file-class

    0.1.3 • Public • Published

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

    Install

    npm i file-class

    DownloadsWeekly Downloads

    77

    Version

    0.1.3

    License

    MIT

    Last publish

    Collaborators

    • dominicbarnes