{"id":714,"url":"https://github.com/paulmillr/readdirp","last_synced_at":"2025-05-13T20:13:16.992Z","repository":{"id":3441678,"uuid":"4494405","full_name":"paulmillr/readdirp","owner":"paulmillr","description":"Recursive version of fs.readdir with small RAM \u0026 CPU footprint.","archived":false,"fork":false,"pushed_at":"2025-03-06T06:49:58.000Z","size":460,"stargazers_count":387,"open_issues_count":2,"forks_count":54,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-28T10:58:16.847Z","etag":null,"topics":["bun","deno","filesystem","fs","node","readdir","readdirp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulmillr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"paulmillr"}},"created_at":"2012-05-30T12:21:00.000Z","updated_at":"2025-03-06T06:50:01.000Z","dependencies_parsed_at":"2025-01-28T17:06:43.246Z","dependency_job_id":"1226540d-d2a0-4f45-ba79-538c2b0b9b38","html_url":"https://github.com/paulmillr/readdirp","commit_stats":{"total_commits":390,"total_committers":36,"mean_commits":"10.833333333333334","dds":0.5487179487179488,"last_synced_commit":"e658127a87627f3fb0aacd8f01c634ebbb118807"},"previous_names":["thlorenz/readdirp"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Freaddirp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Freaddirp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Freaddirp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulmillr%2Freaddirp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulmillr","download_url":"https://codeload.github.com/paulmillr/readdirp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252269103,"owners_count":21721246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","deno","filesystem","fs","node","readdir","readdirp"],"created_at":"2024-01-05T20:15:29.472Z","updated_at":"2025-05-13T20:13:11.983Z","avatar_url":"https://github.com/paulmillr.png","language":"JavaScript","readme":"# readdirp [![Weekly downloads](https://img.shields.io/npm/dw/readdirp.svg)](https://github.com/paulmillr/readdirp)\n\nRecursive version of fs.readdir. Exposes a **stream API** (with small RAM \u0026 CPU footprint) and a **promise API**.\n\n```sh\nnpm install readdirp\njsr add jsr:@paulmillr/readdirp\n```\n\n```javascript\n// Use streams to achieve small RAM \u0026 CPU footprint.\n// 1) Streams example with for-await.\nimport readdirp from 'readdirp';\nfor await (const entry of readdirp('.')) {\n  const {path} = entry;\n  console.log(`${JSON.stringify({path})}`);\n}\n\n// 2) Streams example, non for-await.\n// Print out all JS files along with their size within the current folder \u0026 subfolders.\nimport readdirp from 'readdirp';\nreaddirp('.', {alwaysStat: true, fileFilter: (f) =\u003e f.basename.endsWith('.js')})\n  .on('data', (entry) =\u003e {\n    const {path, stats: {size}} = entry;\n    console.log(`${JSON.stringify({path, size})}`);\n  })\n  // Optionally call stream.destroy() in `warn()` in order to abort and cause 'close' to be emitted\n  .on('warn', error =\u003e console.error('non-fatal error', error))\n  .on('error', error =\u003e console.error('fatal error', error))\n  .on('end', () =\u003e console.log('done'));\n\n// 3) Promise example. More RAM and CPU than streams / for-await.\nimport { readdirpPromise } from 'readdirp';\nconst files = await readdirpPromise('.');\nconsole.log(files.map(file =\u003e file.path));\n\n// Other options.\nimport readdirp from 'readdirp';\nreaddirp('test', {\n  fileFilter: (f) =\u003e f.basename.endsWith('.js'),\n  directoryFilter: (d) =\u003e d.basename !== '.git',\n  // directoryFilter: (di) =\u003e di.basename.length === 9\n  type: 'files_directories',\n  depth: 1\n});\n```\n\n## API\n\n`const stream = readdirp(root[, options])` — **Stream API**\n\n- Reads given root recursively and returns a `stream` of [entry infos](#entryinfo)\n- Optionally can be used like `for await (const entry of stream)` with node.js 10+ (`asyncIterator`).\n- `on('data', (entry) =\u003e {})` [entry info](#entryinfo) for every file / dir.\n- `on('warn', (error) =\u003e {})` non-fatal `Error` that prevents a file / dir from being processed. Example: inaccessible to the user.\n- `on('error', (error) =\u003e {})` fatal `Error` which also ends the stream. Example: illegal options where passed.\n- `on('end')` — we are done. Called when all entries were found and no more will be emitted.\n- `on('close')` — stream is destroyed via `stream.destroy()`.\n  Could be useful if you want to manually abort even on a non fatal error.\n  At that point the stream is no longer `readable` and no more entries, warning or errors are emitted\n- To learn more about streams, consult the very detailed [nodejs streams documentation](https://nodejs.org/api/stream.html)\n  or the [stream-handbook](https://github.com/substack/stream-handbook)\n\n`const entries = await readdirp.promise(root[, options])` — **Promise API**. Returns a list of [entry infos](#entryinfo).\n\nFirst argument is awalys `root`, path in which to start reading and recursing into subdirectories.\n\n### options\n\n- `fileFilter`: filter to include or exclude files\n    - **Function**: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry\n- `directoryFilter`: filter to include/exclude directories found and to recurse into. Directories that do not pass a filter will not be recursed into.\n- `depth: 5`: depth at which to stop recursing even if more subdirectories are found\n- `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.\n- `alwaysStat: false`: always return `stats` property for every file. Default is `false`, readdirp will return `Dirent` entries. Setting it to `true` can double readdir execution time - use it only when you need file `size`, `mtime` etc. Cannot be enabled on node \u003c10.10.0.\n- `lstat: false`: include symlink entries in the stream along with files. When `true`, `fs.lstat` would be used instead of `fs.stat`\n\n### `EntryInfo`\n\nHas the following properties:\n\n- `path: 'assets/javascripts/react.js'`: path to the file/directory (relative to given root)\n- `fullPath: '/Users/dev/projects/app/assets/javascripts/react.js'`: full path to the file/directory found\n- `basename: 'react.js'`: name of the file/directory\n- `dirent: fs.Dirent`: built-in [dir entry object](https://nodejs.org/api/fs.html#fs_class_fs_dirent) - only with `alwaysStat: false`\n- `stats: fs.Stats`: built in [stat object](https://nodejs.org/api/fs.html#fs_class_fs_stats) - only with `alwaysStat: true`\n\n## Changelog\n\n- 4.0 (Aug 25, 2024) rewritten in typescript, producing hybrid common.js / esm module.\n    - Remove glob support and all dependencies\n    - Make sure you're using `let {readdirp} = require('readdirp')` in common.js\n- 3.5 (Oct 13, 2020) disallows recursive directory-based symlinks.\n  Before, it could have entered infinite loop.\n- 3.4 (Mar 19, 2020) adds support for directory-based symlinks.\n- 3.3 (Dec 6, 2019) stabilizes RAM consumption and enables perf management with `highWaterMark` option. Fixes race conditions related to `for-await` looping.\n- 3.2 (Oct 14, 2019) improves performance by 250% and makes streams implementation more idiomatic.\n- 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\".\n- 3.0 brings huge performance improvements and stream backpressure support.\n- Upgrading 2.x to 3.x:\n    - Signature changed from `readdirp(options)` to `readdirp(root, options)`\n    - Replaced callback API with promise API.\n    - Renamed `entryType` option to `type`\n    - Renamed `entryType: 'both'` to `'files_directories'`\n    - `EntryInfo`\n        - Renamed `stat` to `stats`\n            - Emitted only when `alwaysStat: true`\n            - `dirent` is emitted instead of `stats` by default with `alwaysStat: false`\n        - Renamed `name` to `basename`\n        - Removed `parentDir` and `fullParentDir` properties\n- Supported node.js versions:\n    - 4.x: node 14+\n    - 3.x: node 8+\n    - 2.x: node 0.6+\n\n## License\n\nCopyright (c) 2012-2019 Thorsten Lorenz, Paul Miller (\u003chttps://paulmillr.com\u003e)\n\nMIT License, see [LICENSE](LICENSE) file.\n","funding_links":["https://github.com/sponsors/paulmillr"],"categories":["JavaScript","Libraries"],"sub_categories":["Filesystem"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmillr%2Freaddirp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulmillr%2Freaddirp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulmillr%2Freaddirp/lists"}