3.4.0 • Published 2 months ago

readdirp v3.4.0

Weekly downloads
18,490,916
License
MIT
Repository
github
Last release
2 months ago

readdirp Weekly downloads

Recursive version of fs.readdir. Exposes a stream API and a promise API.

NPM

npm install readdirp
const readdirp = require('readdirp');

// Use streams to achieve small RAM & CPU footprint.
// 1) Streams example with for-await.
for await (const entry of readdirp('.')) {
  const {path} = entry;
  console.log(`${JSON.stringify({path})}`);
}

// 2) Streams example, non for-await.
// Print out all JS files along with their size within the current folder & subfolders.
readdirp('.', {fileFilter: '*.js', alwaysStat: true})
  .on('data', (entry) => {
    const {path, stats: {size}} = entry;
    console.log(`${JSON.stringify({path, size})}`);
  })
  // Optionally call stream.destroy() in `warn()` in order to abort and cause 'close' to be emitted
  .on('warn', error => console.error('non-fatal error', error))
  .on('error', error => console.error('fatal error', error))
  .on('end', () => console.log('done'));

// 3) Promise example. More RAM and CPU than streams / for-await.
const files = await readdirp.promise('.');
console.log(files.map(file => file.path));

// Other options.
readdirp('test', {
  fileFilter: '*.js',
  directoryFilter: ['!.git', '!*modules']
  // directoryFilter: (di) => di.basename.length === 9
  type: 'files_directories',
  depth: 1
});

For more examples, check out examples directory.

API

const stream = readdirp(root[, options])Stream API

  • Reads given root recursively and returns a stream of entry infos
  • Optionally can be used like for await (const entry of stream) with node.js 10+ (asyncIterator).
  • on('data', (entry) => {}) entry info for every file / dir.
  • on('warn', (error) => {}) non-fatal Error that prevents a file / dir from being processed. Example: inaccessible to the user.
  • on('error', (error) => {}) fatal Error which also ends the stream. Example: illegal options where passed.
  • on('end') — we are done. Called when all entries were found and no more will be emitted.
  • on('close') — stream is destroyed via stream.destroy(). Could be useful if you want to manually abort even on a non fatal error. At that point the stream is no longer readable and no more entries, warning or errors are emitted
  • To learn more about streams, consult the very detailed nodejs streams documentation or the stream-handbook

const entries = await readdirp.promise(root[, options])Promise API. Returns a list of entry infos.

First argument is awalys root, path in which to start reading and recursing into subdirectories.

options

  • fileFilter: ["*.js"]: filter to include or exclude files. A Function, Glob string or Array of glob strings.
    • Function: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry
    • Glob string: a string (e.g., *.js) which is matched using picomatch, so go there for more information. Globstars (**) are not supported since specifying a recursive pattern for an already recursive function doesn't make sense. Negated globs (as explained in the minimatch documentation) are allowed, e.g., !*.txt matches everything but text files.
    • Array of glob strings: either need to be all inclusive or all exclusive (negated) patterns otherwise an error is thrown. ['*.json', '*.js'] includes all JavaScript and Json files. ['!.git', '!node_modules'] includes all directories except the '.git' and 'node_modules'.
    • Directories that do not pass a filter will not be recursed into.
  • directoryFilter: ['!.git']: filter to include/exclude directories found and to recurse into. Directories that do not pass a filter will not be recursed into.
  • depth: 5: depth at which to stop recursing even if more subdirectories are found
  • type: 'files': determines if data events on the stream should be emitted for 'files' (default), 'directories', 'files_directories', or 'all'. Setting to 'all' will also include entries for other types of file descriptors like character devices, unix sockets and named pipes.
  • alwaysStat: false: always return stats property for every file. Setting it to true can double readdir execution time - use it only when you need file size, mtime etc. Cannot be enabled on node <10.10.0.
  • lstat: false: include symlink entries in the stream along with files. When true, fs.lstat would be used instead of fs.stat

EntryInfo

Has the following properties:

  • path: 'assets/javascripts/react.js': path to the file/directory (relative to given root)
  • fullPath: '/Users/dev/projects/app/assets/javascripts/react.js': full path to the file/directory found
  • basename: 'react.js': name of the file/directory
  • dirent: fs.Dirent: built-in dir entry object - only with alwaysStat: false
  • stats: fs.Stats: built in stat object - only with alwaysStat: true

