readdir-glob provides a memory-efficient, recursive file system directory reader with a streaming API, designed as an alternative to `node-glob` for scenarios requiring constant memory usage regardless of the file system size or the number of matched files. It leverages the `minimatch` library for glob pattern filtering. The current stable version is `3.0.0`, which requires Node.js 18 or later. The library ships with TypeScript types since v2.0.0 and supports both CommonJS and ESM. Its primary differentiator is its low, constant memory footprint, making it suitable for processing very large file systems where other glob libraries might exhaust memory. Releases appear to be driven by Node.js version updates and dependency security patches, with major versions aligning with Node.js LTS cycles.
npm install readdir-globVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize `readdir-glob` to find all `.js` files recursively within a specified root directory, excluding `node_modules`, and streaming the results. It also shows basic error handling and how to use the `pause` and `resume` methods.
Upgrade your Node.js runtime to the version required by your `readdir-glob` installation (e.g., Node.js 18+ for v3.0.0).
Update your ESM `import` statements for `readdirGlob` from named to default: `import readdirGlob from 'readdir-glob';`.
Avoid `stat: true` and `follow: true` if you don't need file stats or symlink traversal. For better performance, leverage `options.skip` to restrict the search as much as possible, as it prunes the directory tree before processing.
For entire directory branches you want to exclude from the search, use `options.skip`. For filtering individual files or directories found within explored paths, use `options.ignore`. Both `ignore` and `skip` patterns always operate in `dot:true` mode.
Review `minimatch` changelogs when upgrading `readdir-glob` across major versions to understand potential subtle behavior shifts in glob pattern matching. Ensure you are on a `minimatch` version >=10.2.1 to mitigate known ReDoS vulnerabilities.
For ESM (v3.0.0+), use `import readdirGlob from 'readdir-glob';`. For CommonJS, use `const readdirGlob = require('readdir-glob');`.Ensure the first argument to `readdirGlob` is a valid string representing the directory path to start searching, e.g., `readdirGlob('.', { pattern: '**/*.js' });`.Verify your `pattern` string. If matching files or directories starting with a `.` (dotfiles), ensure `options.dot` is set to `true`. Check `options.ignore` and `options.skip` patterns to confirm they aren't unintentionally excluding desired files. Note that `ignore` and `skip` patterns always operate in `dot:true` mode.