{"id":22362772,"url":"https://github.com/danmasta/walk","last_synced_at":"2026-01-05T01:11:17.548Z","repository":{"id":42348186,"uuid":"117478282","full_name":"danmasta/walk","owner":"danmasta","description":"Directory and file walking utility for node apps","archived":false,"fork":false,"pushed_at":"2025-06-14T04:13:24.000Z","size":460,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-14T05:23:36.957Z","etag":null,"topics":["async","directory","file","node","promise","stream","walk"],"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/danmasta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"zenodo":null}},"created_at":"2018-01-15T00:20:05.000Z","updated_at":"2025-06-14T04:13:25.000Z","dependencies_parsed_at":"2024-05-02T00:37:40.576Z","dependency_job_id":"8cefdab2-2f1a-4812-a345-2b072a32f856","html_url":"https://github.com/danmasta/walk","commit_stats":{"total_commits":64,"total_committers":1,"mean_commits":64.0,"dds":0.0,"last_synced_commit":"3b94d77f4233f8919cefcc5d169d7606c05f89a3"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/danmasta/walk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fwalk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fwalk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fwalk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fwalk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danmasta","download_url":"https://codeload.github.com/danmasta/walk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danmasta%2Fwalk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267882833,"owners_count":24160214,"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","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["async","directory","file","node","promise","stream","walk"],"created_at":"2024-12-04T17:11:41.884Z","updated_at":"2026-01-05T01:11:17.523Z","avatar_url":"https://github.com/danmasta.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Walk\nDirectory and file walking utility for node apps\n\n#### Features:\n* Easy to use\n* Simple, lightweight, and fast\n* Native esm and cjs support\n* Support for filtering with glob pattern matching\n* Support for require-style path resolving\n* Include and exclude pattern matching options\n* Normalized [`File`](#file-objects) objects with helper methods\n* Includes async and sync api\n* Supports multiple interfaces:\n    * `Readable Stream`\n    * `Promise`\n    * `Iterable`\n    * `AsyncIterable`\n    * `Generator`\n    * `AsyncGenerator`\n    * Iteration helpers: `each`, `map`, `tap`\n* 1 external dependency\n\n## About\nI needed a better way to walk directories and read files during build and/or run time. I wanted an api that was simple, supported glob pattern matching, and returned objects with a similar format as vinyl. This package allows you to simply read any directory (or file), filter results with glob pattern matching, and return an array of [`File`](#file-objects) objects.\n\n## Usage\nAdd walk as a dependency for your app and install via npm\n```sh\nnpm install walk@danmasta/walk --save\n```\nInstall a specific [version](https://github.com/danmasta/walk/tags)\n```sh\nnpm install walk@danmasta/walk#v0.0.1 --save\n```\nImport or require the package in your app\n```js\nimport walk from 'walk';\n```\n\n### Options\nName | Type | Description\n-----|----- | -----------\n`cwd` | *`string`* | Base directory to start walk from. Default is `process.cwd`\n`root` | *`string`* | Root directory or file to walk from. This affects the relative paths used in [`File`](#file-objects) objects and matching. Default is `.`\n`src` | *`string\\|string[]`* | [Picomatch pattern](https://github.com/micromatch/picomatch#picomatch-1) for result filtering by including matches. Can be a path string, glob pattern string, or an array of strings. Defaults to `*(../)*(**/)*`\n`ignore` | *`string\\|string[]`* | [Picomatch pattern](https://github.com/micromatch/picomatch#picomatch-1) for result filtering by excluding matches. Can be a path string, glob pattern string, or an array of strings. Defaults to `*(../)*(**/)(.git\\|node_modules)`\n`bash` | *`boolean`* | Enable following bash matching rules more strictly (disallow backslashes as escape characters, and treat single stars as globstars `**`). Default is `false`\n`dot` | *`boolean`* | Whether or not to include dot files when matching. Default is `true`\n`posix` | *`boolean`* | Support posix character classes (brackets) when matching. Default is `false`\n`regex` | *`boolean`* | Support regular expression rules for `+`, and stars `*` that follow parenthesis or brackets when matching. Default is `false`\n`encoding` | *`string\\|null`* | Which encoding to use when reading and writing File contents. Default is `utf8`\n`require` | *`boolean`* | Enable using `require.resovle` to resolve paths if not found. Default is `false`\n`paths` | *`string\\|string[]`* | Which paths to walk to find files. Default is `undefined`\n`include` | *`function`* | Custom function to use for path matching for including files. Function will receive 1 argument `path` and should return a `boolean`. Default is `undefined`\n`exclude` | *`function`* | Custom function to use for path matching for excluding files. Function will receive 1 argument `path` and should return a `boolean`. Default is `undefined`\n\n### Methods\nName | Description\n-----|------------\n`each(fn)` | Run an iterator function for each file. Returns a promise that resolves with the `Walk` instance if `fn` is async. Otherwise returns the `Walk` instance\n`map(fn)` | Run an iterator function for each file. Returns a promise that resolves with an array of return values if `fn` is async. Otherwise returns an array of return values\n`tap(fn)` | Run an iterator function for each file. Returns a promise that resolves with an `array` of File objects if `fn` is async. Otherwise returns an array of File objects\n`promise()` | Returns a promise that resolves with an `array` of File objects\n`Symbol.asyncIterator()` | Returns an [`AsyncIterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator)\n`Symbol.iterator()` | Returns a synchronus [`Iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator)\n`generator()` | Returns an [`AsyncGenerator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator)\n`generatorSync()` | Returns a synchronous [`Generator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator)\n\n## File Objects\nEach `File` object returned from walk has the following signature:\n### Properties\nName | Type | Description\n-----|----- | -----------\n`cwd` | *`string`* | Current working directory. Default is `process.cwd`\n`root` | *`string`* | Base directory to use for relative pathing. Default is `cwd`\n`path` | *`string`* | Absolute path of file on disk\n`relative` | *`string`* | Relative path to file from `root`\n`relativeFromCwd` | *`string`* | Relative path to file from `cwd`\n`dir` | *`string`* | Parent directory where file is located\n`base` | *`string`* | File name with extension\n`name` | *`string`* | File name without extension\n`ext` | *`string`* | File extension\n`stat` | *`object`* | The [`fs.stat`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object for file. Default is `undefined`\n`contents` | *`string\\|object`* | Contents of file. Default is `undefined`\n`encoding` | *`string`* | Default encoding to use when reading or writing file contents. Default is `utf8`\n\n### Methods\nName | Description\n-----| -----------\n[`createReadStream(opts)`](https://nodejs.org/api/fs.html#fscreatereadstreampath-options) | Returns a `Readable` stream for File\n[`createWriteStream(opts)`](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) | Returns a `Writable` stream for File\n[`append(data, opts)`](https://nodejs.org/api/fs.html#fspromisesappendfilepath-data-options) | Append data to File\n[`appendSync(data, opts)`](https://nodejs.org/api/fs.html#fsappendfilesyncpath-data-options) | Synchronous alias for `append`\n[`read(opts)`](https://nodejs.org/api/fs.html#fspromisesreadfilepath-options) | Read File contents. Returns `string` or `buffer` based on encoding\n[`readSync(opts)`](https://nodejs.org/api/fs.html#fsreadfilesyncpath-options) | Synchronous alias for `read`\n`readAsString(opts)` | Shortcut for `read` that verifies encoding is set or throws an error\n`readAsStringSync(opts)` | Synchronous alias for `readAsString`\n`readAsBuffer(opts)` | Shortcut for `read` that sets the encoding to `null`\n`readAsBufferSync(opts)` | Synchronous alias for `readAsBuffer`\n`readStr` | Alias for `readAsString`\n`readStrSync` | Alias for `readAsStringSync`\n`readBuf` | Alias for `readAsBuffer`\n`readBufSync` | Alias for `readAsBufferSync`\n[`write(data, opts)`](https://nodejs.org/api/fs.html#fspromiseswritefilefile-data-options) | Write data to File\n[`writeSync(data, opts)`](https://nodejs.org/api/fs.html#fspromiseswritefilefile-data-options) | Synchronous alias for `write`\n`require()` | Read File contents using `require`. Returns an `object`\n`import()` | Read File contents using `import`. Returns a `promise`\n`importOrRequire()` | Read File contents using `import` or `require` based on esm-ness. Returns a `promise` if `imported`, or an `object` if `required`\n`importRequireOrRead()` | Read File contents using `import` or `require` if able, otherwise read as `string` or `buffer` based on encoding. Returns a `promise`\n`isModule()` | Returns `true` if `contents` is a [`Module`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import#module_namespace_object)\n`isBuffer()` | Returns `true` if `contents` is a [`Buffer`](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_isbuffer_obj)\n`isStream()` | Returns `true` if `contents` is a [`Stream`](https://nodejs.org/api/stream.html)\n`isNull()` | Returns `true` if `contents` is `null`\n`isNil()` | Returns `true` if `contents` is `null` or `undefined`\n`isString()` | Returns `true` if `contents` is a `string`\n`isDirectory()` | Returns `true` if File is a [directory](https://nodejs.org/api/fs.html#fs_stats_isdirectory)\n`isSymbolicLink()` | Returns `true` if File is a [symbolic link](https://nodejs.org/api/fs.html#fs_stats_issymboliclink)\n`isBlockDevice()` | Returns `true` if File is a [block device](https://nodejs.org/api/fs.html#fs_stats_isblockdevice)\n`isCharacterDevice()` | Returns `true` if File is a [character device](https://nodejs.org/api/fs.html#fs_stats_ischaracterdevice)\n`isFIFO()` | Returns `true` if File is a [first-in-first-out (FIFO) pipe](https://nodejs.org/api/fs.html#fs_stats_isfifo)\n`isFile()` | Returns `true` if File is a [file](https://nodejs.org/api/fs.html#fs_stats_isfile)\n`isSocket()` | Returns `true` if File is a [socket](https://nodejs.org/api/fs.html#fs_stats_issocket)\n`isEmpty()` | Returns `true` if File is empty (zero bytes)\n`getEncodingFromBOM()` | Returns encoding from the File [Byte Order Mark](https://en.wikipedia.org/wiki/Byte_order_mark#Byte_order_marks_by_encoding) if set, otherwise `undefined`\n`getEncodingFromBOMSync()` | Synchronous alias for `getEncodingFromBOM`\n\n## Examples\n```js\nimport walk from 'walk';\n```\n#### Walk the current working directory as `Readable` stream, pipe all Files to a destination stream\n```js\nwalk().pipe(...);\n```\n#### Walk the current working directory, exclude all `.json` Files, return a promise\n```js\nwalk({ src: '**/*.!(json)' }).promise().then(files =\u003e {\n    ...\n});\n```\n#### Walk a child directory, include only `.json` Files, return a promise\n```js\nwalk('config', { src: '**/*.json' }).promise().then(files =\u003e {\n    ...\n});\n```\n#### Use `async/await`\n```js\nlet files = await walk().promise();\n```\n#### Iterate synchronously using `for...of`\n```js\nfor (const file of walk()) {\n    ...\n}\n```\n#### Iterate asynchronously using `for await...of`\n```js\nfor await (const file of walk()) {\n    ...\n}\n```\n#### Iterate synchronously with a `Generator`\n```js\nfor (const file of walk().generatorSync()) {\n    ...\n}\n```\n#### Iterate asynchronously with an `AsyncGenerator`\n```js\nfor await (const file of walk().generator()) {\n    ...\n}\n```\n#### Iterate asynchronously using the built in `map` iteration method:\n```js\nconst files = await walk().map(async file =\u003e {\n    file.contents = await file.read();\n    return file;\n});\n```\n*Note: The built in iteration methods `each`, `map`, and `tap` can be awaited by passing an `async` iterator fn. If a regular function is passed they will iterate synchronously*\n\n#### Iterate synchronously using the built in `tap` iteration method:\n```js\nconst files = walk().tap(file =\u003e {\n    file.contents = file.readBufSync();\n});\n```\n#### Get a list of files as an array, synchronously\n```js\nimport { sync as walk } from 'walk';\nconst files = walk('src');\n```\n#### Walk directory using an absolute path\n```js\nwalk('/usr/local').promise().then(files =\u003e {\n    ...\n});\n```\n#### Read the contents of all `pug` files in the `views` directory as a `string`\n```js\nawait walk('views', { src: '**/*.pug' }).tap(async file =\u003e {\n    let tpl = await file.readStr();\n});\n```\n#### Import all `js` files in the `routes` directory\n```js\nawait walk('routes', { src: '**/*.js' }).each(async route =\u003e {\n    app.use(await route.import());\n});\n```\n\n## Testing\nTests are currently run using mocha and chai. To execute tests run `make test`. To generate unit test coverage reports run `make coverage`\n\n## Contact\nIf you have any questions feel free to get in touch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanmasta%2Fwalk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanmasta%2Fwalk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanmasta%2Fwalk/lists"}