to-vfile

What is to-vfile?

The 'to-vfile' npm package is a utility for working with virtual files in Node.js. It allows you to create, read, write, and manipulate file objects in memory, which can be particularly useful for processing files in a pipeline without needing to interact with the filesystem directly.

What are to-vfile's main functionalities?

Creating a virtual file

This feature allows you to create a virtual file object with specified path and contents. The file object can then be manipulated in memory.

const vfile = require('to-vfile');
const file = vfile({ path: 'example.txt', contents: 'Hello, world!' });
console.log(file);

Reading a file from the filesystem

This feature allows you to read a file from the filesystem into a virtual file object. The contents of the file are loaded into memory, and you can manipulate the file object as needed.

const vfile = require('to-vfile');
vfile.read('example.txt', 'utf8', (err, file) => {
  if (err) throw err;
  console.log(file);
});

Writing a virtual file to the filesystem

This feature allows you to write a virtual file object to the filesystem. The contents of the virtual file are saved to the specified path.

const vfile = require('to-vfile');
const file = vfile({ path: 'example.txt', contents: 'Hello, world!' });
vfile.write(file, err => {
  if (err) throw err;
  console.log('File written!');
});

Other packages similar to to-vfile

vinyl

Vinyl is a similar package that provides a virtual file format. It is commonly used in the Gulp ecosystem for handling file transformations in memory. Compared to 'to-vfile', Vinyl is more focused on stream-based workflows and integrates tightly with Gulp.

memfs

Memfs is a package that provides an in-memory filesystem. It allows you to perform filesystem operations in memory, which can be useful for testing and mocking. While 'to-vfile' focuses on individual file objects, Memfs provides a broader filesystem abstraction.

README

to-vfile

Create a vfile from a file-path. Optionally populates them from the file-system as well. Can write virtual files to file-system too.

Installation

npm:

npm install to-vfile

Note: the file-system stuff is not available in the browser.

Usage

var vfile = require('to-vfile');

console.log(vfile('readme.md'));
console.log(vfile.readSync('.git/HEAD'));
console.log(vfile.readSync('.git/HEAD', 'utf8'));

Yields:

VFile {
  data: {},
  messages: [],
  history: [ 'readme.md' ],
  cwd: '/Users/tilde/projects/oss/to-vfile' }
VFile {
  data: {},
  messages: [],
  history: [ '.git/HEAD' ],
  cwd: '/Users/tilde/projects/oss/to-vfile',
  contents: <Buffer 72 65 66 3a 20 72 65 66 73 2f 68 65 61 64 73 2f 6d 61 73 74 65 72 0a> }
VFile {
  data: {},
  messages: [],
  history: [ '.git/HEAD' ],
  cwd: '/Users/tilde/projects/oss/to-vfile',
  contents: 'ref: refs/heads/master\n' }

API

toVFile(options)

Create a virtual file. Works like the vfile constructor, except when options is string or Buffer, in which case it’s treated as {path: options} instead of {contents: options}.

toVFile.read(options[, encoding], callback)

Creates a virtual file from options (toVFile(options)), reads the file from the file-system and populates file.contents with the result. If encoding is specified, it’s passed to fs.readFile. Invokes callback with either an error or the populated virtual file.

toVFile.readSync(options[, encoding])

Like toVFile.read but synchronous. Either throws an error or returns a populated virtual file.

toVFile.write(options[, fsOptions], callback)

Creates a virtual file from options (toVFile(options)), writes the file to the file-system. fsOptions are passed to fs.writeFile. Invokes callback with an error, if any.

toVFile.writeSync(options[, fsOptions])

Like toVFile.write but synchronous. Throws an error, if any.

License

MIT © Titus Wormer