vigour-fs v3.0.6

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.

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

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.

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

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