os-paths

os-paths

Generate portable common OS paths (home, temp, ...)

 

Installation

npm install os-paths
# or... `npm install github:rivy/js.os-paths`
# or... `npm install "https://cdn.jsdelivr.net/gh/rivy/js.os-paths@latest/dist/os-paths.tgz"`

Usage

const osPaths = require('os-paths');

osPaths.home();
//(*nix) => '/home/rivy'
//(win)  => 'C:\Users\rivy'

osPaths.temp();
//(*nix) => '/tmp'
//(win)  => 'C:\Windows\temp'

API

Initialization

require('os-paths'): OSPaths()

const osPaths = require('os-paths');

The object returned by the module constructor is a function object, OSPaths, augmented with attached methods. When this object is called directly (eg, const p = osPaths()), it returns another newly constructed OSPaths object. Since the OSPaths object contains no instance state, all constructed objects will be functionally identical.

Methods

All module methods return simple, platform-compatible, path strings which are normalized and have no trailing path separators.

The path strings are not guaranteed to already exist on the file system. So, the user is responsible for directory construction, if/when needed. However, since all of these are standard OS directories, they should all exist without the need for user intervention.

If/when necessary, make-dir or mkdirp can be used to create the directories.

osPaths.home(): string | undefined

• Returns the home directory for user (or undefined)

undefined is returned if the home directory is not resolvable.

osPaths.temp(): string

• Returns the directory for temporary files

Always returns a non-empty path (as sanely as possible).

Discussion

XDG

All XDG-related methods have been relocated to the xdg-portable and xdg-app-paths modules.

Supported Platforms

NodeJS

Requirements

NodeJS >= 4.0¹

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

CJS is the basic supported output (back to versions as early as NodeJS-v4).

const osPaths = require('os-paths');

console.log(osPaths.home());
console.log(osPaths.temp());

ECMAScript modules (ESM; *.mjs)

OSPaths fully supports ESM imports.

import osPaths from 'os-paths';

console.log(osPaths.home());
console.log(osPaths.temp());

TypeScript (*.ts)

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

Deno

OSPaths also fully supports use by Deno.

import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths@latest/src/mod.deno.ts';

console.log(osPaths.home());
console.log(osPaths.temp());

Building and Contributing

 

Build requirements

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

optional

• git-changelog ... enables changelog automation

Build/test

npm install-test

Project development scripts

> npm run help
...
usage: `npm run TARGET` or `npx run-s TARGET [TARGET..]`

TARGETs:

build               build/compile package
clean               remove build artifacts
coverage            calculate and display (or send) code coverage [alias: 'cov']
fix                 fix package issues (automated/non-interactive)
fix:lint            fix ESLint issues
fix:style           fix Prettier formatting issues
help                display help
lint                check for package code 'lint'
lint:commits        check for commit flaws (using `commitlint` and `cspell`)
lint:lint           check for code 'lint' (using `eslint`)
lint:markdown       check for markdown errors (using `remark`)
lint:spell          check for spelling errors (using `cspell`)
lint:style          check for format imperfections (using `prettier`)
realclean           remove all generated files
rebuild             clean and (re-)build project
retest              clean and (re-)test project
reset:hard          remove *all* generated files and reinstall dependencies
show:deps           show package dependencies
test                test package
test:code           test package code
test:types          test for type declaration errors (using `tsd`)
update              update/prepare for distribution
update:changelog    update CHANGELOG (using `git changelog ...`)
update:dist         update distribution content

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-app-paths ... easy XDG for applications
• xdg-portable ... XDG Base Directory paths (cross-platform)

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+. ↩