Object-oriented API for interacting with files
npm install file-classObject-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");
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
`
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)
});
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()
});
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()
});
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()
});
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()
});
Check for this file's existence (via fs.exists(...)).
Arguments
* callback - Arguments provided:
* exists - true/false
`javascript`
file.exists(function (exists) {
// exists => true/false
});
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
});
----
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 FileFile
* options - same as , with some additions:null
* replacer - A replacer function: see JSON.stringify (default: )null
* spaces - Number of spaces to use in output: see JSON.stringify (default: )
`javascript
var json = new File.JSONFile("package.json");
json.read(function (err, json) {
// json => parsed JSON object for file
});
`
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
});
----
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 FileString
* options
* ignore - , RegExp, Function
`javascript
var list = new File.ListFile("banned.txt");
list.read(function (err, users) {
// users => array of users (one per line of file)
});
`
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
});
`
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
});
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/falsethis.read(...)
* list - The complete list (via )
`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
});
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()
});
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()
});