Namespace Pollution Mechanism

    async-folder-walker

    2.1.1 • Public • Published

    async-folder-walker

    Actions Status

    A recursive async iterator of the files and directories in a given folder. Can take multiple folders, limit walk depth and filter based on path names and stat results.

    Installation

    npm install async-folder-walker
    

    Usage

    const { asyncFolderWalker, allFiles } = require('async-folder-walker')
    
    async function iterateFiles () {
      const walker = asyncFolderWalker(['.git', 'node_modules'])
      for await (const file of walker) {
        console.log(file) // logs the file path!
      }
    }
    
    async function getAllFiles () {
      const allFilepaths = await allFiles(['.git', 'node_modules'])
      console.log(allFilepaths)
    }
    
    iterateFiles().then(() => getAllFiles())

    API

    const { asyncFolderWalker, allFiles } = require('async-folder-walker')

    Import asyncFolderWalker or allFiles.

    async-gen = asyncFolderWalker(paths, [opts])

    Return an async generator that will iterate over all of files inside of a directory. paths can be a string path or an Array of string paths.

    You can iterate over each file and directory individually using a for-await...of loop. Note, you must be inside an async function statement.

    const { asyncFolderWalker } = require('async-folder-walker');
    async function iterateFiles () {
      const walker = asyncFolderWalker(['.git', 'node_modules']);
      for await (const file of walker) {
        console.log(file); // logs the file path!
      }
    }
    
    iterateFiles();

    Opts include:

    {
      fs: require('fs'),
      pathFilter: filepath => true,
      statFilter st => true,
      ignore: [],
      maxDepth: Infinity,
      shaper: ({ root, filepath, stat, relname, basename }) => filepath
    }

    The pathFilter function allows you to filter files from additional async stat operations. Return false to filter the file.

    { // exclude node_modules
      pathFilter: filepath => !filepath.includes(node_modules)
    }

    The statFilter function allows you to filter files based on the internal stat operation. Return false to filter the file.

    { // exclude all directories:
      statFilter: st => !st.isDirectory()
    }

    The ignore option can be a string or or array of strings that should follow gitignore style ignore strings. Files and directories that match are ignored.

    { // Ignore node_modules at any depth and any file starting with a .
      ['node_modules', '.*']
    }

    The shaper function lets you change the shape of the returned value based on data accumulaed during the iteration. To return the same shape as okdistribute/folder-walker use the following function:

    { // Return the same shape as folder-walker
      shaper: fwData => fwData
    }

    Example of a fwData object for a directory:

    {
      root: '/Users/bret/repos/async-folder-walker/fixtures',
      filepath: '/Users/bret/repos/async-folder-walker/fixtures/sub-folder/sub-sub-folder',
      stat: Stats {
        dev: 16777220,
        mode: 16877,
        nlink: 3,
        uid: 501,
        gid: 20,
        rdev: 0,
        blksize: 4096,
        ino: 30244023,
        size: 96,
        blocks: 0,
        atimeMs: 1574381262779.8396,
        mtimeMs: 1574380914743.5474,
        ctimeMs: 1574380914743.5474,
        birthtimeMs: 1574380905232.5996,
        atime: 2019-11-22T00:07:42.780Z,
        mtime: 2019-11-22T00:01:54.744Z,
        ctime: 2019-11-22T00:01:54.744Z,
        birthtime: 2019-11-22T00:01:45.233Z
      },
      relname: 'sub-folder/sub-sub-folder',
      basename: 'sub-sub-folder'
    }

    and another example for a file on windows:

    {
      root: 'D:\\a\\async-folder-walker\\async-folder-walker\\fixtures',
      filepath: 'D:\\a\\async-folder-walker\\async-folder-walker\\fixtures\\sub-folder\\sub-sub-folder\\sub-sub-folder-file.json',
      stat: Stats {
        dev: 1321874112,
        mode: 33206,
        nlink: 1,
        uid: 0,
        gid: 0,
        rdev: 0,
        blksize: 4096,
        ino: 562949953421580,
        size: 37,
        blocks: 0,
        atimeMs: 1577476819530.035,
        mtimeMs: 1577476819530.035,
        ctimeMs: 1577476819530.035,
        birthtimeMs: 1577476819530.035,
        atime: 2019-12-27T20:00:19.530Z,
        mtime: 2019-12-27T20:00:19.530Z,
        ctime: 2019-12-27T20:00:19.530Z,
        birthtime: 2019-12-27T20:00:19.530Z
      },
      relname: 'sub-folder\\sub-sub-folder\\sub-sub-folder-file.json',
      basename: 'sub-sub-folder-file.json'
    }

    The stat property is an instance of fs.Stats so it has extra methods not listed here.

    files = await allFiles(paths, [opts])

    Get an Array of all files inside of a directory. paths can be a single string path or an array of string paths.

    opts Is the same as asyncFolderWalker.

    See also

    This module is effectivly a rewrite of okdistribute/folder-walker using async generators instead of Node streams, and a few tweaks to the underlying options to make the results a bit more flexible.

    License

    MIT

    Keywords

    none

    Install

    npm i async-folder-walker

    DownloadsWeekly Downloads

    16

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    23.9 kB

    Total Files

    17

    Last publish

    Collaborators

    • bret