{"_id":"@jsdevtools/readdir-enhanced","_rev":"37115","name":"@jsdevtools/readdir-enhanced","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","dist-tags":{"latest":"6.0.4"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"time":{"modified":"2021-06-03T10:10:15.000Z","created":"2020-02-17T16:43:03.067Z","6.0.4":"2020-07-18T12:52:12.583Z","6.0.3":"2020-03-16T11:13:25.982Z","6.0.2":"2020-03-16T10:51:06.727Z","6.0.1":"2020-03-14T14:06:14.499Z","6.0.0":"2020-02-17T18:38:22.054Z","5.1.1":"2020-02-17T16:43:03.067Z"},"users":{},"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"versions":{"6.0.4":{"name":"@jsdevtools/readdir-enhanced","version":"6.0.4","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"eslint src test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config":"^1.0.4","@jsdevtools/version-bump-prompt":"^6.0.5","@types/chai":"^4.2.11","@types/mocha":"^8.0.0","@types/node":"^14.0.23","chai":"^4.2.0","del":"^5.1.0","eslint":"^7.4.0","mocha":"^8.0.1","npm-check":"^5.9.2","nyc":"^15.1.0","shx":"^0.3.2","through2":"^4.0.2","typescript":"^3.9.7"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.2"},"gitHead":"4eeea85e345385a61ed3ea1344917d44642057fd","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@6.0.4","_nodeVersion":"10.21.0","_npmVersion":"6.14.4","dist":{"shasum":"077749dac62cefd01453cd5af1084586c635a358","size":22955,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-6.0.4.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-6.0.4.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_6.0.4_1595076732455_0.8754629070726092"},"_hasShrinkwrap":false,"publish_time":1595076732583,"_cnpm_publish_time":1595076732583},"6.0.3":{"name":"@jsdevtools/readdir-enhanced","version":"6.0.3","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"npm run lint:typescript && npm run lint:javascript","lint:typescript":"tslint -p tsconfig.json","lint:javascript":"eslint test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config-modular":"^8.0.0","@jsdevtools/tslint-modular":"^2.0.2","@jsdevtools/version-bump-prompt":"^6.0.2","@types/chai":"^4.2.11","@types/mocha":"^7.0.2","@types/node":"^13.9.1","chai":"^4.2.0","del":"^5.1.0","eslint":"^6.8.0","mocha":"^7.1.0","npm-check":"^5.9.2","nyc":"^15.0.0","shx":"^0.3.2","through2":"^3.0.0","tslint":"^6.1.0","typescript":"^3.8.3","typescript-tslint-plugin":"^0.5.5"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.0"},"gitHead":"987b8c80125aaece3d0a7bc265ab5bc87cfa6a5a","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@6.0.3","_nodeVersion":"10.19.0","_npmVersion":"6.13.4","dist":{"shasum":"0916be64d6677dd98b8bf6fd38e6e1057d31ada2","size":22847,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-6.0.3.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-6.0.3.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_6.0.3_1584357205879_0.11330054412675006"},"_hasShrinkwrap":false,"publish_time":1584357205982,"_cnpm_publish_time":1584357205982},"6.0.2":{"name":"@jsdevtools/readdir-enhanced","version":"6.0.2","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"npm run lint:typescript && npm run lint:javascript","lint:typescript":"tslint -p tsconfig.json","lint:javascript":"eslint test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config-modular":"^8.0.0","@jsdevtools/tslint-modular":"^2.0.2","@jsdevtools/version-bump-prompt":"^6.0.2","@types/chai":"^4.2.11","@types/mocha":"^7.0.2","@types/node":"^13.9.1","chai":"^4.2.0","del":"^5.1.0","eslint":"^6.8.0","mocha":"^7.1.0","npm-check":"^5.9.2","nyc":"^15.0.0","shx":"^0.3.2","through2":"^3.0.0","tslint":"^6.1.0","typescript":"^3.8.3","typescript-tslint-plugin":"^0.5.5"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.0"},"gitHead":"6560200544e9975ad67986e10d0e6e70ec09753f","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@6.0.2","_nodeVersion":"10.19.0","_npmVersion":"6.13.4","dist":{"shasum":"d4f8efb921b0dc0aa67b52937e5c3e562996aa41","size":22706,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-6.0.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-6.0.2.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_6.0.2_1584355866403_0.8322321674305038"},"_hasShrinkwrap":false,"publish_time":1584355866727,"_cnpm_publish_time":1584355866727},"6.0.1":{"name":"@jsdevtools/readdir-enhanced","version":"6.0.1","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"npm run lint:typescript && npm run lint:javascript","lint:typescript":"tslint -p tsconfig.json","lint:javascript":"eslint test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config-modular":"^8.0.0","@jsdevtools/tslint-modular":"^2.0.2","@jsdevtools/version-bump-prompt":"^6.0.2","@types/chai":"^4.2.11","@types/mocha":"^7.0.2","@types/node":"^13.9.1","chai":"^4.2.0","del":"^5.1.0","eslint":"^6.8.0","mocha":"^7.1.0","npm-check":"^5.9.2","nyc":"^15.0.0","shx":"^0.3.2","through2":"^3.0.0","tslint":"^6.1.0","typescript":"^3.8.3","typescript-tslint-plugin":"^0.5.5"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.0"},"gitHead":"4fff82a9c9ad5f6eecb978b5b225f899cc0fc3cb","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@6.0.1","_nodeVersion":"10.19.0","_npmVersion":"6.13.4","dist":{"shasum":"2448f7c2db15852eb9dbe35a956ac93e465ca289","size":22668,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-6.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-6.0.1.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_6.0.1_1584194774365_0.41607555380165895"},"_hasShrinkwrap":false,"publish_time":1584194774499,"_cnpm_publish_time":1584194774499},"6.0.0":{"name":"@jsdevtools/readdir-enhanced","version":"6.0.0","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"npm run lint:typescript && npm run lint:javascript","lint:typescript":"tslint -p tsconfig.json","lint:javascript":"eslint test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config-modular":"^8.0.0","@jsdevtools/tslint-modular":"^2.0.1","@jsdevtools/version-bump-prompt":"^6.0.0","@types/chai":"^4.2.9","@types/mocha":"^7.0.1","@types/node":"^13.7.1","chai":"^4.2.0","coveralls":"^3.0.9","del":"^5.1.0","eslint":"^6.8.0","mkdirp":"^1.0.3","mocha":"^7.0.1","npm-check":"^5.9.0","nyc":"^15.0.0","shx":"^0.3.2","through2":"^3.0.0","tslint":"^6.0.0","typescript":"^3.7.5","typescript-tslint-plugin":"^0.5.5"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.0"},"gitHead":"17f754413b19b5c95e4e614a2e82af535057cef6","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@6.0.0","_nodeVersion":"10.19.0","_npmVersion":"6.13.4","dist":{"shasum":"4d841023801647d2aaf0af4cd79806ba33520072","size":22678,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-6.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-6.0.0.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_6.0.0_1581964701946_0.8057433028444971"},"_hasShrinkwrap":false,"publish_time":1581964702054,"_cnpm_publish_time":1581964702054},"5.1.1":{"name":"@jsdevtools/readdir-enhanced","version":"5.1.1","description":"fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.","keywords":["fs","readdir","async","promise","iterator","generator","async-iterator","stream","event","event-emitter","recursive","deep","walk","crawl","filter","absolute"],"author":{"name":"James Messinger","url":"https://jamesmessinger.com"},"license":"MIT","homepage":"https://jstools.dev/readdir-enhanced","repository":{"type":"git","url":"git+https://github.com/JS-DevTools/readdir-enhanced.git"},"main":"lib/index.js","types":"lib/index.d.ts","scripts":{"clean":"shx rm -rf .nyc_output coverage lib","lint":"npm run lint:typescript && npm run lint:javascript","lint:typescript":"tslint -p tsconfig.json","lint:javascript":"eslint test","build":"tsc","watch":"tsc --watch","test":"npm run test:node && npm run test:typescript && npm run lint","test:node":"mocha","test:typescript":"tsc --noEmit --strict --lib esnext test/specs/typescript-definition.spec.ts","coverage":"nyc node_modules/mocha/bin/mocha","upgrade":"npm-check -u && npm audit fix","bump":"bump --tag --push --all","release":"npm run upgrade && npm run clean && npm run build && npm test && npm run bump"},"engines":{"node":">=10"},"devDependencies":{"@jsdevtools/eslint-config-modular":"^8.0.0","@jsdevtools/tslint-modular":"^2.0.1","@jsdevtools/version-bump-prompt":"^6.0.0","@types/chai":"^4.2.9","@types/mocha":"^7.0.1","@types/node":"^13.7.1","chai":"^4.2.0","coveralls":"^3.0.9","del":"^5.1.0","eslint":"^6.8.0","mkdirp":"^1.0.3","mocha":"^7.0.1","npm-check":"^5.9.0","nyc":"^15.0.0","shx":"^0.3.2","through2":"^3.0.0","tslint":"^6.0.0","typescript":"^3.7.5","typescript-tslint-plugin":"^0.5.5"},"dependencies":{"@jsdevtools/file-path-filter":"^3.0.0"},"gitHead":"f8121be61feb3269080dcec104253c7119f79b76","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"_id":"@jsdevtools/readdir-enhanced@5.1.1","_nodeVersion":"13.3.0","_npmVersion":"6.13.1","dist":{"shasum":"8aa7d989bb7f6c7815c7060e71f6472453ceeaa9","size":22579,"noattachment":false,"key":"/@jsdevtools/readdir-enhanced/-/@jsdevtools/readdir-enhanced-5.1.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/@jsdevtools/readdir-enhanced/download/@jsdevtools/readdir-enhanced-5.1.1.tgz"},"maintainers":[{"name":"jamesmessinger","email":"james.messinger@gmail.com"},{"name":"james_messinger","email":"j.ames.messinger@gmail.com"}],"_npmUser":{"name":"jamesmessinger","email":"james.messinger@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/readdir-enhanced_5.1.1_1581957782877_0.9968267842867444"},"_hasShrinkwrap":false,"publish_time":1581957783067,"_cnpm_publish_time":1581957783067}},"readme":"Enhanced `fs.readdir()`\n=======================\n\n[![Cross-Platform Compatibility](https://jstools.dev/img/badges/os-badges.svg)](https://github.com/JS-DevTools/readdir-enhanced/actions)\n[![Build Status](https://github.com/JS-DevTools/readdir-enhanced/workflows/CI-CD/badge.svg)](https://github.com/JS-DevTools/readdir-enhanced/actions)\n\n[![Coverage Status](https://coveralls.io/repos/github/JS-DevTools/readdir-enhanced/badge.svg?branch=master)](https://coveralls.io/github/JS-DevTools/readdir-enhanced?branch=master)\n[![Dependencies](https://david-dm.org/JS-DevTools/readdir-enhanced.svg)](https://david-dm.org/JS-DevTools/readdir-enhanced)\n\n[![npm](https://img.shields.io/npm/v/@jsdevtools/readdir-enhanced.svg)](https://www.npmjs.com/package/@jsdevtools/readdir-enhanced)\n[![License](https://img.shields.io/npm/l/@jsdevtools/readdir-enhanced.svg)](LICENSE)\n[![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/JS-DevTools/readdir-enhanced)\n\n\n\nFeatures\n----------------------------------\n- Fully [**backward-compatible**](#backward-compatible) drop-in replacement for [`fs.readdir()`](https://nodejs.org/api/fs.html#fs_fs_readdir_path_options_callback) and [`fs.readdirSync()`](https://nodejs.org/api/fs.html#fs_fs_readdirsync_path_options)\n\n- Can [crawl sub-directories](#deep) - you can even control which ones\n\n- Supports [filtering results](#filter) using globs, regular expressions, or custom logic\n\n- Can return [absolute paths](#basepath)\n\n- Can return [`fs.Stats` objects](#stats) rather than just paths\n\n- Exposes additional APIs: [Promise, Stream, EventEmitter, and Async Iterator](#pick-your-api).\n\n\n\nExample\n----------------------------------\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\nimport through2 from \"through2\";\n\n// Synchronous API\nlet files = readdir.sync(\"my/directory\");\n\n// Callback API\nreaddir.async(\"my/directory\", (err, files) => { ... });\n\n// Promises API\nreaddir.async(\"my/directory\")\n  .then((files) => { ... })\n  .catch((err) => { ... });\n\n// Async/Await API\nlet files = await readdir.async(\"my/directory\");\n\n// Async Iterator API\nfor await (let item of readdir.iterator(\"my/directory\")) {\n  ...\n}\n\n// EventEmitter API\nreaddir.stream(\"my/directory\")\n  .on(\"data\", (path) => { ... })\n  .on(\"file\", (path) => { ... })\n  .on(\"directory\", (path) => { ... })\n  .on(\"symlink\", (path) => { ... })\n  .on(\"error\", (err) => { ... });\n\n// Streaming API\nlet stream = readdir.stream(\"my/directory\")\n  .pipe(through2.obj(function(data, enc, next) {\n    console.log(data);\n    this.push(data);\n    next();\n  });\n```\n\n\n\nPick Your API\n----------------------------------\nReaddir Enhanced has multiple APIs, so you can pick whichever one you prefer. Here are some things to consider about each API:\n\n|Function|Returns|Syntax|[Blocks the thread?](#blocking-the-thread)|[Buffers results?](#buffered-results)|\n|---|---|---|---|---|\n|`readdirSync()`<br>`readdir.sync()`|Array|Synchronous|yes|yes|\n|`readdir()`<br>`readdir.async()`<br>`readdirAsync()`|[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)|[`async/await`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await)<br>[`Promise.then()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)<br>[callback](https://nodejs.org/en/knowledge/getting-started/control-flow/what-are-callbacks/)|no|yes|\n|`readdir.iterator()`<br>`readdirIterator()`|[Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)|[`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)|no|no|\n|`readdir.stream()`<br>`readdirStream()`|[Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)|[`stream.on(\"data\")`](https://nodejs.org/api/stream.html#stream_event_data)<br>[`stream.read()`](https://nodejs.org/api/stream.html#stream_readable_read_size)<br>[`stream.pipe()`](https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options)|no|no|\n\n### Blocking the Thread\nThe synchronous API blocks the thread until all results have been read. Only use this if you know the directory does not contain many items, or if your program needs the results before it can do anything else.\n\n### Buffered Results\nSome APIs buffer the results, which means you get all the results at once (as an array). This can be more convenient to work with, but it can also consume a significant amount of memory, depending on how many results there are. The non-buffered APIs return each result to you one-by-one, which means you can start processing the results even while the directory is still being read.\n\n\n\nAlias Exports\n----------------------------------\nThe [example above](#example) imported the `readdir` default export and used its properties, such as `readdir.sync` or `readdir.async` to call specific APIs. For convenience, each of the different APIs is exported as a named function that you can import directly.\n\n- `readdir.sync()` is also exported as `readdirSync()`\n- `readdir.async()` is also exported as `readdirAsync()`\n- `readdir.iterator()` is also exported as `readdirIterator()`\n- `readdir.stream()` is also exported as `readdirStream()`\n\nHere's how to import named exports rather than the default export:\n\n```javascript\nimport { readdirSync, readdirAsync, readdirIterator, readdirStream } from \"@jsdevtools/readdir-enhanced\";\n```\n\n\n\n<a id=\"options\"></a>\nEnhanced Features\n----------------------------------\nReaddir Enhanced adds several features to the built-in `fs.readdir()` function.  All of the enhanced features are opt-in, which makes Readdir Enhanced [fully backward compatible by default](#backward-compatible).  You can enable any of the features by passing-in an `options` argument as the second parameter.\n\n\n\n<a id=\"deep\"></a>\nCrawl Subdirectories\n----------------------------------\nBy default, Readdir Enhanced will only return the top-level contents of the starting directory. But you can set the `deep` option to recursively traverse the subdirectories and return their contents as well.\n\n### Crawl ALL subdirectories\n\nThe `deep` option can be set to `true` to traverse the entire directory structure.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\nreaddir(\"my/directory\", {deep: true}, (err, files) => {\n  console.log(files);\n  // => subdir1\n  // => subdir1/file.txt\n  // => subdir1/subdir2\n  // => subdir1/subdir2/file.txt\n  // => subdir1/subdir2/subdir3\n  // => subdir1/subdir2/subdir3/file.txt\n});\n```\n\n### Crawl to a specific depth\nThe `deep` option can be set to a number to only traverse that many levels deep.  For example, calling `readdir(\"my/directory\", {deep: 2})` will return `subdir1/file.txt` and `subdir1/subdir2/file.txt`, but it _won't_ return `subdir1/subdir2/subdir3/file.txt`.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\nreaddir(\"my/directory\", {deep: 2}, (err, files) => {\n  console.log(files);\n  // => subdir1\n  // => subdir1/file.txt\n  // => subdir1/subdir2\n  // => subdir1/subdir2/file.txt\n  // => subdir1/subdir2/subdir3\n});\n```\n\n### Crawl subdirectories by name\nFor simple use-cases, you can use a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) or a [glob pattern](https://github.com/isaacs/node-glob#glob-primer) to crawl only the directories whose path matches the pattern.  The path is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath).\n\n> **NOTE:** Glob patterns [_always_ use forward-slashes](https://github.com/isaacs/node-glob#windows), even on Windows. This _does not_ apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using `[\\\\/]`.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Only crawl the \"lib\" and \"bin\" subdirectories\n// (notice that the \"node_modules\" subdirectory does NOT get crawled)\nreaddir(\"my/directory\", {deep: /lib|bin/}, (err, files) => {\n  console.log(files);\n  // => bin\n  // => bin/cli.js\n  // => lib\n  // => lib/index.js\n  // => node_modules\n  // => package.json\n});\n```\n\n### Custom recursion logic\nFor more advanced recursion, you can set the `deep` option to a function that accepts an [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object and returns a truthy value if the starting directory should be crawled.\n\n> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object that's passed to the function has additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Crawl all subdirectories, except \"node_modules\"\nfunction ignoreNodeModules (stats) {\n  return stats.path.indexOf(\"node_modules\") === -1;\n}\n\nreaddir(\"my/directory\", {deep: ignoreNodeModules}, (err, files) => {\n  console.log(files);\n  // => bin\n  // => bin/cli.js\n  // => lib\n  // => lib/index.js\n  // => node_modules\n  // => package.json\n});\n```\n\n\n\n<a id=\"filter\"></a>\nFiltering\n----------------------------------\nThe `filter` option lets you limit the results based on any criteria you want.\n\n### Filter by name\nFor simple use-cases, you can use a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) or a [glob pattern](https://github.com/isaacs/node-glob#glob-primer) to filter items by their path.  The path is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath).\n\n> **NOTE:** Glob patterns [_always_ use forward-slashes](https://github.com/isaacs/node-glob#windows), even on Windows. This _does not_ apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using `[\\\\/]`.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Find all .txt files\nreaddir(\"my/directory\", {filter: \"*.txt\"});\n\n// Find all package.json files\nreaddir(\"my/directory\", {filter: \"**/package.json\", deep: true});\n\n// Find everything with at least one number in the name\nreaddir(\"my/directory\", {filter: /\\d+/});\n```\n\n### Custom filtering logic\nFor more advanced filtering, you can specify a filter function that accepts an [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object and returns a truthy value if the item should be included in the results.\n\n> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object that's passed to the filter function has additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Only return file names containing an underscore\nfunction myFilter(stats) {\n  return stats.isFile() && stats.path.indexOf(\"_\") >= 0;\n}\n\nreaddir(\"my/directory\", {filter: myFilter}, (err, files) => {\n  console.log(files);\n  // => __myFile.txt\n  // => my_other_file.txt\n  // => img_1.jpg\n  // => node_modules\n});\n```\n\n\n\n<a id=\"stats\"></a>\nGet `fs.Stats` objects instead of strings\n------------------------------------------------------------\nAll of the Readdir Enhanced functions listed above return an array of strings (paths). But in some situations, the path isn't enough information.  Setting the `stats` option returns an array of [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects instead of path strings.  The `fs.Stats` object contains all sorts of useful information, such as the size, the creation date/time, and helper methods such as `isFile()`, `isDirectory()`, `isSymbolicLink()`, etc.\n\n> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects that are returned also have additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\nreaddir(\"my/directory\", { stats: true }, (err, stats) => {\n  for (let stat of stats) {\n    console.log(`${stat.path} was created at ${stat.birthtime}`);\n  }\n});\n```\n\n\n\n<a id=\"basepath\"></a>\nBase Path\n----------------------------------\nBy default all Readdir Enhanced functions return paths that are relative to the starting directory. But you can use the `basePath` option to customize this.  The `basePath` will be prepended to all of the returned paths.  One common use-case for this is to set `basePath` to the absolute path of the starting directory, so that all of the returned paths will be absolute.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\nimport { resolve } from \"path\";\n\n// Get absolute paths\nlet absPath = resolve(\"my/dir\");\nreaddir(\"my/directory\", {basePath: absPath}, (err, files) => {\n  console.log(files);\n  // => /absolute/path/to/my/directory/file1.txt\n  // => /absolute/path/to/my/directory/file2.txt\n  // => /absolute/path/to/my/directory/subdir\n});\n\n// Get paths relative to the working directory\nreaddir(\"my/directory\", {basePath: \"my/directory\"}, (err, files) => {\n  console.log(files);\n  // => my/directory/file1.txt\n  // => my/directory/file2.txt\n  // => my/directory/subdir\n});\n```\n\n\n\n<a id=\"sep\"></a>\nPath Separator\n----------------------------------\nBy default, Readdir Enhanced uses the correct path separator for your OS (`\\` on Windows, `/` on Linux & MacOS). But you can set the `sep` option to any separator character(s) that you want to use instead.  This is usually used to ensure consistent path separators across different OSes.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Always use Windows path separators\nreaddir(\"my/directory\", {sep: \"\\\\\", deep: true}, (err, files) => {\n  console.log(files);\n  // => subdir1\n  // => subdir1\\file.txt\n  // => subdir1\\subdir2\n  // => subdir1\\subdir2\\file.txt\n  // => subdir1\\subdir2\\subdir3\n  // => subdir1\\subdir2\\subdir3\\file.txt\n});\n```\n\n\n\n<a id=\"fs\"></a>\nCustom FS methods\n----------------------------------\nBy default, Readdir Enhanced uses the default [Node.js FileSystem module](https://nodejs.org/api/fs.html) for methods like `fs.stat`, `fs.readdir` and `fs.lstat`. But in some situations, you can want to use your own FS methods (FTP, SSH, remote drive and etc). So you can provide your own implementation of FS methods by setting `options.fs` or specific methods, such as `options.fs.stat`.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\nfunction myCustomReaddirMethod(dir, callback) {\n  callback(null, [\"__myFile.txt\"]);\n}\n\nlet options = {\n  fs: {\n    readdir: myCustomReaddirMethod\n  }\n};\n\nreaddir(\"my/directory\", options, (err, files) => {\n  console.log(files);\n  // => __myFile.txt\n});\n```\n\n\n\n<a id=\"backward-compatible\"></a>\nBackward Compatible\n-------------------------------------\nReaddir Enhanced is fully backward-compatible with Node.js' built-in `fs.readdir()` and `fs.readdirSync()` functions, so you can use it as a drop-in replacement in existing projects without affecting existing functionality, while still being able to use the enhanced features as needed.\n\n```javascript\nimport { readdir, readdirSync } from \"@jsdevtools/readdir-enhanced\";\n\n// Use it just like Node's built-in fs.readdir function\nreaddir(\"my/directory\", (er,  files) => { ... });\n\n// Use it just like Node's built-in fs.readdirSync function\nlet files = readdirSync(\"my/directory\");\n```\n\n\n\nA Note on Streams\n----------------------------------\nThe Readdir Enhanced streaming API follows the Node.js streaming API. A lot of questions around the streaming API can be answered by reading the [Node.js documentation.](https://nodejs.org/api/stream.html). However, we've tried to answer the most common questions here.\n\n### Stream Events\n\nAll events in the Node.js streaming API are supported by Readdir Enhanced. These events include \"end\", \"close\", \"drain\", \"error\", plus more. [An exhaustive list of events is available in the Node.js documentation.](https://nodejs.org/api/stream.html#stream_class_stream_readable)\n\n#### Detect when the Stream has finished\n\nUsing these events, we can detect when the stream has finished reading files.\n\n```javascript\nimport readdir from \"@jsdevtools/readdir-enhanced\";\n\n// Build the stream using the Streaming API\nlet stream = readdir.stream(\"my/directory\")\n  .on(\"data\", (path) => { ... });\n\n// Listen to the end event to detect the end of the stream\nstream.on(\"end\", () => {\n  console.log(\"Stream finished!\");\n});\n```\n\n### Paused Streams vs. Flowing Streams\n\nAs with all Node.js streams, a Readdir Enhanced stream starts in \"paused mode\". For the stream to start emitting files, you'll need to switch it to \"flowing mode\".\n\nThere are many ways to trigger flowing mode, such as adding a `stream.data()` handler, using `stream.pipe()` or calling `stream.resume()`.\n\nUnless you trigger flowing mode, your stream will stay paused and you won't receive any file events.\n\n[More information on paused vs. flowing mode can be found in the Node.js documentation.](https://nodejs.org/api/stream.html#stream_two_reading_modes)\n\n\n\nContributing\n--------------------------\nContributions, enhancements, and bug-fixes are welcome!  [Open an issue](https://github.com/JS-DevTools/readdir-enhanced/issues) on GitHub and [submit a pull request](https://github.com/JS-DevTools/readdir-enhanced/pulls).\n\n#### Building\nTo build the project locally on your computer:\n\n1. __Clone this repo__<br>\n`git clone https://github.com/JS-DevTools/readdir-enhanced.git`\n\n2. __Install dependencies__<br>\n`npm install`\n\n3. __Run the tests__<br>\n`npm test`\n\n\n\nLicense\n--------------------------\nReaddir Enhanced is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.\n\nThis package is [Treeware](http://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/JS-DevTools/readdir-enhanced) to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.\n\n\n\nBig Thanks To\n--------------------------\nThanks to these awesome companies for their support of Open Source developers ❤\n\n[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com)\n[![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com)\n[![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io)\n","_attachments":{},"homepage":"https://jstools.dev/readdir-enhanced","bugs":{"url":"https://github.com/JS-DevTools/readdir-enhanced/issues"},"license":"MIT"}