Neoclassical Piano Montage

    dirator

    0.9.0 • Public • Published

    Dirator

    Build Status Dependency Status npm version Coverage Status

    Directory iterator with filters, individual and array callbacks/listeners, and both synchronous and asynchronous execution.

    // example: get all js files
    require('dirator')({
      target: 'some/dir',
      acceptPath: function(path) {
        return path.endsWith('.js')
      },
      file: function(file) {
        // do something with each file
      },
      // must have done callback for async
      done: function(error, result) {
        // check for an error
      }
    })

    Install

    npm install dirator --save
    

    Table of Contents

    1. Usage - Asynchronous via Options
    2. Usage - Asynchronous via Events
    3. Usage - Synchronous
    4. Results
    5. Modes
    6. Convenience methods
    7. Examples

    Usage: Asynchronous via Options

    You must specify a done callback to operate asynchronously.

    This example uses all other options, however, only specify the options you want and dirator will do less work.

    var dirator = require('dirator');
     
    dirator({
     
      // the starting directory path
      target: 'some/dir',
     
      // although all these can be specified,
      // only specify the ones you want.
      // except `done`. that's required to signal async.
     
      // return true to accept the path string.
      // each false return is counted
      acceptString: function(pathString) {
        return path.length > 5;
      },
     
      // return true to accept the path.
      // the `path` is an fspath instance.
      // each false return is counted.
      acceptPath: function(path) {
        return !path.endsWith('.tmp');
      },
     
      file: function(file)  {
        file.pipe(someTransform).pipe(targetStream);
      },
     
      files: function(files) {
        /* files is an array of fspath's */
      },
     
      dir  : function(dir)   {
        /* dir is an fspath */
      },
     
      dirs : function(dirs)  {
        /* dirs is an array of fspath's */
      },
     
      path : function(path)  {
        /* path is an fspath */
      },
     
      paths: function(paths) {
        /* paths is an array of fspath's */
      },
     
      done : function(error, results) {
          if (error) {
            /* do something with error and return... */
          }
     
          console.log(
            'Found',result.found.files,
            'files',
            result.found.dirs,
            'dirs, and',
            result.found.paths,
            'paths.'
          );
     
          console.log(
            'Rejected paths based on',
            result.rejected.strings,
            'path strings and',
            result.rejected.paths,
            'Path instances.'
          );
        }
    });
     
    // OR, to repeatedly use it:
    var Dirator = require('dirator').Dirator
    var dirator = new Dirator({
      target: 'some/dir'
      // all the options used above
    });
     
    // then run it.
    // you can do this repeatedly.
    dirator.run();

    Usage: Asynchronous via Events

    You must specify a done event listener to operate asynchronously.

    This example uses all other options, however, only specify the options you want and dirator will do less work.

    var Dirator = require('dirator').Dirator
      , dirator = new Dirator({target:'some/dir'});
     
    // called for each file
    dirator.on('file',  function(file) {});
     
    // called for each directory with an array
    // of fspath instances for each file
    dirator.on('files', function(files) {});
     
    // called for each accepted dir
    dirator.on('dir',   function(dir) {});
     
    // called for each directory with an array
    // of fspath instances for each
    // immediate sub-directory
    dirator.on('dirs',  function(dirs) {});
     
    // called for each accepted path
    dirator.on('path',  function(path) {});
     
    // called for each directory with an array
    // of fspath instances for each path (file/directory)
    dirator.on('paths', function(paths) {});
     
    // called when it's all done iterating.
    dirator.on('done',  function(error, result) {
      // do something with counts...
    });
     
    // now start the work.
    // can be used repeatedly.
    dirator.run();

    Usage: Synchronous

    Without a done callback/listener dirator runs synchronously and provides all results at once in returned object.

    TODO: It seems appropriate to allow adding event listeners when running synchronously because they are executed synchronously. I may include this feature in a future version. For now, don't use callbacks/listeners without a done listener/callback.

    var Dirator = require('dirator').Dirator
      , dirator = new Dirator({target:'some/dir'});
      , result = dirator.run();
     
    // OR:
    var result = require('dirator')({
      target: 'some/dir'
    })
     
    result = {
      paths: [ /* array of all paths */ ]
      found: {
        paths: // <number>
      },
      rejected: {
        strings: 0,
        paths: 0
      }
    }

    Results

    The result contains different content depending on the mode it runs in. The results are cumulative, so, the more modes you specify the more results you will receive.

    The results object always contains these:

    A. found - an object containing the number found of each mode (type) specified

    // specify all modes to get all counts
    results = dirator({ only:['files', 'dirs', 'paths'] })
    results = {
      found: { // leave out a mode above and this won't contain its count
        files: /* <number> */ ,
        dirs : /* <number> */ ,
        paths: /* <number> */
      }
    }

    B. rejected - an object containing two numbers:

    1. strings - the number of paths rejected by the acceptString filter
    2. paths - the number of paths rejected by the acceptPath filter

    The results object only contains these when its corresponding mode is specified:

    1. result.paths - available when the paths mode is specified (the default mode)
    2. result.files - available when the files mode is specified (using dirator.files() sets this mode)
    3. result.dirs - available when the dirs mode is specified (using dirator.dirs() sets this mode)

    Modes

    Dirator performs differently depending on which modes it runs with.

    It operates in paths mode by default.

    There are three modes:

    A. paths

    1. only provides paths in results object: result.paths
    2. only calls the path and paths callbacks/listeners.
    3. will iterate through directories to find all paths

    B. files

    1. only provides files in results object: result.files
    2. only calls the file and files callbacks/listeners.
    3. will iterate through directories to find all files

    C. dirs

    1. only provides dirs in results object: result.dirs
    2. only calls the dir and dirs callbacks/listeners.
    3. will iterate through directories to find all directories

    The mode can be affected in three ways:

    1. set the only property of options to an array containing one or more of: paths, files, or dirs.
    2. specify callbacks/listeners and their corresponding mode will be added. For example, the file and files options/listeners will add the files mode.
    3. specify a single mode by using a direct function for the mode: dirator.files(), dirator.dirs(), and the default does the paths mode: dirator().

    Note: If you specify both the modes to use and a callback/listener which is not part of those modes, then they will not be called. For example:

    var dirator = require('dirator');
     
    dirator({
      only: ['dirs'],
      file: function(file) {
        /* this will never be called */
      },
      done: function(error, results) {
        // this will receive `results.dirs` because of the mode
      }
    });

    Usage: Convenience methods

    For common uses there are three functions on the package's exported object. By default, these will run synchronously in their corresponding mode and return the result with all corresponding types found by recursively iterating from the current working directory down. They also accept options as described above to customize their actions.

    1. files(options)
    2. dirs(options)
    3. paths(options)
    var dirator = require('dirator')
     
    // get all the files within 'src'
    var result = dirator.files({ target: 'src' })
     
    // get all the *.js files within 'src'
    result = dirator.files({
      target: 'src',
     
      acceptString: function(pathString) {
        return '.js' === pathString.slice(-3)
      },
     
      // OR: use acceptPath as the filter:
      acceptPath: function(path) {
        return path.endsWith('.js')
      }
    })

    Examples

    Get all JS files

    Imagine a directory 'some/dir' with JS files in it and within sub-directories.

    var dirator = require('dirator')
     
    // Asynchronous:
    dirator({
      target: 'some/dir',
      acceptString: function(pathString) {
        return '.js' === pathString.slice(-3)
      },
      // OR:
      acceptPath: function(path) {
        return path.endsWith('.js')
      },
      file: function(file) {
        // this is called once for each matching file.
        // for our example,
        // do something with the file
      },
      // must have done callback for async
      done: function(error, result) {
        // check for an error
        // use result...
      }
    })
     
    // Synchronous:
    var result = dirator({
      target: 'some/dir',
      acceptString: function(pathString) {
        return '.js' === pathString.slice(-3)
      },
      // OR:
      acceptPath: function(path) {
        return path.endsWith('.js')
      }
    })
     
    result = {
      found: {
        paths: 1 // counts how many files/dirs were found
      },
      rejected: {
        paths: 0, // counts rejects, acceptPath returned false
        strings: 0 // counts rejects, acceptString returned false
      },
      paths: [
        // an `fspath` Path instance per file accepted
      ]
    }

    Get all directories

    var dirator = require('dirator')
     
    // Asynchronous:
    dirator.dirs({
      target: 'some/dir',
      dir: function(dir) {
        // this is called once for each matching directory.
      },
      // must have done callback for async
      done: function(error, result) {
        // check for an error
      }
    })
     
    // Synchronous:
    var result = dirator.dirs({ target: 'some/dir' })
     
    result = {
      found: {
        dirs: 1 // counts how many directories were found
      },
      rejected: {
        paths: 0, // counts rejects, acceptPath returned false
        strings: 0 // counts rejects, acceptString returned false
      },
      dirs: [
        // an `fspath` Path instance per directory accepted
      ]
    }
     
     
    // Or, get them in chunks:
    dirator.dirs({
      target: 'some/dir',
      dirs: function(dirs) {
        // dirs is an array of fspath Path instances.
        // as we iterate down thru directories we call this
        // with all the directories within one of the directories.
      },
      done: function(error) { /* ... */ }
    })
     

    MIT License

    Install

    npm i dirator

    DownloadsWeekly Downloads

    26

    Version

    0.9.0

    License

    MIT

    Last publish

    Collaborators

    • elidoran