vigour-fs

3.0.6 • Public • Published

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

Package Sidebar

Install

npm i vigour-fs

Weekly Downloads

11

Version

3.0.6

License

ISC

Last publish

Collaborators

  • vigour-io