{ "name": "@mrmlnc/readdir-enhanced", "versions": { "2.2.0": { "name": "@mrmlnc/readdir-enhanced", "version": "2.2.0", "description": "fs.readdir with sync, async, and streaming APIs + filtering, recursion, absolute paths, etc.", "keywords": [ "fs", "readdir", "stream", "event", "recursive", "deep", "filter", "absolute" ], "author": { "name": "James Messinger", "url": "http://bigstickcarpet.com" }, "homepage": "https://github.com/bigstickcarpet/readdir-enhanced", "repository": { "type": "git", "url": "git+https://github.com/bigstickcarpet/readdir-enhanced.git" }, "license": "MIT", "main": "lib/index.js", "typings": "types.d.ts", "files": [ "lib" ], "scripts": { "lint": "eslint lib test --fix", "test": "mocha && npm run lint", "cover": "istanbul cover _mocha", "upgrade": "npm-check -u", "bump": "bump --prompt --tag --push --all", "release": "npm run upgrade && npm test && npm run bump && npm publish" }, "devDependencies": { "chai": "^4.1.2", "codacy-coverage": "^2.0.3", "coveralls": "^3.0.0", "del": "^3.0.0", "eslint": "^4.15.0", "eslint-config-modular": "^4.1.1", "istanbul": "^0.4.5", "mkdirp": "^0.5.1", "mocha": "^4.1.0", "npm-check": "^5.5.2", "through2": "^2.0.3", "version-bump-prompt": "^4.0.0" }, "dependencies": { "call-me-maybe": "^1.0.1", "glob-to-regexp": "^0.3.0" }, "engines": { "node": ">=4" }, "gitHead": "1580afe4fdf21cd191c202ec599d1ca7d0ab062d", "bugs": { "url": "https://github.com/bigstickcarpet/readdir-enhanced/issues" }, "_id": "@mrmlnc/readdir-enhanced@2.2.0", "_npmVersion": "5.6.0", "_nodeVersion": "9.4.0", "_npmUser": { "name": "mrmlnc", "email": "dmalinochkin@rambler.ru" }, "dist": { "integrity": "sha512-GcwPZ/nVuAfz43kkftB6itI/3Z22oQe1xcCjvOeSG15T6235nkmP741BWIo2FSuosO53uCmKIEEfYGRmor8ZjA==", "shasum": "27df53d3d140fef15caab926642f7ec35cc9e819", "tarball": "https://registry.npmjs.org/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.0.tgz", "fileCount": 15, "unpackedSize": 51301 }, "maintainers": [ { "name": "mrmlnc", "email": "dmalinochkin@rambler.ru" } ], "directories": {}, "_npmOperationalInternal": { "host": "s3://npm-registry-packages", "tmp": "tmp/readdir-enhanced_2.2.0_1518538924504_0.7427640544933949" }, "contributors": [] }, "2.2.1": { "name": "@mrmlnc/readdir-enhanced", "version": "2.2.1", "description": "fs.readdir with sync, async, and streaming APIs + filtering, recursion, absolute paths, etc.", "keywords": [ "fs", "readdir", "stream", "event", "recursive", "deep", "filter", "absolute" ], "author": { "name": "James Messinger", "url": "http://bigstickcarpet.com" }, "homepage": "https://github.com/bigstickcarpet/readdir-enhanced", "repository": { "type": "git", "url": "git+https://github.com/bigstickcarpet/readdir-enhanced.git" }, "license": "MIT", "main": "lib/index.js", "typings": "types.d.ts", "files": [ "lib", "types.d.ts" ], "scripts": { "lint": "eslint lib test --fix", "test": "mocha && npm run lint", "cover": "istanbul cover _mocha", "upgrade": "npm-check -u", "bump": "bump --prompt --tag --push --all", "release": "npm run upgrade && npm test && npm run bump && npm publish" }, "devDependencies": { "chai": "^4.1.2", "codacy-coverage": "^2.0.3", "coveralls": "^3.0.0", "del": "^3.0.0", "eslint": "^4.15.0", "eslint-config-modular": "^4.1.1", "istanbul": "^0.4.5", "mkdirp": "^0.5.1", "mocha": "^4.1.0", "npm-check": "^5.5.2", "through2": "^2.0.3", "version-bump-prompt": "^4.0.0" }, "dependencies": { "call-me-maybe": "^1.0.1", "glob-to-regexp": "^0.3.0" }, "engines": { "node": ">=4" }, "gitHead": "1580afe4fdf21cd191c202ec599d1ca7d0ab062d", "bugs": { "url": "https://github.com/bigstickcarpet/readdir-enhanced/issues" }, "_id": "@mrmlnc/readdir-enhanced@2.2.1", "_npmVersion": "5.6.0", "_nodeVersion": "9.4.0", "_npmUser": { "name": "mrmlnc", "email": "dmalinochkin@rambler.ru" }, "dist": { "integrity": "sha512-bPHp6Ji8b41szTOcaP63VlnbbO5Ny6dwAATtY6JTjh5N2OLrb5Qk/Th5cRkRQhkWCt+EJsYrNB0MiL+Gpn6e3g==", "shasum": "524af240d1a360527b730475ecfa1344aa540dde", "tarball": "https://registry.npmjs.org/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.1.tgz", "fileCount": 16, "unpackedSize": 53874 }, "maintainers": [ { "name": "mrmlnc", "email": "dmalinochkin@rambler.ru" } ], "directories": {}, "_npmOperationalInternal": { "host": "s3://npm-registry-packages", "tmp": "tmp/readdir-enhanced_2.2.1_1518542538843_0.9963591147462021" }, "contributors": [] } }, "time": { "created": "2018-02-13T16:22:04.135Z", "2.2.0": "2018-02-13T16:22:05.125Z", "modified": "2018-02-13T17:22:21.231Z", "2.2.1": "2018-02-13T17:22:19.584Z" }, "users": {}, "dist-tags": { "latest": "2.2.1" }, "_uplinks": { "npmjs": { "etag": "W/\"b41211d6b8fa32efd946cc453a03c6cd\"", "fetched": 1593324456340 } }, "_distfiles": { "readdir-enhanced-2.2.0.tgz": { "url": "https://registry.npmjs.org/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.0.tgz", "sha": "27df53d3d140fef15caab926642f7ec35cc9e819", "registry": "npmjs" }, "readdir-enhanced-2.2.1.tgz": { "url": "https://registry.npmjs.org/@mrmlnc/readdir-enhanced/-/readdir-enhanced-2.2.1.tgz", "sha": "524af240d1a360527b730475ecfa1344aa540dde", "registry": "npmjs" } }, "_attachments": { "readdir-enhanced-2.2.1.tgz": { "shasum": "524af240d1a360527b730475ecfa1344aa540dde" } }, "_rev": "2-765e63b15e3df23e", "_id": "@mrmlnc/readdir-enhanced", "readme": "Enhanced `fs.readdir()`\n=======================\n\n> :warning: This is «fork» for original `readdir-enhanced` package but with some monkey fixes.\n\n[![Build Status](https://api.travis-ci.org/BigstickCarpet/readdir-enhanced.svg?branch=master)](https://travis-ci.org/BigstickCarpet/readdir-enhanced)\n[![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/bigstickcarpet/readdir-enhanced?svg=true&branch=master&failingText=Windows%20build%20failing&passingText=Windows%20build%20passing)](https://ci.appveyor.com/project/BigstickCarpet/readdir-enhanced/branch/master)\n\n[![Coverage Status](https://coveralls.io/repos/github/BigstickCarpet/readdir-enhanced/badge.svg?branch=master)](https://coveralls.io/github/BigstickCarpet/readdir-enhanced?branch=master)\n[![Codacy Score](https://api.codacy.com/project/badge/Grade/178a817b6c864de7813fef457c0ed5ae)](https://www.codacy.com/public/jamesmessinger/readdir-enhanced)\n[![Inline docs](http://inch-ci.org/github/BigstickCarpet/readdir-enhanced.svg?branch=master&style=shields)](http://inch-ci.org/github/BigstickCarpet/readdir-enhanced)\n[![Dependencies](https://david-dm.org/BigstickCarpet/readdir-enhanced.svg)](https://david-dm.org/BigstickCarpet/readdir-enhanced)\n\n[![npm](https://img.shields.io/npm/v/readdir-enhanced.svg?maxAge=43200)](https://www.npmjs.com/package/readdir-enhanced)\n[![License](https://img.shields.io/npm/l/readdir-enhanced.svg?maxAge=2592000)](LICENSE)\n\n`readdir-enhanced` is a [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) with tons of extra features ([filtering](#filter), [recursion](#deep), [absolute paths](#basepath), [stats](#stats), and more) as well as additional APIs for Promises, Streams, and EventEmitters.\n\n\nPick Your API\n-----------------\n`readdir-enhanced` has multiple APIs, so you can pick whichever one you prefer. There are three main APIs:\n\n- **Synchronous API**
\naliases: `readdir.sync`, `readdir.readdirSync`
\nBlocks the thread until all directory contents are read, and then returns all the results.\n\n- **Async API**
\naliases: `readdir`, `readdir.async`, `readdir.readdirAsync`
\nReads the starting directory contents asynchronously and buffers all the results until all contents have been read. Supports callback or Promise syntax (see example below).\n\n- **Streaming API**
\naliases: `readdir.stream`, `readdir.readdirStream`
\nThe streaming API reads the starting directory asynchronously and returns the results in real-time as they are read. The results can be [piped](https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options) to other Node.js streams, or you can listen for specific events via the [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) interface. (see example below)\n\n```javascript\nvar readdir = require('readdir-enhanced');\nvar through2 = require('through2');\n\n// Synchronous API\nvar files = readdir.sync('my/directory');\n\n// Callback API\nreaddir.async('my/directory', function(err, files) { ... });\n\n// Promises API\nreaddir.async('my/directory')\n .then(function(files) { ... })\n .catch(function(err) { ... });\n\n// EventEmitter API\nreaddir.stream('my/directory')\n .on('data', function(path) { ... })\n .on('file', function(path) { ... })\n .on('directory', function(path) { ... })\n .on('symlink', function(path) { ... })\n .on('error', function(err) { ... });\n\n// Streaming API\nvar 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\nEnhanced Features\n-----------------\n`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](#backward-compatible). You can enable any of the features by passing-in an `options` argument as the second parameter.\n\n\n\n### Recursion\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\nvar readdir = require('readdir-enhanced');\n\nreaddir('my/directory', {deep: true}, function(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\nvar readdir = require('readdir-enhanced');\n\nreaddir('my/directory', {deep: 2}, function(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\nvar readdir = require('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/}, function(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\nvar readdir = require('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}, function(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### Filtering\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\nvar readdir = require('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\nvar readdir = require('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}, function(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### Base Path\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\nvar readdir = require('readdir-enhanced');\nvar path = require('path');\n\n// Get absolute paths\nvar absPath = path.resolve('my/dir');\nreaddir('my/directory', {basePath: absPath}, function(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'}, function(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### Path Separator\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\nvar readdir = require('readdir-enhanced');\n\n// Always use Windows path separators\nreaddir('my/directory', {sep: '\\\\', deep: true}, function(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### Custom FS methods\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\nvar readdir = require('readdir-enhanced');\n\nfunction myCustomReaddirMethod(dir, callback) {\n callback(null, ['__myFile.txt']);\n}\n\nvar options = {\n fs: {\n readdir: myCustomReaddirMethod\n }\n};\n\nreaddir('my/directory', options, function(err, files) {\n console.log(files);\n // => __myFile.txt\n});\n```\n\n\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. So, `readdir-enhanced` provides alternative versions of each function, which return an array of [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_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.\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\nTo 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.\n\n```javascript\nvar readdir = require('readdir-enhanced');\n\n// Synchronous API\nvar stats = readdir.sync.stat('my/directory');\nvar stats = readdir.readdirSyncStat('my/directory');\n\n// Async API\nreaddir.async.stat('my/directory', function(err, stats) { ... });\nreaddir.readdirAsyncStat('my/directory', function(err, stats) { ... });\n\n// Streaming API\nreaddir.stream.stat('my/directory')\n .on('data', function(stat) { ... })\n .on('file', function(stat) { ... })\n .on('directory', function(stat) { ... })\n .on('symlink', function(stat) { ... });\n\nreaddir.readdirStreamStat('my/directory')\n .on('data', function(stat) { ... })\n .on('file', function(stat) { ... })\n .on('directory', function(stat) { ... })\n .on('symlink', function(stat) { ... });\n\n```\n\n\nBackward Compatible\n--------------------\n`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.\n\n```javascript\nvar readdir = require('readdir-enhanced');\nvar readdirSync = readdir.sync;\n\n// Use it just like Node's built-in fs.readdir function\nreaddir('my/directory', function(err, files) { ... });\n\n// Use it just like Node's built-in fs.readdirSync function\nvar files = readdirSync('my/directory');\n```\n\n\n\nContributing\n--------------------------\nI welcome any contributions, enhancements, and bug-fixes. [File an issue](https://github.com/BigstickCarpet/readdir-enhanced/issues) on GitHub and [submit a pull request](https://github.com/BigstickCarpet/readdir-enhanced/pulls).\n\n#### Building\nTo build the project locally on your computer:\n\n1. __Clone this repo__
\n`git clone https://github.com/bigstickcarpet/readdir-enhanced.git`\n\n2. __Install dependencies__
\n`npm install`\n\n3. __Run the tests__
\n`npm test`\n\n\n\nLicense\n--------------------------\n`readdir-enhanced` is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want." }