scorta
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:
- Echo the value of
process.env.CACHE_DIR
if defined and truthy - Traverse parent directories until a
package.json
file is found - If a
package.json
was found, return anode_modules/.cache/{name}
path only if it's not read-only - All other cases return a
fallback
, which is eitherundefined
or aos.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 ;; const fixtures = ; await ;//=> "/example/demo/node_modules/.cache/hello" await ;//=> undefined await ;//=> "/var/folders/77/hdmgkj_x2l7454w0y5lwv2l80000gn/T"
Note: To run the above example with "sync" mode, import from
scorta/sync
& remove theawait
s.
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:
Thesync
andasync
versions share the same API.
The only difference is thatsync
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 ;//=> /.../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