@ygor/file

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.stem);
// -> bar

foo.stem = '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.extname);
// -> .txt

foo.extname = '.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']

MIT © Shannon Moeller