escalade
A tiny (183B to 210B) and fast utility to ascend parent directories
With escalade, you can scale parent directories until you've found what you're looking for.
Given an input file or directory, escalade
will continue executing your callback function until either:
the callback returns a truthy value
escalade
has reached the system root directory (eg,/
)
Important: Please note that
escalade
only deals with direct ancestry – it will not dive into parents' sibling directories.
Notice: As of v3.1.0, escalade
now includes Deno support! Please see Deno Usage below.
Install
Modes
There are two "versions" of escalade
available:
"async"
Node.js: >= 8.x Size (gzip): 210 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): 183 bytes Availability: CommonJS, ES Module
This is the opt-in mode, ideal for scenarios where async
usage cannot be supported.
Usage
Example Structure
Example Usage
Note: To run the above example with "sync" mode, import from
escalade/sync
and remove theawait
keyword.
API
escalade(input, callback)
Returns: string|void
or Promise<string|void>
When your callback
locates a file, escalade
will resolve/return with an absolute path.
If your callback
was never satisfied, then escalade
will resolve/return with nothing (undefined).
Important: The
sync
andasync
versions share the same API. The only difference is thatsync
is not Promise-based.
input
Type: string
The path from which to start ascending.
This may be a file or a directory path.
However, when input
is a file, escalade
will begin with its parent directory.
Important: Unless given an absolute path,
input
will be resolved fromprocess.cwd()
location.
callback
Type: Function
The callback to execute for each ancestry level. It always is given two arguments:
dir
- an absolute path of the current parent directorynames
- a list (string[]
) of contents relative to thedir
parent
Note: The
names
list can contain names of files and directories.
When your callback returns a falsey value, then escalade
will continue with dir
's parent directory, re-invoking your callback with new argument values.
When your callback returns a string, then escalade
stops iteration immediately.
If the string is an absolute path, then it's left as is. Otherwise, the string is resolved into an absolute path from the dir
that housed the satisfying condition.
Important: Your
callback
can be aPromise/AsyncFunction
when using the "async" version ofescalade
.
Benchmarks
Running on Node.js v10.13.0
Deno
As of v3.1.0, escalade
is available on the Deno registry.
Please note that the API is identical and that there are still two modes from which to choose:
Important: The
allow-read
permission is required!
Related
premove - A tiny (247B) utility to remove items recursively
totalist - A tiny (195B to 224B) utility to recursively list all (total) files in a directory
mk-dirs - A tiny (420B) utility to make a directory and its parents, recursively
License
MIT © Luke Edwards
Last updated