xdg-app-paths

Determine (XDG-compatible) paths for storing application files (cache, config, data, etc)

 

Installation (CJS/ESM/TypeScript)

1npm install xdg-app-paths
2# or... `npm install "git:github.com/rivy/js.xdg-app-paths"`
3# or... `npm install "git:github.com/rivy/js.xdg-app-paths#v8.3.0"`
4# or... `npm install "https://cdn.jsdelivr.net/gh/rivy/js.xdg-app-paths@v8.3.0/dist/xdg-app-paths.tgz"`
5# or... `npm install "https://cdn.jsdelivr.net/gh/rivy/js.xdg-app-paths@COMMIT_SHA/dist/xdg-app-paths.tgz"`

Usage

CommonJS (CJS)

1// MyApp.js
2const xdgAppPaths = require('xdg-app-paths/cjs');
3
4const cache = xdgAppPaths.cache();
5//(nix)=> '/home/rivy/.cache/MyApp.js'
6//(win)=> 'C:\\Users\\rivy\\AppData\\Local\\MyApp\\Cache'
7
8const config = xdgAppPaths.config();
9//(nix)=> '/home/rivy/.config/MyApp.js'
10//(win)=> 'C:\\Users\\rivy\\AppData\\Roaming\\MyApp\\Config'
11
12const data = xdgAppPaths.data();
13//(nix)=> '/home/rivy/.local/share/MyApp.js'
14//(win)=> 'C:\\Users\\rivy\\AppData\\Roaming\\MyApp\\Data'

ECMAScript (ESM)/TypeScript

1import xdgAppPaths from 'xdg-app-paths';
2const configDirs = xdgAppPaths.configDirs();
3//...

Deno

1import xdgAppPaths from 'https://deno.land/x/xdg_app_paths@v8.3.0/src/mod.deno.ts';
2//or (via CDN, [ie, JSDelivr with GitHub version/version-range, commit, 'latest' support])...
3//import xdgAppPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.xdg-app-paths@v8.3.0/src/mod.deno.ts';
4//import xdgAppPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.xdg-app-paths@COMMIT_SHA/src/mod.deno.ts';
5const configDirs = xdgAppPaths.configDirs();
6//...

API

Construction/Initialization

XDGAppPaths( Options? )

1// CJS
2const xdgAppPaths = require('xdg-app-paths/cjs');
3// or ...
4const xdgAppPaths = require('xdg-app-paths/cjs')(options);
5
6// ESM/TypeScript
7import xdgAppPaths from 'xdg-app-paths';
8// or ...
9import XDGAppPaths from 'xdg-app-paths';
10const xdgAppPaths = XDGAppPaths(options);
11
12// Deno
13import xdgAppPaths from 'https://deno.land/x/xdg_app_paths/src/mod.deno.ts';
14// or ...
15import XDGAppPaths from 'https://deno.land/x/xdg_app_paths/src/mod.deno.ts';
16const xdgAppPaths = XDGAppPaths(options);

When importing this module, the object returned is a function object, XDGAppPaths, augmented with attached methods. Additional XDGAppPaths objects may be constructed by direct call of the imported XDGAppPaths object (eg, const x = xdgAppPaths(...)) or by using new (eg, const x = new xdgAppPaths(...)).

Upon construction, if not supplied with a specified name (via Options.name), XDGAppPaths will generate an application name which is used to further generate isolated application directories, where needed. "$eval" is used as the fallback value when automatically generating names (ie, for immediate mode scripts such as node -e "..."). The generated or supplied name is stored during XDGAppPaths construction and subsequently accessible via the $name() method.

Interfaces/Types

1import type { DirOptions, Options, XDGAppPaths } from 'xdg-app-paths'; // TypeScript
2//or...
3//import type { DirOptions, Options, XDGAppPaths } from 'https://deno.land/x/xdg_app_paths/src/mod.deno.ts'; // Deno

XDGAppPaths

XDGAppPaths API; also, the interface/type of the default function object export

---

DirOptions

Configuration options supplied to XDGAppPaths methods

DirOptions: boolean => { isolated: boolean }
As a shortcut, when DirOptions is supplied as a boolean, it is directly interpreted as the isolated property (ie, dirOptions = { isolated: dirOptions }).

---

DirOptions: object
• default = { isolated: true }

DirOptions.isolated: boolean
• default = true
Isolation flag; used to override the default isolation mode, when needed

Options

Configuration options supplied when constructing XDGAppPaths

Options: string => { name: string }
As a shortcut, when Options is supplied as a string, is interpreted directly as the name property (ie, options = { name: options }).

---

Options: object
• default = { name: '', suffix: '', isolated: true }

