Nebulous Puffy Marshmallows
    Wondering what’s next for npm?Check out our public roadmap! »

    os-paths
    TypeScript icon, indicating that this package has built-in type declarations

    6.9.0 • Public • Published

    os-paths

    Determine common OS/platform paths (home, temp, ...)

    Build status (GHA) Build status (Travis-CI) Build status (AppVeyor) Coverage status License Style Guide  
    Repository Deno version NPM version NodeJS version npmJS Downloads JSDelivr Downloads

    Installation (CJS/ESM/TypeScript)

    npm install os-paths
    # or... `npm install "git:github.com/rivy/js.os-paths"`
    # or... `npm install "git:github.com/rivy/js.os-paths#v6.3.0"`
    # or... `npm install "https://cdn.jsdelivr.net/gh/rivy/js.os-paths/dist/os-paths.tgz"`

    Usage

    CommonJS (CJS)

    const osPaths = require('os-paths/cjs');
    const home = osPaths.home();
    const temp = osPaths.temp();

    ECMAScript (ESM)/TypeScript

    import osPaths from 'os-paths';
    const home = osPaths.home();
    const temp = osPaths.temp();

    Deno

    import osPaths from 'https://deno.land/x/os_paths/src/mod.deno.ts';
    //or...
    //import osPaths from 'https://deno.land/x/os_paths@v6.3.0/src/mod.deno.ts';
    //or (via CDN, with optional version/version-range/latest/commit support)...
    //import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths@6.3.0/src/mod.deno.ts'; // v6.3.0
    //import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths@6/src/mod.deno.ts'; // v6.x.y
    //import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths/src/mod.deno.ts'; // latest
    //import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths@latest/src/mod.deno.ts'; // latest
    //import osPaths from 'https://cdn.jsdelivr.net/gh/rivy/js.os-paths@COMMIT/src/mod.deno.ts'; // commit
    const home = osPaths.home();
    const temp = osPaths.temp();
    Required Deno permissions
    --allow-env · allow access to the process environment variables

    This module/package requires access to various environment variable to determine platform configuration (eg, location of temp and user directories).

    API

    Construction/Initialization

    OSPaths()

    const osPaths = require('os-paths/cjs'); // CJS
    //or...
    //import osPaths from 'os-paths'; // ESM/TypeScript
    //import osPaths from 'https://deno.land/x/os_paths/src/mod.deno.ts'; // Deno

    When importing this module, the object returned is a function object, OSPaths, augmented with attached methods. Additional OSPaths objects may be constructed by direct call of the imported OSPaths object (eg, const p = osPaths()) or by using new (eg, const p = new osPaths()). Notably, since the OSPaths object contains no instance state, all OSPaths objects will be functionally identical.

    Methods

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

    The returned 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 path string of the user's home directory (or undefined if the user's home directory is not resolvable).
    console.log(osPaths.home());
    //(*nix) => '/home/rivy
    //(windows) =>  'C:\Users\rivy'

    osPaths.temp(): string

    • Returns the path string of the system's default directory for temporary files.
    console.log(osPaths.temp());
    //(*nix) => '/tmp'
    //(windows) =>  'C:\Users\rivy\AppData\Local\Temp'

    temp() will always return a non-empty path string (as sanely as possible).

    Supported Platforms

    NodeJS

    Requirements

    NodeJS >= 4.0[^*]

    [^*]: 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+.

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

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

    const osPaths = require('os-paths/cjs');
    console.log(osPaths.home());
    console.log(osPaths.temp());

    Note: for CJS, require('os-paths') is supported for backward-compatibility and will execute correctly at run-time. However, require('os-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('os-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 v6.0+.

    OSPaths fully supports ESM imports.

    import osPaths from 'os-paths';
    console.log(osPaths.home());
    console.log(osPaths.temp());

    TypeScript (*.ts)

    • Requires v5.0+.

    As of 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

    • Requires v6.0+.

    OSPaths also fully supports use by Deno.

    import osPaths from 'https://deno.land/x/os_paths/src/mod.deno.ts';
    console.log(osPaths.home());
    console.log(osPaths.temp());

    Building and Contributing

    Repository Build status (GHA) Build status (Travis-CI) Build status (AppVeyor) Coverage status  
    Quality status (Codacy) Quality status (CodeClimate) Quality status (CodeFactor)

    Build requirements

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

    optional

    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:editorconfig   check for EditorConfig format flaws (using `editorconfig-checker`)
    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 [alias: 'dist']
    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

    License

    MIT © Roy Ivy III

    Install

    npm i os-paths

    DownloadsWeekly Downloads

    405

    Version

    6.9.0

    License

    MIT

    Unpacked Size

    94.9 kB

    Total Files

    14

    Last publish

    Collaborators

    • avatar