Changelog

  • 3.3 (Dec 6, 2019) stabilizes RAM consumption and enables perf management with highWaterMark option. Fixes race conditions related to for-await looping.
  • 3.2 (Oct 14, 2019) improves performance by 250% and makes streams implementation more idiomatic.
  • 3.1 (Jul 7, 2019) brings bigint support to stat output on Windows. This is backwards-incompatible for some cases. Be careful. It you use it incorrectly, you'll see "TypeError: Cannot mix BigInt and other types, use explicit conversions".
  • 3.0 brings huge performance improvements and stream backpressure support.
  • Upgrading 2.x to 3.x:
    • Signature changed from readdirp(options) to readdirp(root, options)
    • Replaced callback API with promise API.
    • Renamed entryType option to type
    • Renamed entryType: 'both' to 'files_directories'
    • EntryInfo
      • Renamed stat to stats
        • Emitted only when alwaysStat: true
        • dirent is emitted instead of stats by default with alwaysStat: false
      • Renamed name to basename
      • Removed parentDir and fullParentDir properties
  • Supported node.js versions:
    • 3.x: node 8+
    • 2.x: node 0.6+

License

Copyright (c) 2012-2019 Thorsten Lorenz, Paul Miller (https://paulmillr.com)

MIT License, see LICENSE file.

chokidar@neoscrib/express-hbslolli.js@arisageha/react-lazyload@arisageha/react-lazyload-fixshoriponyshow-cli@clangd/installgit-split-branchgit-terminalka-flow.jstranspile-md-to-jsonturbo-clitribble-plugintwofold@itper/chokidar@platform-os/marketplace-kit@platformos/pos-cli@pingy/export@oriduk/ckeditor5-rebuild-oriduk@oriduk/ckeditor5-rebuild-musicanote@ozelot379/convert-minecraft-java-texture-to-bedrock@webscale-oy/bauble@wzlin/cabinet@wsbauble/wsbauble@unlimit/gatewayab-fs-matcheradjectivealbum-exif-analyzerallsomeali18nassemblejsattakap_utilsaxios-retry-anoaxios-yet-another-proxy-fixxspf-playlistxgettext-regexxgettext-webirdyak-shavexaryah@hypergraph-xyz/cli@jare-talend/i18next-parser@isotope/docking@hashicorp/next-hashicorp@hashicorp/nextjs-scripts@rstacruz/pnpm@restorecommerce/gql-bot@rbc-public/react-selectable-fast@southcn/ckeditor5-build-inline@l1nyanm1ng/react-picture-viewer@johnls/make-set-list@johnls/octopus@johnls/shovel@johnls/sshovel@joeybaker/chokidar@johntng/sidebar-generator@kingstonsoftware/shovel@netlify/build@netlify/cache-utils@morsedigital/webpack-defaults@maordavidov/flow_splitter@novembrecom/zxcvbn@ngxvoice/ngx-voicelistner@nikolay-borzov/torrent-clean@mblode/react-native-feather@srag/ngx-source-obfuscation@syncano/clibroccoli-static-asset-revbrowserify-ftwbroccoli-ng-templatecachebroccoli-optimagebutterbratwurstbitcarcaissoncanvas-fingerprintcatnapcarousel-reactcenarius-webcheck-pkgckeditor5-build-classic-v-editchokidar-graceful-cross-platformchokidar-webextensionschariot.jschronostoreclearly-stateddead-package-findercrabycosupcourse-vue-tplcreate-react-redux-webpack-projectcozy-desktopcordova-new-hot-code-push-clicopy-template-dircordova-hot-code-push-clicordova-hot-code-push-cli-aliyuncordova-hot-code-push-cli-wxlcordova-hot-code-push-cli-youpinyao
3.4.0

2 months ago

3.3.0

6 months ago

3.2.0

8 months ago

3.1.3

8 months ago

3.1.2

10 months ago

3.1.1

11 months ago

3.1.0

11 months ago

3.0.3

11 months ago

3.0.2

12 months ago

3.0.1

1 year ago

3.0.0

1 year ago

2.2.1

2 years ago

2.2.0

2 years ago

2.1.0

4 years ago

2.0.1

4 years ago

2.0.0

5 years ago

1.4.0

5 years ago

1.3.0

5 years ago

1.2.0

5 years ago

1.1.0

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.4.0

6 years ago

0.3.3

6 years ago

0.3.2

6 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.5

7 years ago

0.2.4

7 years ago

0.2.3

7 years ago

0.2.2

7 years ago

0.2.1

8 years ago

0.2.0

8 years ago

0.1.4

8 years ago

0.1.3

8 years ago

0.1.2

8 years ago

0.1.1

8 years ago

0.1.0

8 years ago