Options.name: string
• default = ''
Name of the application; used to generate isolated application paths
When missing (undefined, null, or empty ('')), it is generated automatically from the process main file name, where determinable. '$eval' is used as a final fallback value when the application name cannot otherwise be determined. Note, Deno reports '$deno$eval' as the main file name when executing deno eval ....

Options.suffix: string
• default = ''
Suffix which is appended to the application name when generating the application paths

Options.isolated: boolean
• default = true
Default isolation flag (used when no isolation flag is supplied for DirOptions)

All interfaces/types listed are exported individually by name (eg, as "XDGAppPaths").

Methods

All returned path strings are simple, platform-compatible, strings and are not guaranteed to exist. The application is responsible for construction of the directories. If needed, make-dir or mkdirp can be used to create the directories.

xdgAppPaths.cache( DirOptions? ): string

Returns the directory for non-essential data files

Deletion of the data contained here might cause an application to slow down.

xdgAppPaths.config( DirOptions? ): string

Returns the directory for config files

Deletion of the data contained here might require the user to reconfigure an application.

xdgAppPaths.data( DirOptions? ): string

Returns the directory for data files

Deletion of the data contained here might force the user to restore from backups.

xdgAppPaths.runtime( DirOptions? ): string?

Returns the directory for runtime files; may return undefined

Deletion of the data contained here might interfere with a currently executing application but should have no effect on future executions.

xdgAppPaths.state( DirOptions? ): string

Returns the directory for state files

Deletion of the data contained here should not materially interfere with execution of an application.

xdgAppPaths.configDirs( DirOptions? ): readonly string[]

Returns a priority-sorted list of possible directories for configuration file storage (includes paths.config() as the first entry)

xdgAppPaths.dataDirs( DirOptions? ): readonly string[]

Returns a priority-sorted list of possible directories for data file storage (includes paths.data() as the first entry)

xdgAppPaths.$name(): string

Application name used for path construction (from supplied configuration or auto-generated)

xdgAppPaths.$isolated(): boolean

Default isolation mode used by the particular XDGAppPaths instance

Example

1// MyApp.js
2const locatePath = require('locate-path');
3const mkdirp = require('mkdirp');
4const path = require('path');
5
6const xdgAppPaths = require('xdg-app-paths/cjs');
7// Extend appPaths with a "log" location function
8xdgAppPaths.log = function (dirOptions) {
9  const self = xdgAppPaths; // * bind `self` to `xdgAppPaths` => avoids `this` variability due to caller context
10  function typeOf(x) {
11    // use avoids circumvention of eslint variable tracking for `x`
12    return typeof x;
13  }
14
15  if (typeOf(dirOptions) === 'boolean') {
16    dirOptions = { isolated: dirOptions };
17  }
18
19  if (
20    typeOf(dirOptions) !== 'object' ||
21    dirOptions === null ||
22    typeOf(dirOptions.isolated) !== 'boolean'
23  ) {
24    dirOptions = { isolated: self.$isolated() };
25  }
26
27  return path.join(self.state(dirOptions), (dirOptions.isolated ? '' : self.$name() + '-') + 'log');
28};
29
30// log file
31const logPath = path.join(xdgAppPaths.log(), 'debug.txt');
32mkdirp.sync(path.dirname(logPath), 0o700);
33
34// config file
35// * search for config file within user preferred directories; otherwise, use preferred directory
36const possibleConfigPaths = xdgAppPaths
37  .configDirs()
38  .concat(xdgAppPaths.configDirs({ isolated: !xdgAppPaths.$isolated() }))
39  .map((v) => path.join(v, xdgAppPaths.$name() + '.json'));
40const configPath = locatePath.sync(possibleConfigPaths) || possibleConfigPaths[0];
41// debug(logPath, 'configPath="%s"', configPath);
42mkdirp.sync(path.dirname(configPath), 0o700);
43
44// cache file
45const cacheDir = path.join(xdgAppPaths.cache());
46// debug(logPath, 'cacheDir="%s"', cacheDir);
47mkdirp.sync(cacheDir, 0o700);
48const cachePath = {};
49cachePath.orders = path.join(cacheDir, 'orders.json');
50cachePath.customers = path.join(cacheDir, 'customers.json');
51//...

Supported Platforms

NodeJS

Requirements

NodeJS >= 4.0¹

CommonJS modules (CJS; *.js and *.cjs)

CJS is the basic supported output (with support for NodeJS versions as early as NodeJS-v4).

1const xdgAppPaths = require('xdg-app-paths/cjs');
2console.log(xdgAppPaths.config());

Note: for CJS, require('xdg-app-paths') is supported for backward-compatibility and will execute correctly at run-time. However, require('xdg-app-paths') links to the default package type declarations which, though correct for Deno/ESM/TypeScript, are incorrect for CJS. This, then, leads to incorrect analysis of CJS files by static analysis tools such as TypeScript and Intellisense.

