API Usage

Path: /src/index.coffee compiled to /lib/index.js

For the standard node.js functions everything is the same as far as not listed below.

Extended Functionality

All the extended functions use the same naming convention as the node core, making the use nearly natural. And you can still use the native Node.js methods, also.

Some of the native methods are slightly changed: -File Stats - file stat retrieval (with caching)

Additional methods: -Make Directories - recursive create depth directory with it’s parents -Find Binary - find binary in NPM path -Temp Directory - create temporary directory -Temp File - create temporary file

Working on multiple files using filter rules: -Find Files - search for files or directories -Copy Files - copy file, directory or selection -Move Files - move file, directory or selection -Remove Files - remove file, directory or selection -Touch Files - touch file -Change Ownership - change ownership of file, directory or selection -Change Mode - change access rights of file, directory or selection

Most methods use an options object which can specify how it works. The options are based on the tree serach andfilter specification. Some also have their own options described within the method itself.

Async vs Sync

All this methods may be called asynchroneous or synchroneous.

Because the decision of using asynchroneous or synchroneous methods is based on blocking IO as far as possible you should better use this methods async and do some other things in parallel.

Only if your could is synchroneous anyway and you can’t do other things while the IO works the use of the corresponding ...Sync() methods are easier to add. It will also be more readable in major to guys not so involved in async programming.

Asynchroneous call:

CoffeeScript Code
fs.find '/tmp/some/directory',
  filter:
    include: '*.jpg'
, (err, list) ->
  return console.error err.message if err
  console.log "Found " + list.length + " images."
  # do something with list

Synchroneous call:

CoffeeScript Code
try
  list = fs.findSync '/tmp/some/directory',
    filter:
      include: '*.jpg'
catch error
  return console.error error.message
console.log "Found " + list.length + " images."
# do something with list

Differences are always the same:

  • async version needs a callback as last parameter
  • error and result will be retrieved in callback for async version
  • the sync version may throw an error and return the result directly

Because the preferred way is to use asynchroneous calls this is also shown in all the examples.

A lot of the extended methods allow traversing the directory tree and checking the found entries through thefilter options.

For file parsing the following options may be specified:

  • filter - Array<Object>|ObjectFilter Rules
  • dereference - Boolean don’t use the symbolic link as an entry but dereference it and check the target of it and go into it (default: false)
  • ignoreErrors - Boolean ignore dead symlinks otherwise an Error is created (default: false)
  • parallel - Integer number of maximum parallel calls in asynchronous run (defaults to half of open files limit per process on the system)

For all other look into the method description.

Debugging

This module uses thedebug module so you may anytime call your app with the environment setting DEBUG=fs:* but keep in mind that this will output a lot of information. So better use the concrete setting in each module. Most have one defined with their name:

DEBUG=fs:*      -> complete fs package
DEBUG=fs:copy   -> only copy method