vigour-fs

vigour-fs

node's fs module with sugar on top + native support.

This document describes only the sugar. For the meat and potatoes, refer to the nodejs docs.

Versioning

This module respects the semver versioning methodology

Installation

npm install vigour-fs

Usage

Same as node's fs module, e.g.

var fs = require('vigour-fs');

fs.readFile('somefile.txt', 'utf8', function(err, data) {
  console.log(data, err)
})

Modification to node's fs "API"

All methods provided in vigour-fs that also exist in fs should behave exactly the same, except for these extra features:

• mkdirp option

fs.writeFile accepts a mkdirp option, which will create any missing subdirectories

fs.writeFile("path/with/inexistent/subdirectories/file.txt"
, "Hello World"
, { mkdirp: true }
, function (err) {
  if (!err) {
    console.log("File will be written to specified path, with subdirectories created as needed")
  }
})

• read from URL

fs.readFile and fs.writeFile can accept a URL as path, in which case they will perform a GET request to that url.

fs.readFile('http://perdu.com', 'utf8', function (err, data) {
  if (!err) {
    console.log("html from perdu.com", data)
  }
})

fs.writeFile('perdu.html', 'http://perdu.com', 'utf8', function (err) {
  if (!err) {
    console.log("perdu.html now contains the html from perdu.com")
  }
})

This means fs.readFile and fs.writeFile come with extra options.

Option	Possible values	Default	Description
url	true false	true	Whether to treat path as a url. If false, treats path as a local file path. Otherwise, treats path as a url if and only if it starts with http:// or https://
followRedirects	true false	true	Whether to follow redirects (301, 302, 303, 305, 307, 308)
maxTries	Positive integer above 0	1	Number of attempts to make in total. If over 1, will retry the request if the response's status code is 500 or 503. Use the retryOn404 option to retry on 404 as well (not recommended).
retryDelay	Positive integer	500	Time to wait before retrying the first time, in milliseconds. Subsequent attempts may use a different delay, dependant on the retryDelayType option. The delay may also be given by a 'retry-after' header accompanying a 503 response (see the respectRetryAfter option). In any case, the delay is capped by the maxRetryDelay option.
retryDelayType	exp linear constant	exp	Time to wait before retrying, in milliseconds, as a function of the attempt number (tryNb) and the original delay (retryDelay) specified in the retryDelay option exp retryDelay * 2 ^ tryNb linear retryDelay * tryNb anything else retryDelay
respectRetryAfter	true false	true	Whether to respect the delay provided in a retry-after header when receiving a 503 response. True will respect the received delay, false will ignore it and use the retryDelayType and retryDelay options to determine the delay. In any case, the delay is capped by the maxRetryDelay option.
maxRetryDelay	Positive integer above 0	60000	Maximum time to wait before retrying, in milliseconds. Overrides Retry-After response-headers (see the respectRetryAfter) option and normal retry delay increments (see the retryDelay) option.
retryOn404	true false	false	Whether to retry when response status code is 404. This looks stupid, and most of the time it will be. It is recommended to leave the default in for this one.

Examples

fs.readFile('http://perdu.com'
  , {
    encoding: 'utf8'
    , maxTries: 5
    , retryDelayType: 'exp'
    , retryDelay: 100
    , retryOn404: true
    , respectRetryAfter: true
  }
  , function(err, str) {
    if (!err) {
      console.log('Contents:', str)
    }
  })

fs.writeFile('file.txt'
  , 'http://perdu.com'
  , {
    encoding: 'utf8'
    , maxTries: 5
    , retryDelayType: 'exp'
    , retryDelay: 100
    , retryOn404: true
    , respectRetryAfter: true
  }
  , function(err) {
    if (!err) {
      console.log("file.txt now contains the html from perdu.com")
    }
  })

fs.writeFile('file.txt'
  ,'http://perdu.com'
  , { url: false }
  , function(err) {
    if (!err) {
      console.log('file.txt now contains the string "http://perdu.com"')
    }
  })

New methods

fs.remove( path, callback )

Remove a file or directory recursively

Argument	Type	Description
path	String	path
callback	function (err)	Callback

fs.remove('someDirectory', function(err) {
  if (!err) {
    console.log('success!')
  }
})

fs.remove('someFile.txt', function(err) {
  if (!err) {
    console.log('success!')
  }
})

fs.mkdirp( path, [ options ], callback)

Create any necessary subdirectories to allow path to exist. Also see fs.writeFile's mkdirp option.

Argument	Type	Default	Description
path	String		path to create
options	Mode	0777
callback	function (err)		Callback

fs.mkdirp('path/with/inexistent/subdirectories', function (err) {
  if (!err) {
    console.log("All subdirectories have been created")
  }
})

fs.readJSON( path, [ options ], callback)

Reads a file and JSON.parses it

fs.readJSON('somefile.json', function (err, obj) {
  if (!err) {
      console.log(obj.key)
  }
})

fs.writeJSON( path, data, [ options ], callback)

JSON.stringifys data and writes the resulting string to path

fs.writeJSON('somefile.json', { key: 'value' }, function (err) {
  if (!err) {
    console.log('somefile.json contains `{"key":"value"}`')
  }
})

fs.editJSON( path, fn, [ options ], callback)

Reads the file found at path, JSON.parses it, passes the result as a single parameter to fn, JSON.stringifys whatever fn returns, saves the resulting string to that same file and calls callback.

fs.editJSON('somefile.json'
, function (obj) {
  obj.x += 1
  return obj
}
, function (err) {
  if (!err) {
    console.log("done")
  }
})

fn can also return a promise

var Promise = require('promise')
fs.editJSON('somefile.json'
, function (obj) {
  return new Promise(function (resolve, reject) {
    setTimeout(function () {
      obj.x += 1
      resolve(obj)
    }, 500)
  })
}
, function (err) {
  if (!err) {
    console.log("done")
  }
})

Native only

fs.rootDir

Root directory of the filesystem

console.log(fs.rootDir)

Supported platforms

platform	support
node	full
iOS	partial
Android	partial
Windows Phone	partial
other	none

Supported on native

• fs.readFile
• fs.writeFile
• fs.readdir
• fs.mkdir
• fs.rmdir
• fs.rename
• fs.unlink
• fs.exists
• fs.stat (Only supports creation date, modification date and accessed date, all of which are Date objects)
• fs.remove

Internals

• vigour-fs is based on graceful-fs
• fs.mkdirp and the mkdirp option available on fw.writeFile and fs.writeJSON use node-mkdirp) internally
• fs.remove uses rimraf internally

License

ISC