fs.readdir with sync, async, and streaming APIs + filtering, recursion, absolute paths, etc.
npm install @mrmlnc/readdir-enhancedEnhanced fs.readdir()
=======================
> :warning: This is «fork» for original readdir-enhanced package but with some monkey fixes.
readdir-enhanced is a backward-compatible drop-in replacement for fs.readdir() and fs.readdirSync() with tons of extra features (filtering, recursion, absolute paths, stats, and more) as well as additional APIs for Promises, Streams, and EventEmitters.
Pick Your API
-----------------readdir-enhanced has multiple APIs, so you can pick whichever one you prefer. There are three main APIs:
- Synchronous API
aliases: readdir.sync, readdir.readdirSync
Blocks the thread until all directory contents are read, and then returns all the results.
- Async API
aliases: readdir, readdir.async, readdir.readdirAsync
Reads the starting directory contents asynchronously and buffers all the results until all contents have been read. Supports callback or Promise syntax (see example below).
- Streaming API
aliases: readdir.stream, readdir.readdirStream
The streaming API reads the starting directory asynchronously and returns the results in real-time as they are read. The results can be piped to other Node.js streams, or you can listen for specific events via the EventEmitter interface. (see example below)
``javascript
var readdir = require('readdir-enhanced');
var through2 = require('through2');
// Synchronous API
var files = readdir.sync('my/directory');
// Callback API
readdir.async('my/directory', function(err, files) { ... });
// Promises API
readdir.async('my/directory')
.then(function(files) { ... })
.catch(function(err) { ... });
// EventEmitter API
readdir.stream('my/directory')
.on('data', function(path) { ... })
.on('file', function(path) { ... })
.on('directory', function(path) { ... })
.on('symlink', function(path) { ... })
.on('error', function(err) { ... });
// Streaming API
var stream = readdir.stream('my/directory')
.pipe(through2.obj(function(data, enc, next) {
console.log(data);
this.push(data);
next();
});
`
Enhanced Features
-----------------
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.
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.#### Crawl ALL subdirectories
The
deep option can be set to true to traverse the entire directory structure.`javascript
var readdir = require('readdir-enhanced');readdir('my/directory', {deep: true}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1/file.txt
// => subdir1/subdir2
// => subdir1/subdir2/file.txt
// => subdir1/subdir2/subdir3
// => subdir1/subdir2/subdir3/file.txt
});
`#### Crawl to a specific depth
The
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.`javascript
var readdir = require('readdir-enhanced');readdir('my/directory', {deep: 2}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1/file.txt
// => subdir1/subdir2
// => subdir1/subdir2/file.txt
// => subdir1/subdir2/subdir3
});
`#### Crawl subdirectories by name
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
.> 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
[\\/].`javascript
var readdir = require('readdir-enhanced');// Only crawl the "lib" and "bin" subdirectories
// (notice that the "node_modules" subdirectory does NOT get crawled)
readdir('my/directory', {deep: /lib|bin/}, function(err, files) {
console.log(files);
// => bin
// => bin/cli.js
// => lib
// => lib/index.js
// => node_modules
// => package.json
});
`#### Custom recursion logic
For more advanced recursion, you can set the
option to a function that accepts an fs.Stats object and returns a truthy value if the starting directory should be crawled.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. The depth is the number of subdirectories beneath the base path (see options.deep).`javascript
var readdir = require('readdir-enhanced');// Crawl all subdirectories, except "node_modules"
function ignoreNodeModules (stats) {
return stats.path.indexOf('node_modules') === -1;
}
readdir('my/directory', {deep: ignoreNodeModules}, function(err, files) {
console.log(files);
// => bin
// => bin/cli.js
// => lib
// => lib/index.js
// => node_modules
// => package.json
});
`$3
The option lets you limit the results based on any criteria you want.#### Filter by name
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
[\\/].`javascript
var readdir = require('readdir-enhanced');// Find all .txt files
readdir('my/directory', {filter: '*.txt'});
// Find all package.json files
readdir('my/directory', {filter: '**/package.json', deep: true});
// Find everything with at least one number in the name
readdir('my/directory', {filter: /\d+/});
`#### Custom filtering logic
For more advanced filtering, you can specify a filter function that accepts an
object and returns a truthy value if the item should be included in the results.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. The depth is the number of subdirectories beneath the base path (see options.deep).`javascript
var readdir = require('readdir-enhanced');// Only return file names containing an underscore
function myFilter(stats) {
return stats.isFile() && stats.path.indexOf('_') >= 0;
}
readdir('my/directory', {filter: myFilter}, function(err, files) {
console.log(files);
// => __myFile.txt
// => my_other_file.txt
// => img_1.jpg
// => node_modules
});
`$3
By default all 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.`javascript
var readdir = require('readdir-enhanced');
var path = require('path');// Get absolute paths
var absPath = path.resolve('my/dir');
readdir('my/directory', {basePath: absPath}, function(err, files) {
console.log(files);
// => /absolute/path/to/my/directory/file1.txt
// => /absolute/path/to/my/directory/file2.txt
// => /absolute/path/to/my/directory/subdir
});
// Get paths relative to the working directory
readdir('my/directory', {basePath: 'my/directory'}, function(err, files) {
console.log(files);
// => my/directory/file1.txt
// => my/directory/file2.txt
// => my/directory/subdir
});
`$3
By default, 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.`javascript
var readdir = require('readdir-enhanced');// Always use Windows path separators
readdir('my/directory', {sep: '\\', deep: true}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1\file.txt
// => subdir1\subdir2
// => subdir1\subdir2\file.txt
// => subdir1\subdir2\subdir3
// => subdir1\subdir2\subdir3\file.txt
});
`$3
By default, 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.`javascript
var readdir = require('readdir-enhanced');function myCustomReaddirMethod(dir, callback) {
callback(null, ['__myFile.txt']);
}
var options = {
fs: {
readdir: myCustomReaddirMethod
}
};
readdir('my/directory', options, function(err, files) {
console.log(files);
// => __myFile.txt
});
` objects instead of strings
------------------------
All of the readdir-enhanced functions listed above return an array of strings (paths). But in some situations, the path isn't enough information. So, readdir-enhanced provides alternative versions of each function, which return an array of fs.Stats objects instead of 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.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. The depth is the number of subdirectories beneath the base path (see options.deep).To get
fs.Stats objects instead of strings, just add the word "Stat" to the function name. As with the normal functions, each one is aliased (e.g. readdir.async.stat is the same as readdir.readdirAsyncStat), so you can use whichever naming style you prefer.`javascript
var readdir = require('readdir-enhanced');// Synchronous API
var stats = readdir.sync.stat('my/directory');
var stats = readdir.readdirSyncStat('my/directory');
// Async API
readdir.async.stat('my/directory', function(err, stats) { ... });
readdir.readdirAsyncStat('my/directory', function(err, stats) { ... });
// Streaming API
readdir.stream.stat('my/directory')
.on('data', function(stat) { ... })
.on('file', function(stat) { ... })
.on('directory', function(stat) { ... })
.on('symlink', function(stat) { ... });
readdir.readdirStreamStat('my/directory')
.on('data', function(stat) { ... })
.on('file', function(stat) { ... })
.on('directory', function(stat) { ... })
.on('symlink', function(stat) { ... });
` 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.`javascript
var readdir = require('readdir-enhanced');
var readdirSync = readdir.sync;// Use it just like Node's built-in fs.readdir function
readdir('my/directory', function(err, files) { ... });
// Use it just like Node's built-in fs.readdirSync function
var files = readdirSync('my/directory');
`Contributing
--------------------------
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
#### Building
To build the project locally on your computer:
1. __Clone this repo__
2. __Install dependencies__
3. __Run the tests__
License
--------------------------