node package manager
Love JavaScript? Your insights can make it even better. Take the 2017 JavaScript Ecosystem Survey »

@ygor/file

@ygor/file

NPM version Downloads Build Status Coverage Status

A no-frills file object. Built on promises to work wonderfully with async and await in Node.js 8 and above. Part of the Ygor toolkit.

Install

$ npm install --save @ygor/file

Usage

const file = require('@ygor/file');
 
const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
// Read the contents of the file at the given path.
await foo.read();
 
// Modify the contents in memory.
file.contents = file.contents.toUpperCase();
 
// Write the new contents to the file system.
await foo.write();

API

file([options]): File

  • options {Object}
  • options.cwd {String} - Current working directory. (default: process.cwd())
  • options.path {String} - Path to file relative to .cwd. (default: undefined)
  • options.contents {String|Buffer} - File contents. (default: undefined)
  • options.[custom] {any} - Any additional properties will be copied to the returned File object.

Creates a File object.

File Methods

.delete(): Promise<File>

Unlinks the file on the file system. The contents remain in memory if they were set or read.

.read([options]): Promise<File>

  • options {Object} - Same as fs.readFile options with the following change.
  • options.encoding {String|null} - File encoding defaults to utf8. You must specify null for binary files. (default: 'utf8')

Reads the file contents from the file system into the .contents value.

.stat(): Promise<Stats>

Returns an instance of the Node.js fs.Stats class.

.write([options]): Promise<File>

  • options {Object} - Same as fs.writeFile options with the following addition.
  • options.cwd {String} Alternate base path for the write; can be relative to the existing .cwd or an absolute path.

Writes the .contents value as the file contents to the file system.

.toJSON(): Object

Returns .cwd, .path, and .contents as a plain object.

.toString(): String

Returns a console.log-friendly representation of the file.

File Properties

.contents {String|Buffer|undefined}

The contents of the file.

.absolute {String}

The absolute path to the file. Read only.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt

.cwd {String}

The current working directory of the file. (default process.cwd())

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.cwd);
// -> /home/jdoe
 
foo.cwd = '/Users/jappleseed';
 
console.log(foo.absolute);
// -> /Users/jappleseed/foo/bar.txt

.path {String}

The path of the file relative to .cwd.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.path);
// -> foo/bar.txt
 
foo.path = 'baz/qux.txt';
 
console.log(foo.absolute);
// -> /home/jdoe/baz/qux.txt

.dirname {String}

The directory portion of .path.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.dirname);
// -> foo
 
foo.dirname = 'baz/qux';
 
console.log(foo.absolute);
// -> /home/jdoe/baz/qux/bar.txt

.basename {String}

The file portion of .path.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.basename);
// -> bar.txt
 
foo.basename = 'qux.txt';
 
console.log(foo.absolute);
// -> /home/jdoe/foo/qux.txt

.stem {String}

The file portion of .path without the extension.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.basename);
// -> bar
 
foo.basename = 'qux';
 
console.log(foo.absolute);
// -> /home/jdoe/foo/qux.txt

.extname {String}

The file extension portion of .path.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.txt
 
console.log(foo.basename);
// -> .txt
 
foo.basename = '.html';
 
console.log(foo.absolute);
// -> /home/jdoe/foo/bar.html

.history {Array<String>}

The history of .path changes. Generally best treated as read-only.

const foo = file({ path: 'foo/bar.txt' });
 
console.log(foo.history);
// -> ['foo/bar.txt']
 
foo.stem = 'qux';
 
console.log(foo.history);
// -> ['foo/bar.txt', 'foo/qux.txt']

© 2017 Shannon Moeller me@shannonmoeller.com (shannonmoeller.com)

Licensed under MIT