fs-capture

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
  • Arguments
• Default options
• Setup
• Explanation
• Examples
  • Example (callback)
  • Example (promises) (recommended)
• Flows
• Important notes
• How to install
• Unit-Tests
  • Test-case: Default
  • Make
  • NPM
• Contributing
• License

---

API Reference

Capture Engine:

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

Arguments:

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

---

Setup

fs-capture can be easily set up.

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

---

Explanation

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) }

    console.log(results) 
    
    /* 
    Results
    [ 
        { 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)

---

Examples

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) }

  console.log(results) 
  
  /* 
  Results
  [ 
      { 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:

capture('/home/steven/dog')
.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:

capture('/home/steven/dog')
.each(function (result) {
  // do something with each result
})
.catch(function (err) {
  // do error handling
})

Filter the results:

capture('/home/steven/dog')
.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.

---

Flows

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

capture('/home/steven/dog')
// Captures a folder OR file by the name of dog

capture('/home/steven/dog.txt')
// 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

---

Unit-Tests

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

make test

NPM

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

---

Contributing

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

---

License

MIT