sourav-das/stem-separator

1# escalade [![CI](https://github.com/lukeed/escalade/workflows/CI/badge.svg)](https://github.com/lukeed/escalade/actions) [![licenses](https://licenses.dev/b/npm/escalade)](https://licenses.dev/npm/escalade) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/escalade)](https://codecov.io/gh/lukeed/escalade)2 3> A tiny (183B to 210B) and [fast](#benchmarks) utility to ascend parent directories4 5With [escalade](https://en.wikipedia.org/wiki/Escalade), you can scale parent directories until you've found what you're looking for.<br>Given an input file or directory, `escalade` will continue executing your callback function until either:6 71) the callback returns a truthy value82) `escalade` has reached the system root directory (eg, `/`)9 10> **Important:**<br>Please note that `escalade` only deals with direct ancestry – it will not dive into parents' sibling directories.11 12---13 14**Notice:** As of v3.1.0, `escalade` now includes [Deno support](http://deno.land/x/escalade)! Please see [Deno Usage](#deno) below.15 16---17 18## Install19 20```21$ npm install --save escalade22```23 24 25## Modes26 27There are two "versions" of `escalade` available:28 29#### "async"30> **Node.js:** >= 8.x<br>31> **Size (gzip):** 210 bytes<br>32> **Availability:** [CommonJS](https://unpkg.com/escalade/dist/index.js), [ES Module](https://unpkg.com/escalade/dist/index.mjs)33 34This is the primary/default mode. It makes use of `async`/`await` and [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original).35 36#### "sync"37> **Node.js:** >= 6.x<br>38> **Size (gzip):** 183 bytes<br>39> **Availability:** [CommonJS](https://unpkg.com/escalade/sync/index.js), [ES Module](https://unpkg.com/escalade/sync/index.mjs)40 41This is the opt-in mode, ideal for scenarios where `async` usage cannot be supported.42 43 44## Usage45 46***Example Structure***47 48```49/Users/lukeed50  └── oss51    ├── license52    └── escalade53      ├── package.json54      └── test55        └── fixtures56          ├── index.js57          └── foobar58            └── demo.js59```60 61***Example Usage***62 63```js64//~> demo.js65import { join } from 'path';66import escalade from 'escalade';67 68const input = join(__dirname, 'demo.js');69// or: const input = __dirname;70 71const pkg = await escalade(input, (dir, names) => {72  console.log('~> dir:', dir);73  console.log('~> names:', names);74  console.log('---');75 76  if (names.includes('package.json')) {77    // will be resolved into absolute78    return 'package.json';79  }80});81 82//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar83//~> names: ['demo.js']84//---85//~> dir: /Users/lukeed/oss/escalade/test/fixtures86//~> names: ['index.js', 'foobar']87//---88//~> dir: /Users/lukeed/oss/escalade/test89//~> names: ['fixtures']90//---91//~> dir: /Users/lukeed/oss/escalade92//~> names: ['package.json', 'test']93//---94 95console.log(pkg);96//=> /Users/lukeed/oss/escalade/package.json97 98// Now search for "missing123.txt"99// (Assume it doesn't exist anywhere!)100const missing = await escalade(input, (dir, names) => {101  console.log('~> dir:', dir);102  return names.includes('missing123.txt') && 'missing123.txt';103});104 105//~> dir: /Users/lukeed/oss/escalade/test/fixtures/foobar106//~> dir: /Users/lukeed/oss/escalade/test/fixtures107//~> dir: /Users/lukeed/oss/escalade/test108//~> dir: /Users/lukeed/oss/escalade109//~> dir: /Users/lukeed/oss110//~> dir: /Users/lukeed111//~> dir: /Users112//~> dir: /113 114console.log(missing);115//=> undefined116```117 118> **Note:** To run the above example with "sync" mode, import from `escalade/sync` and remove the `await` keyword.119 120 121## API122 123### escalade(input, callback)124Returns: `string|void` or `Promise<string|void>`125 126When your `callback` locates a file, `escalade` will resolve/return with an absolute path.<br>127If your `callback` was never satisfied, then `escalade` will resolve/return with nothing (undefined).128 129> **Important:**<br>The `sync` and `async` versions share the same API.<br>The **only** difference is that `sync` is not Promise-based.130 131#### input132Type: `string`133 134The path from which to start ascending.135 136This may be a file or a directory path.<br>However, when `input` is a file, `escalade` will begin with its parent directory.137 138> **Important:** Unless given an absolute path, `input` will be resolved from `process.cwd()` location.139 140#### callback141Type: `Function`142 143The callback to execute for each ancestry level. It always is given two arguments:144 1451) `dir` - an absolute path of the current parent directory1462) `names` - a list (`string[]`) of contents _relative to_ the `dir` parent147 148> **Note:** The `names` list can contain names of files _and_ directories.149 150When your callback returns a _falsey_ value, then `escalade` will continue with `dir`'s parent directory, re-invoking your callback with new argument values.151 152When your callback returns a string, then `escalade` stops iteration immediately.<br>153If 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.154 155> **Important:** Your `callback` can be a `Promise/AsyncFunction` when using the "async" version of `escalade`.156 157## Benchmarks158 159> Running on Node.js v10.13.0160 161```162# Load Time163  find-up         3.891ms164  escalade        0.485ms165  escalade/sync   0.309ms166 167# Levels: 6 (target = "foo.txt"):168  find-up          x 24,856 ops/sec ±6.46% (55 runs sampled)169  escalade         x 73,084 ops/sec ±4.23% (73 runs sampled)170  find-up.sync     x  3,663 ops/sec ±1.12% (83 runs sampled)171  escalade/sync    x  9,360 ops/sec ±0.62% (88 runs sampled)172 173# Levels: 12 (target = "package.json"):174  find-up          x 29,300 ops/sec ±10.68% (70 runs sampled)175  escalade         x 73,685 ops/sec ± 5.66% (66 runs sampled)176  find-up.sync     x  1,707 ops/sec ± 0.58% (91 runs sampled)177  escalade/sync    x  4,667 ops/sec ± 0.68% (94 runs sampled)178 179# Levels: 18 (target = "missing123.txt"):180  find-up          x 21,818 ops/sec ±17.37% (14 runs sampled)181  escalade         x 67,101 ops/sec ±21.60% (20 runs sampled)182  find-up.sync     x  1,037 ops/sec ± 2.86% (88 runs sampled)183  escalade/sync    x  1,248 ops/sec ± 0.50% (93 runs sampled)184```185 186## Deno187 188As of v3.1.0, `escalade` is available on the Deno registry.189 190Please note that the [API](#api) is identical and that there are still [two modes](#modes) from which to choose:191 192```ts193// Choose "async" mode194import escalade from 'https://deno.land/escalade/async.ts';195 196// Choose "sync" mode197import escalade from 'https://deno.land/escalade/sync.ts';198```199 200> **Important:** The `allow-read` permission is required!201 202 203## Related204 205- [premove](https://github.com/lukeed/premove) - A tiny (247B) utility to remove items recursively206- [totalist](https://github.com/lukeed/totalist) - A tiny (195B to 224B) utility to recursively list all (total) files in a directory207- [mk-dirs](https://github.com/lukeed/mk-dirs) - A tiny (420B) utility to make a directory and its parents, recursively208 209## License210 211MIT © [Luke Edwards](https://lukeed.com)212