Have ideas to improve npm?Join in the discussion! »


    1.0.0 • Public • Published


    JavaScript Style Guide GitHub license Build Status npm version

    Captures a folder/file based on a path.

    We've all been to that point where we want to query a file/folder in a convenient way.

    Perhaps a file and a folder share the same name and sometimes we don't even know the extension.

    And what if we just want to gather those files/folders in a specific order?

    Here comes fs-capture into play!

    A simple module based on its tiny capture-engine, featuring a promised asynchronous control-flow.

    Read the explanation: Explanation

    Table of contents

    API Reference

    Capture Engine:

        String target,
        [Object {
            extension: String='',
            sort: int=type
        } options],
        [function(class ErrorClass err, Array results) Handler]
    ) -> function|Promise


    Argument Description
    target A path that points to a directory or file
    options An object with supplied options (optional)
    callback A nodeback (err, results)
    1st = Error
    2nd = Array

    Default options:

    By default, the capture-processor is going to check for a directory first.

    Since directory-names usually do not contain an extension (suffix), it is safe to assume that there are less zero-extension files than directories in a real-world scenario.

    However. You can simply change this behaviour to get the desired results.

        extension: '',        // (String)  any
        sort: 2,              // (int)     1 = File | 2 = Directory
    Option Description
    extension A string that contains a suffix '.js' (optional) [bound to sort]
    sort An integer of 1 = File or 2 = Folder (optional) [bound to extension]

    Important! The sort option does only work in conjunction with the extension option! read more


    fs-capture can be easily set up.

    var capture = require('@burnett01/fs-capture')


    Assume we have the following directory: /home/steven/

    Inside that directory we have a folder called code and a file called code.txt

    Based on our input { sort: 1 }, we want to catch the file first.

    capture('/home/steven/code', { extension: '.txt', sort: 1 }, 
      function (err, results) {
        if (err) { return console.log(err) }
            { path: '/home/steven/code.txt', stats: copy of fs.stat, type: 1 },
            { path: '/home/steven/code', stats: copy of fs.stat, type: 2 }

    As you can see we caught the file as specified.

    If we hadn't specified the order, the capture-processor would've returned the folder first.

    Remember: By default it is going to look for a directory first. (read more)


    Example (callback)

    Catch a directory and file called 'dog' in default order

    capture('/home/steven/dog', function (err, results) {
      if (err) { return console.log(err) }
          { path: '/home/steven/dog', stats: copy of fs.stat, type: 2 },
          { path: '/home/steven/dog.txt', stats: copy of fs.stat, type: 1 }
      Now do stuff with results

    Check the next example to get an impression on how to use options.

    Example (promises)

    Catch a directory and file called 'dog' in default order.

    Get all results:

    .then(function (results) {
        // do something with all results
    .catch(function (err) {
        // do error handling

    Get all results (2nd approach):

    capture('/home/steven/dog').all() //same as above

    Get results one by one:

    .each(function (result) {
      // do something with each result
    .catch(function (err) {
      // do error handling

    Filter the results:

    .filter(function (result) {
      return !(result.type == 2)
    .then(function (results) {
      // do something with each result
    .catch(function (err) {
      // do error handling

    There is a lot you can archive with promises.

    List of possible functions:

    • .all
    • .props
    • .any
    • .some
    • .map
    • .reduce
    • .filter
    • .each
    • .mapSeries
    • .race

    Check Bluebirds API-Reference for more.


    There are atleast 5 flows available, to be used with the callback or promises:

    // Captures a folder OR file by the name of dog
    // Captures a folder OR file by the name of dog.txt
    capture('/home/steven/dog', { extension: '.txt' })
    // Captures a folder AND file by the name of dog and dog.txt
    capture('/home/steven/dog', { extension: '.txt', sort: 1 })
    // Captures a file AND folder by the name of dog and dog.txt sorted by the file
    capture('/home/steven/dog', { extension: '.txt', sort: 2 })
    // Captures a file AND folder by the name of dog and dog.txt sorted by folder
    // This works the same as flow 3, thus redundant

    [...] to be continued

    Once you've got your results, you may want to do more: Check promises

    Important notes

    • fs-capture does not(!) read, search nor traverse the supplied target.

    It simply checks whether a file/folder exists by grabbing their stats. Check .stat()

    • An error of type ENOENT will be supressed by the capture-processor, when file and folder are not found.

    Instead, an empty Array is forwarded to the 2nd parameter of the nodeback.

    When using Promises, the .catch() handler will not be fired on ENOENT.

    Such as with the callback, an empty array is returned. It is up to the client to handle that empty array.

    Any other error will not be supressed and forwarded/thrown.

    This is intentional due to the way of how a file/folder is being processed.

    Soon, a custom error-handler ontop of Promises (or an option) will be added, to have the client catch that error.

    • The sort option does only work in conjunction with the extension option,

      since with the extension option we are telling the capture-proccessor to check for an additional file/folder.

      There is no sense in sorting a single result.

    How to install:

    Use npm install @burnett01/fs-capture


    The testing-framework used by this module is Mocha with the BDD / TDD assertion library Chai.

    Various tests are performed to make sure this module runs as smoothly as possible.

    To get an overview of a test, simply consume its source.

    • test/test.default.js Performs 18 tests | Source

    Output using Mocha list reporter:

    Default reporter: spec

    Any other reporter: make test REPORTER=nyan


    make test


    npm test

    Once executed, an entire testing file structure will be created for you. Up to 3 empty folders and files are put into test/tmp/, prior to running the tests. If you don't need that structure anymore, simply delete it by running make clean


    You're very welcome and free to contribute. Thank you.




    npm i @burnett01/fs-capture

    DownloadsWeekly Downloads






    Unpacked Size

    30.8 kB

    Total Files


    Last publish


    • avatar