vinyl.md

Vinyl

A virtual file format. When a file is read by src(), a Vinyl object is generated to represent the file - including the path, contents, and other metadata.

Vinyl objects can have transformations applied using plugins. They may also be persisted to the file system using dest().

When creating your own Vinyl objects - instead of generating with src() - use the external vinyl module, as shown in Usage below.

Usage

const Vinyl = require('vinyl');

const file = new Vinyl({
  cwd: '/',
  base: '/test/',
  path: '/test/file.js',
  contents: new Buffer('var x = 123')
});

file.relative === 'file.js';

file.dirname === '/test';
file.dirname = '/specs';
file.path === '/specs/file.js';

file.basename === 'file.js';
file.basename = 'file.txt';
file.path === '/specs/file.txt';

file.stem === 'file';
file.stem = 'foo';
file.path === '/specs/foo.txt';
file.extname === '.txt';
file.extname = '.js';
file.path === '/specs/file.js';

Signature

new Vinyl([options])

Parameters

parameter	type	note
options	object	Detailed in Options below.

Returns

An instance of the Vinyl class representing a single virtual file, detailed in Vinyl instance below.

Errors

When any passed options don't conform to the instance property definitions (like if path is set to a number) throws as defined in the table.

Options

name	type	default	note
cwd	string	process.cwd()	The directory from which relative paths will be derived. Will be normalized and have trailing separators removed.
base	string		Used to calculate the relative instance property. Falls back to the value of cwd if not set. Typically set to the glob base. Will be normalized and have trailing separators removed.
path	string		The full, absolute file path. Will be normalized and have trailing separators removed.
history	array	[ ]	An array of paths to pre-populate the history of a Vinyl instance. Usually comes from deriving a new Vinyl object from a previous Vinyl object. If path and history are both passed, path is appended to history. Each item will be normalized and have trailing separators removed.
stat	object		An instance of fs.Stats, usually the result of calling fs.stat() on a file. Used to determine if a Vinyl object represents a directory or symbolic link.
contents	ReadableStream Buffer null	null	The contents of the file. If contents is a ReadableStream, it is wrapped in a cloneable-readable stream.

Any other properties on options will be directly assigned to the Vinyl instance.

const Vinyl = require('vinyl');

const file = new Vinyl({ foo: 'bar' });
file.foo === 'bar';

Vinyl instance

Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.

Instance properties

All internally managed paths - any instance property except contents and stat - are normalized and have trailing separators removed. See Normalization and concatenation for more information.

property	type	description	throws
contents	ReadableStream Buffer null	Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a [cloneable-readable][cloneable-readable-docs] stream.	If set to any value other than a ReadableStream, a Buffer, or null.
stat	object	Gets and sets an instance of fs.Stats. Used when determining if a Vinyl object represents a directory or symbolic link.
cwd	string	Gets and sets the current working directory. Used for deriving relative paths.	If set to an empty string or any non-string value.
base	string	Gets and sets the base directory. Used to calculate the relative instance property. On a Vinyl object generated by src() will be set to the glob base. If set to null or undefined, falls back to the value of the cwd instance property.	If set to an empty string or any non-string value (except null or undefined).
path	string	Gets and sets the full, absolute file path. Setting to a value different from the current path appends the new path to the history instance property.	If set to any non-string value.
history	array	Array of all path values the Vinyl object has been assigned. The first element (history[0]) is the original path and the last element (history[file.history.length - 1]) is the current path. This property and its elements should be treated as read-only and only altered indirectly by setting the path instance property.
relative	string	Gets the relative path segment between the base and the path instance properties.	If set to any value. If accessed when path is not available.
dirname	string	Gets and sets the directory of the path instance property.	If accessed when path is not available.
stem	string	Gets and sets the stem (filename without extension) of the path instance property.	If accessed when path is not available.
extname	string	Gets and sets the extension of the path instance property.	If accessed when path is not available.
basename	string	Gets and sets the filename (stem + extname) of the path instance property.	If accessed when path is not available.
symlink	string	Gets and sets the reference path of a symbolic link.	If set to any non-string value.

Instance methods

method	return type	returns
isBuffer()	boolean	If the contents instance property is a Buffer, returns true.
isStream()	boolean	If the contents instance property is a Stream, returns true.
isNull()	boolean	If the contents instance property is null, returns true.
isDirectory()	boolean	If the instance represents a directory, returns true. An instance is considered a directory when isNull() returns true, the stat instance property is an object, and stat.isDirectory() returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) fs.Stats object.
isSymbolic()	boolean	If the instance represents a symbolic link, returns true. An instance is considered symbolic when isNull() returns true, the stat instance property is an object, and stat.isSymbolicLink() returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) fs.Stats object.
clone([options])	object	A new Vinyl object with all properties cloned. By default custom properties are deep cloned. If the deep option is false, custom attributes will be shallow cloned. If the contents option is false and the contents instance property is a Buffer, the Buffer will be reused instead of cloned.
inspect()	string	Returns a formatted interpretation of the Vinyl object. Automatically called by Node's console.log.

Normalization and concatenation

All path properties are normalized by their setters. Concatenate paths with /, instead of using path.join(), and normalization will occur properly on all platforms. Never concatenate with \ - it is a valid filename character on POSIX system.

const file = new File();
file.path = '/' + 'test' + '/' + 'foo.bar';

console.log(file.path);
// posix => /test/foo.bar
// win32 => \\test\\foo.bar