file-class v0.1.3

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

File(location, options) constructor

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)

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

File#read(callback)

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

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

File#mkdir(callback)

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

Arguments

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

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

File#write(contents, callback)

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)

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

File#empty(callback)

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

Arguments

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

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

File#unlink(callback) Alias: del

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

Arguments

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

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

File#exists(callback)

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

Arguments

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

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

File#stat(callback)

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

Arguments

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

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

File.JSONFile(location, options) constructor

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)

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

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

File.JSONFile#merge(data, callback)

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

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

File.ListFile(location, options) constructor

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

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

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

File.ListFile#ignore

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.

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
});

File.ListFile#indexOf(item, callback)

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(...))

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
});

File.ListFile#contains(item, callback)

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(...))

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
});

File.ListFile#add(item, callback)

Add a new item to the collection.

Arguments

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

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

File.ListFile#remove(item, callback)

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)

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