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

    1.0.0 • Public • Published

    scorta CI codecov

    A tiny (330B to 357B) and fast utility to find a module's hidden supply / cache directory.

    With scorta, you can locate a module's private .cache directory by name. This is a common practice among many popular libraries, including AVA, nyc, Babel, etc.

    # Others 
    ./node_modules/.cache/ava
    ./node_modules/.cache/babel
    ./node_modules/.cache/nyc
    # Yours! 
    ./node_modules/.cache/hello-world

    When searching, the following steps are taken:

    1. Echo the value of process.env.CACHE_DIR if defined and truthy
    2. Traverse parent directories until a package.json file is found
    3. If a package.json was found, return a node_modules/.cache/{name} path only if it's not read-only
    4. All other cases return a fallback, which is either undefined or a os.tmpdir value

    Why "scorta"? It's Italian for a stock or a supply, which is generally the purpose for a .cache directory.

    Install

    $ npm install --save scorta
    

    Modes

    There are two "versions" of scorta available:

    "async"

    Node.js: >= 8.x
    Size (gzip): 357 bytes
    Availability: CommonJS, ES Module

    This is the primary/default mode. It makes use of async/await and util.promisify.

    "sync"

    Node.js: >= 6.x
    Size (gzip): 330 bytes
    Availability: CommonJS, ES Module

    This is the opt-in mode, ideal for scenarios where async usage cannot be supported.

    Usage

    Example Structure

    /example
      ├── fixtures
        └── empty.js
      └── demo
        └── node_modules/...
        └── package.json
        └── index.js
    

    Example Usage

    // demo/index.js
     
    import { join } from 'path';
    import { scorta } from 'scorta';
     
    const fixtures = join(__dirname, '..', 'fixtures');
     
    await scorta('hello');
    //=> "/example/demo/node_modules/.cache/hello"
     
    await scorta('hello', { cwd: fixtures });
    //=> undefined
     
    await scorta('hello', { cwd: fixtures, tmpdir: true });
    //=> "/var/folders/77/hdmgkj_x2l7454w0y5lwv2l80000gn/T"

    Note: To run the above example with "sync" mode, import from scorta/sync & remove the awaits.

    API

    scorta(name, options)

    Returns: Promise<string|void> or string|void

    When scorta locates a valid directory, the value will always be an absolute path (string).

    However, if scorta cannot locate a valid, writable directory, then the return value is undefined by default. However, this can be changed via the tmpdir option.

    Important:
    The sync and async versions share the same API.
    The only difference is that sync is not Promise-based.

    name

    Type: string

    The target module's name.

    This value is used to construct the final .cache directory path. For example:

    await scorta('hello');
    //=> /.../node_modules/.cache/hello

    options.cwd

    Type: string
    Default: .

    The directory where path resolution should begin. Defauls to the process.cwd() – aka, the directory that your process is run within.

    options.tmpdir

    Type: boolean
    Default: false

    When truthy, scorta will return a os.tmpdir() value instead of undefined.

    Important: When this option is in use, scorta always yields a string!

    Benchmarks

    Running on Node.js v10.13.0

    # Load Time
      find-cache-dir  11.628ms
      scorta           1.326ms
      scorta/sync      0.508ms
    
    # Levels: 0 (target = "foo"):
      find-cache-dir   x 10,700 ops/sec ±0.55% (82 runs sampled)
      scorta/sync      x 11,060 ops/sec ±0.83% (88 runs sampled)
      scorta           x 80,804 ops/sec ±2.22% (74 runs sampled)
    
    # Levels: 6 (target = "bar"):
      find-cache-dir   x  2,107 ops/sec ±0.42% (89 runs sampled)
      scorta/sync      x  5,507 ops/sec ±0.46% (91 runs sampled)
      scorta           x 78,593 ops/sec ±4.03% (79 runs sampled)
    
    # Levels: 11 (target = "baz"):
      find-cache-dir   x  1,377 ops/sec ±0.36% (93 runs sampled)
      scorta/sync      x  3,892 ops/sec ±0.25% (95 runs sampled)
      scorta           x 76,641 ops/sec ±6.92% (68 runs sampled)
    

    Related

    • escalade - A tiny (183B to 210B) utility to ascend parent directories
    • totalist - A tiny (195B to 224B) utility to recursively list all (total) files in a directory
    • mk-dirs - A tiny (380B to 420B) utility to make a directory and its parents, recursively

    License

    MIT © Luke Edwards

    Install

    npm i scorta

    DownloadsWeekly Downloads

    290

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    11.2 kB

    Total Files

    9

    Last publish

    Collaborators

    • lukeed