node-file-class

Object-oriented API for interacting with files in node.js

npm install file-class

Include in your project, the export is a single constructor function

var File = require("file-class");

API Documentation

$3

The constructor will create an object representing a file on disk.

Arguments

* location - The location/path to file on disk (absolute is likely preferred)
* options - A hash of additional properties for the object (just extended to this)
* encoding - The encoding for the file (default: "utf8")
* parse - A function to parse a file body (default: null)
* stringify - A function to encode data into a file body (default: null)

``javascript
var file = new File("foo.txt");

// or

var file = new File("foo.conf", {
encoding: "utf8",
parse: function (input) { / parse and return output / },
stringify: function (input) { / transform and return output / }
});

// or even

var file = new File("my-file");

file.encoding = "binary"; // can set properties after initialization
`

$3

Read the entire contents of the file (via fs.readFile()) and return in a callback.

Arguments

* callback - Arguments provided:
* err - Error object (if relevent)
* contents - The entire contents of the file

`javascript
file.read(function (err, contents) {
// err => null or Error()
// contents => string of contents (or buffer in encoding is not utf8)
});
`

$3

Create the entire directory tree for this file (via mkdirp)

Arguments

* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
file.mkdir(function (err) {
// err => null or Error()
});
`

$3

Write contents to the file (via fs.writeFile())

Arguments

* contents - The data to be written to the file
* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
file.write("FOO", function (err) {
// err => null or Error()
});
`

$3

Clear the contents of the file (ie. file.write("", ...))

Arguments

* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
file.empty(function (err) {
// err => null or Error()
});
`

$3

Delete the file from the filesystem (via fs.unlink(...)).

Arguments

* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
file.unlink(function (err) {
// err => null or Error()
});
`

$3

Check for this file's existence (via fs.exists(...)).

Arguments

* callback - Arguments provided:
* exists - true/false

`javascript
file.exists(function (exists) {
// exists => true/false
});
`

$3

Get a fs.Stats object for the file (via fs.stat(...)).

Arguments

* callback - Arguments provided:
* err - Error object (if relevent)
* stats - fs.Stats object

`javascript
file.stat(function (err, stats) {
// err => null or Error()
// stats => fs.Stats object
});
`

----

$3

The constructor will create an object representing a JSON file on disk. This object exposes helper methods for dealing with JSON.

Arguments

* location - same as File
* options - same as File, with some additions:
* replacer - A replacer function: see JSON.stringify (default: null)
* spaces - Number of spaces to use in output: see JSON.stringify (default: null)

`javascript
var json = new File.JSONFile("package.json");

json.read(function (err, json) {
// json => parsed JSON object for file
});
`

$3

Reads the file, uses extend to merge the data in before writing.

Arguments

* data - The object of data to merge
* callback - Arguments provided:
* err - Error object (if relevent)
* contents - The contents as they were written

`javascript
json.merge({ foo: "bar" }, function (err, contents) {
// err => null or Error()
// contents => final state of file contents
});
`

----

$3

The constructor will create an object representing a file on disk whose contents
are comprised of one item per-line. This object exposes helper methods for
dealing with that collection.

Arguments

* location - same as File
* options
* ignore - String, RegExp, Function

`javascript
var list = new File.ListFile("banned.txt");

list.read(function (err, users) {
// users => array of users (one per line of file)
});
`

$3

This property can be added via the options object in the constructor, or can
be set manually as an object property.

If a String, any line beginning with that same string will be ignored.

If a RegExp, any line that matches the regular expression will be ignored.

If a Function, any line that returns true when executing the function will be ignored.

NOTE Empty lines (this includes lines that consist only of whitespace) are always ignored.

`javascript

var list = new File.ListFile("banned.txt", { ignore: "#" });

// or perhaps
list.ignore = /^#/;

// or even
list.ignore = function (line) {
return line[0] === "#";
};

list.read(function (err, users) {
// users => will exclude entries that begin with a '#' character
// any of the above methods yield the same result in this case
});
`

$3

Determine the index of the item specified in the collection.

Arguments

* item - The item to check
* callback - Arguments provided:
* err - Error object (if relevent)
* index - The 0-indexed line number for that item (-1 if not found)
* list - The complete list (via this.read(...))

`javascript
list.indexOf("hello world", function (err, index, list) {
// err => null or Error()
// index => -1 or index in array
// list => the list that was read from disk
});
`

$3

Determine whether or not an item is in the collection at all.

Arguments

* item - The item to check
* callback - Arguments provided:
* err - Error object (if relevent)
* contains - true/false
* list - The complete list (via this.read(...))

`javascript
list.contains("hello world", function (err, contains, list) {
// err => null or Error()
// contains => -1 or index in array
// list => the list that was read from disk
});
`

$3

Add a new item to the collection.

Arguments

* item - The item to add
* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
list.add("hello world", function (err) {
// err => null or Error()
});
`

$3

Remove an item from the collection. (either by value, or index)

Notice: this will only remove the first occurence, even if the value occurs multiple times in the file.

Arguments

* item - The item to remove (Number: will remove that line via index. String: will call this.indexOf() to determine which line to remove)
* callback - Arguments provided:
* err - Error object (if relevent)

`javascript
list.add("hello world", function (err) {
// err => null or Error()
});
``