Using require('xdg-app-paths/cjs') is preferred as it associates the proper CJS type declarations and provides correct information to static analysis tools.

ECMAScript modules (ESM; *.mjs)

• Requires XDGAppPaths v6.0+.

XDGAppPaths fully supports ESM imports.

1import xdgAppPaths from 'xdg-app-paths';
2console.log(xdgAppPaths.config());

TypeScript (*.ts)

• Requires XDGAppPaths v6.0+.

As of v6.0+, XDGAppPaths has been converted to a TypeScript-based module. As a consequence, TypeScript type definitions are automatically generated, bundled, and exported by the module.

Deno

Requirements

Deno >= v1.8.0²

Required Permissions

• --allow-env · allow access to the process environment variables
  This is a transitive requirement from the 'xdg'/'xdg-portable' module; XDG requires access to various environment variable to determine platform and user configuration (eg, XDG configuration variables, location of temp and user directories, ...).
• --allow-read · allow read(-only) access to the file system
  This permission is required to use Deno.mainModule, which is, in turn, required to auto-generate the application name used for data isolation.

• Requires XDGAppPaths v7.0+.

XDGAppPaths also fully supports use by Deno.

1import xdgAppPaths from 'https://deno.land/x/xdg_app_paths/src/mod.deno.ts';
2console.log(xdgAppPaths.config());

Discussion

The XDG Base Directory Specification^­@ defines categories of user information (ie, "cache", "config", "data", ...), defines their standard storage locations, and defines the standard process for user configuration of those locations (using XDG_CACHE_HOME, etc).

Applications supporting the XDG convention are expected to store user-specific files within these locations, either within the common/shared directory (eg, `${xdg.cache()}/filename`) or within a more isolated application-defined subdirectory (eg, `${xdg.config()}/DIR/filename`; DIR usually being the application name).

Windows ("win32") specific notes

Windows has an alternate convention, offering just two standard locations for applications to persist data, either %APPDATA% (for files which may "roam" with the user between hosts) and %LOCALAPPDATA% (for local-machine-only files). All application files are expected to be stored within an application-unique subdirectory in one of those two locations, usually under a directory matching the application name. There is no further popular convention used to segregate the file types (ie, into "cache", "config", ...) in any way similar to the XDG specification.

So, to support basic XDG-like behavior (that is, segregating the information types into type-specific directories), this module supports a new convention for Windows hosts (taken from xdg-portable), placing the specific types of files into subdirectories under either %APPDATA% or %LOCALAPPDATA%, as appropriate for the file type. The default directories used for the windows platform are listed by xdg-portable.

By default, this module returns paths which are isolated, application-specific sub-directories under the respective common/shared base directories. These sub-directories are purely dedicated to use by the application. If, however, the application requires access to the common/shared areas, the isolated: false option may be used during initialization (or as an optional override for specific function calls) to generate and return the common/shared paths. Note, that when using the command/shared directories, take care to use file names which do not collide with those used by other applications.

Origins

This module was forked from sindresorhus/env-paths in order to add cross-platform portability and support simpler cross-platform applications.

Building and Contributing

 

Build requirements

• NodeJS >= 10.14
• a JavaScript package/project manager (npm or yarn)
• git

optional

• bmp (v0.0.6+) ... synchronizes version strings within the project
• git-changelog (v1.1+) ... enables changelog automation

Quick build/test

1npm install-test

Contributions/development

Reproducible setup (for CI or local development)

1git clone "https://github.com/rivy/js.xdg-app-paths"
2cd js.xdg-app-paths
3# * note: for WinOS, replace `cp` with `copy` (or use [uutils](https://github.com/uutils/coreutils))
4# npm
5cp .deps-lock/package-lock.json .
6npm clean-install
7# yarn
8cp .deps-lock/yarn.lock .
9yarn --immutable --immutable-cache --check-cache

Project development scripts

