Gathering detailed insights and metrics for @mrmlnc/readdir-enhanced
Gathering detailed insights and metrics for @mrmlnc/readdir-enhanced
Gathering detailed insights and metrics for @mrmlnc/readdir-enhanced
Gathering detailed insights and metrics for @mrmlnc/readdir-enhanced
readdir-enhanced
fs.readdir with sync, async, streaming, and async iterator APIs + filtering, recursion, absolute paths, etc.
readdir-glob
Recursive fs.readdir with streaming API and glob filtering.
fs-readdir-recursive
Recursively read a directory
recursive-readdir
Get an array of all files in a directory and subdirectories.
fs.readdir() with filter, recursion, absolute paths, promises, streams, and more!
npm install @mrmlnc/readdir-enhanced
Module System
Min. Node Version
Typescript Support
Node Version
NPM Version
86 Stars
295 Commits
4 Forks
4 Watching
4 Branches
6 Contributors
Updated on 14 May 2024
JavaScript (68.26%)
TypeScript (31.74%)
Cumulative downloads
Total Downloads
Last day
-6.1%
644,103
Compared to previous day
Last week
2.2%
3,520,037
Compared to previous week
Last month
21.5%
14,330,311
Compared to previous month
Last year
-40.4%
169,950,483
Compared to previous year
fs.readdir()
Fully backward-compatible drop-in replacement for fs.readdir()
and fs.readdirSync()
Can crawl sub-directories - you can even control which ones
Supports filtering results using globs, regular expressions, or custom logic
Can return absolute paths
Can return fs.Stats
objects rather than just paths
Exposes additional APIs: Promise, Stream, EventEmitter, and Async Iterator.
1import readdir from "@jsdevtools/readdir-enhanced"; 2import through2 from "through2"; 3 4// Synchronous API 5let files = readdir.sync("my/directory"); 6 7// Callback API 8readdir.async("my/directory", (err, files) => { ... }); 9 10// Promises API 11readdir.async("my/directory") 12 .then((files) => { ... }) 13 .catch((err) => { ... }); 14 15// Async/Await API 16let files = await readdir.async("my/directory"); 17 18// Async Iterator API 19for await (let item of readdir.iterator("my/directory")) { 20 ... 21} 22 23// EventEmitter API 24readdir.stream("my/directory") 25 .on("data", (path) => { ... }) 26 .on("file", (path) => { ... }) 27 .on("directory", (path) => { ... }) 28 .on("symlink", (path) => { ... }) 29 .on("error", (err) => { ... }); 30 31// Streaming API 32let stream = readdir.stream("my/directory") 33 .pipe(through2.obj(function(data, enc, next) { 34 console.log(data); 35 this.push(data); 36 next(); 37 });
Install using npm:
1npm install @jsdevtools/readdir-enhanced
Readdir Enhanced has multiple APIs, so you can pick whichever one you prefer. Here are some things to consider about each API:
Function | Returns | Syntax | Blocks the thread? | Buffers results? |
---|---|---|---|---|
readdirSync() readdir.sync() | Array | Synchronous | yes | yes |
readdir() readdir.async() readdirAsync() | Promise | async/await Promise.then() callback | no | yes |
readdir.iterator() readdirIterator() | Iterator | for await...of | no | no |
readdir.stream() readdirStream() | Readable Stream | stream.on("data") stream.read() stream.pipe() | no | no |
The 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.
Some 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.
The example above 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.
readdir.sync()
is also exported as readdirSync()
readdir.async()
is also exported as readdirAsync()
readdir.iterator()
is also exported as readdirIterator()
readdir.stream()
is also exported as readdirStream()
Here's how to import named exports rather than the default export:
1import { readdirSync, readdirAsync, readdirIterator, readdirStream } from "@jsdevtools/readdir-enhanced";
Readdir 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. You can enable any of the features by passing-in an options
argument as the second parameter.
By 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.
The deep
option can be set to true
to traverse the entire directory structure.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3readdir("my/directory", {deep: true}, (err, files) => { 4 console.log(files); 5 // => subdir1 6 // => subdir1/file.txt 7 // => subdir1/subdir2 8 // => subdir1/subdir2/file.txt 9 // => subdir1/subdir2/subdir3 10 // => subdir1/subdir2/subdir3/file.txt 11});
The 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
.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3readdir("my/directory", {deep: 2}, (err, files) => { 4 console.log(files); 5 // => subdir1 6 // => subdir1/file.txt 7 // => subdir1/subdir2 8 // => subdir1/subdir2/file.txt 9 // => subdir1/subdir2/subdir3 10});
For simple use-cases, you can use a regular expression or a glob pattern 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
.
NOTE: Glob patterns always use forward-slashes, 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
[\\/]
.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Only crawl the "lib" and "bin" subdirectories 4// (notice that the "node_modules" subdirectory does NOT get crawled) 5readdir("my/directory", {deep: /lib|bin/}, (err, files) => { 6 console.log(files); 7 // => bin 8 // => bin/cli.js 9 // => lib 10 // => lib/index.js 11 // => node_modules 12 // => package.json 13});
For more advanced recursion, you can set the deep
option to a function that accepts an fs.Stats
object and returns a truthy value if the starting directory should be crawled.
NOTE: The
fs.Stats
object that's passed to the function has additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Crawl all subdirectories, except "node_modules" 4function ignoreNodeModules (stats) { 5 return stats.path.indexOf("node_modules") === -1; 6} 7 8readdir("my/directory", {deep: ignoreNodeModules}, (err, files) => { 9 console.log(files); 10 // => bin 11 // => bin/cli.js 12 // => lib 13 // => lib/index.js 14 // => node_modules 15 // => package.json 16});
The filter
option lets you limit the results based on any criteria you want.
For simple use-cases, you can use a regular expression or a glob pattern to filter items by their path. The path is relative to the starting directory by default, but you can customize this via options.basePath
.
NOTE: Glob patterns always use forward-slashes, 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
[\\/]
.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Find all .txt files 4readdir("my/directory", {filter: "*.txt"}); 5 6// Find all package.json files 7readdir("my/directory", {filter: "**/package.json", deep: true}); 8 9// Find everything with at least one number in the name 10readdir("my/directory", {filter: /\d+/});
For more advanced filtering, you can specify a filter function that accepts an fs.Stats
object and returns a truthy value if the item should be included in the results.
NOTE: The
fs.Stats
object that's passed to the filter function has additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Only return file names containing an underscore 4function myFilter(stats) { 5 return stats.isFile() && stats.path.indexOf("_") >= 0; 6} 7 8readdir("my/directory", {filter: myFilter}, (err, files) => { 9 console.log(files); 10 // => __myFile.txt 11 // => my_other_file.txt 12 // => img_1.jpg 13 // => node_modules 14});
fs.Stats
objects instead of stringsAll 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
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.
NOTE: The
fs.Stats
objects that are returned also have additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3readdir("my/directory", { stats: true }, (err, stats) => { 4 for (let stat of stats) { 5 console.log(`${stat.path} was created at ${stat.birthtime}`); 6 } 7});
By 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.
1import readdir from "@jsdevtools/readdir-enhanced"; 2import { resolve } from "path"; 3 4// Get absolute paths 5let absPath = resolve("my/dir"); 6readdir("my/directory", {basePath: absPath}, (err, files) => { 7 console.log(files); 8 // => /absolute/path/to/my/directory/file1.txt 9 // => /absolute/path/to/my/directory/file2.txt 10 // => /absolute/path/to/my/directory/subdir 11}); 12 13// Get paths relative to the working directory 14readdir("my/directory", {basePath: "my/directory"}, (err, files) => { 15 console.log(files); 16 // => my/directory/file1.txt 17 // => my/directory/file2.txt 18 // => my/directory/subdir 19});
By 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.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Always use Windows path separators 4readdir("my/directory", {sep: "\\", deep: true}, (err, files) => { 5 console.log(files); 6 // => subdir1 7 // => subdir1\file.txt 8 // => subdir1\subdir2 9 // => subdir1\subdir2\file.txt 10 // => subdir1\subdir2\subdir3 11 // => subdir1\subdir2\subdir3\file.txt 12});
By default, Readdir Enhanced uses the default Node.js FileSystem module 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
.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3function myCustomReaddirMethod(dir, callback) { 4 callback(null, ["__myFile.txt"]); 5} 6 7let options = { 8 fs: { 9 readdir: myCustomReaddirMethod 10 } 11}; 12 13readdir("my/directory", options, (err, files) => { 14 console.log(files); 15 // => __myFile.txt 16});
Readdir 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.
1import { readdir, readdirSync } from "@jsdevtools/readdir-enhanced"; 2 3// Use it just like Node's built-in fs.readdir function 4readdir("my/directory", (er, files) => { ... }); 5 6// Use it just like Node's built-in fs.readdirSync function 7let files = readdirSync("my/directory");
The 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.. However, we've tried to answer the most common questions here.
All 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.
Using these events, we can detect when the stream has finished reading files.
1import readdir from "@jsdevtools/readdir-enhanced"; 2 3// Build the stream using the Streaming API 4let stream = readdir.stream("my/directory") 5 .on("data", (path) => { ... }); 6 7// Listen to the end event to detect the end of the stream 8stream.on("end", () => { 9 console.log("Stream finished!"); 10});
As 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".
There are many ways to trigger flowing mode, such as adding a stream.data()
handler, using stream.pipe()
or calling stream.resume()
.
Unless you trigger flowing mode, your stream will stay paused and you won't receive any file events.
More information on paused vs. flowing mode can be found in the Node.js documentation.
Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.
To build the project locally on your computer:
Clone this repo
git clone https://github.com/JS-DevTools/readdir-enhanced.git
Install dependencies
npm install
Run the tests
npm test
Readdir Enhanced is 100% free and open-source, under the MIT license. Use it however you want.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Thanks to these awesome companies for their support of Open Source developers ❤
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
dependency not pinned by hash detected -- score normalized to 3
Details
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
Found 1/29 approved changesets -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
Reason
project is not fuzzed
Details
Reason
branch protection not enabled on development/release branches
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Reason
28 existing vulnerabilities detected
Details
Score
Last Scanned on 2024-11-25
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More