1> npm run help
2...
3usage: `npm run TARGET` or `npx run-s TARGET [TARGET..]`
4
5TARGETs:
6
7build               build/compile package
8clean               remove build artifacts
9coverage            calculate and display (or send) code coverage [alias: 'cov']
10fix                 fix package issues (automated/non-interactive)
11fix:lint            fix ESLint issues
12fix:style           fix Prettier formatting issues
13help                display help
14lint                check for package code 'lint'
15lint:audit          check for `npm audit` violations in project code
16lint:commits        check for commit flaws (using `commitlint` and `cspell`)
17lint:editorconfig   check for EditorConfig format flaws (using `editorconfig-checker`)
18lint:lint           check for code 'lint' (using `eslint`)
19lint:markdown       check for markdown errors (using `remark`)
20lint:spell          check for spelling errors (using `cspell`)
21lint:style          check for format imperfections (using `prettier`)
22prerelease          clean, rebuild, and fully test (useful prior to publish/release)
23realclean           remove all generated files
24rebuild             clean and (re-)build project
25refresh             clean and rebuild/regenerate all project artifacts
26refresh:dist        clean, rebuild, and regenerate project distribution
27retest              clean and (re-)test project
28reset:hard          remove *all* generated files and reinstall dependencies
29show:deps           show package dependencies
30test                test package
31test:code           test package code (use `--test-code=...` to pass options to testing harness)
32test:types          test for type declaration errors (using `tsd`)
33update              update/prepare for distribution [alias: 'dist']
34update:changelog    update CHANGELOG (using `git changelog ...`)
35update:dist         update distribution content
36verify              fully (and verbosely) test package

Packaging & Publishing

Package

1#=== * POSIX
2# update project VERSION strings (package.json,...)
3# * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format
4bmp --minor
5VERSION=$(cat VERSION)
6git-changelog --next-tag "v${VERSION}" > CHANGELOG.mkd
7# create/commit updates and distribution
8git add package.json CHANGELOG.mkd README.md VERSION .bmp.yml
9git commit -m "${VERSION}"
10npm run clean && npm run update:dist && git add dist && git commit --amend --no-edit
11# (optional) update/save dependency locks
12# * note: `yarn import` of 'package-lock.json' (when available) is faster but may not work for later versions of 'package-lock.json'
13rm -f package-lock.json yarn.lock
14npm install --package-lock
15yarn install
16mkdir .deps-lock 2> /dev/null
17cp package-lock.json .deps-lock/
18cp yarn.lock .deps-lock/
19git add .deps-lock
20git commit --amend --no-edit
21# tag VERSION commit
22git tag -f "v${VERSION}"
23# (optional) prerelease checkup
24npm run prerelease
25#=== * WinOS
26@rem # update project VERSION strings (package.json,...)
27@rem # * `bmp --[major|minor|patch]`; next VERSION in M.m.r (semver) format
28bmp --minor
29for /f %G in (VERSION) do @set "VERSION=%G"
30git-changelog --next-tag "v%VERSION%" > CHANGELOG.mkd
31@rem # create/commit updates and distribution
32git add package.json CHANGELOG.mkd README.md VERSION .bmp.yml
33git commit -m "%VERSION%"
34npm run clean && npm run update:dist && git add dist && git commit --amend --no-edit
35@rem # (optional) update/save dependency locks
36@rem # * note: `yarn import` of 'package-lock.json' (when available) is faster but may not work for later versions of 'package-lock.json'
37del package-lock.json yarn.lock 2>NUL
38npm install --package-lock
39yarn install
40mkdir .deps-lock 2>NUL
41copy /y package-lock.json .deps-lock >NUL
42copy /y yarn.lock .deps-lock >NUL
43git add .deps-lock
44git commit --amend --no-edit
45@rem # tag VERSION commit
46git tag -f "v%VERSION%"
47@rem # (optional) prerelease checkup
48npm run prerelease

Publish

1# publish
2# * optional (will be done in 'prePublishOnly' by `npm publish`)
3npm run clean && npm run test && npm run dist && git-changelog > CHANGELOG.mkd #expect exit code == 0
4git diff-index --quiet HEAD || echo "[lint] ERROR uncommitted changes" # expect no output and exit code == 0
5# *
6npm publish # `npm publish --dry-run` will perform all prepublication actions and stop just before the actual publish push
7# * if published to NPMjs with no ERRORs; push to deno.land with tag push
8git push origin --tags

Contributions

Contributions are welcome.

Any pull requests should be based off of the default branch (master). And, whenever possible, please include tests for any new code, ensuring that local (via npm test) and remote CI testing passes.

By contributing to the project, you are agreeing to provide your contributions under the same license as the project itself.

Related

• xdg-portable ... XDG Base Directory paths (cross-platform)
• env-paths ... inspiration for this module

License

MIT © Roy Ivy III

Footnotes

1. With the conversion to a TypeScript-based project, due to tooling constraints, building and testing are more difficult and more limited on Node platforms earlier than NodeJS-v10. However, the generated CommonJS/UMD project code is fully tested (for NodeJS-v10+) and continues to be compatible with NodeJS-v4+. ↩

2. The Deno.permissions API (stabilized in Deno v1.8.0) is required to avoid needless panics or prompts by Deno during static imports of this module/package. Note: Deno v1.3.0+ may be used if the run flag --unstable is also used. ↩