Repository files navigation

Virtual file format.

Vinyl is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind:path andcontents. These are the main attributes on a Vinyl object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. Vinyl can be used to describe files from all of these sources.

While Vinyl provides a clean way to describe a file, we also need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes asrc(globs) and adest(folder) method. Each return a stream. Thesrc stream produces Vinyl objects, and thedest stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as thesymlink methodvinyl-fs provides.

varVinyl=require('vinyl');varjsFile=newVinyl({cwd:'/',base:'/test/',path:'/test/file.js',contents:Buffer.from('var x = 123'),});

The constructor is used to create a new instance ofVinyl. Each instance represents a separate file, directory or symlink.

All internally managed paths (cwd,base,path,history) are normalized and have trailing separators removed. SeeNormalization and concatenation for more information.

Options may be passed upon instantiation to create a file with specific properties.

Options are not mutated by the constructor.

The current working directory of the file.

Type:String

Default:process.cwd()

Used for calculating therelative property. This is typically where a glob starts.

Type:String

Default:options.cwd

The full path to the file.

Type:String

Default:undefined

Stores the path history. Ifoptions.path andoptions.history are both passed,options.path is appended tooptions.history. Alloptions.history paths are normalized by thefile.path setter.

Type:Array

Default:[] (or[options.path] ifoptions.path is passed)

The result of anfs.stat call. This is how you mark the file as a directory or symbolic link. SeeisDirectory(),isSymbolic() andfs.Stats for more information.

Type:fs.Stats

Default:undefined

The contents of the file. Ifoptions.contents is aReadableStream, it is wrapped in acloneable-readable stream.

Type:ReadableStream,Buffer, ornull

Default:null

Any other option properties will be directly assigned to the new Vinyl object.

varVinyl=require('vinyl');varfile=newVinyl({foo:'bar'});file.foo==='bar';// true

Each Vinyl object will have instance methods. Every method will be available but may return differently based on what properties were set upon instantiation or modified since.

Returnstrue if the file contents are aBuffer, otherwisefalse.

Returnstrue if the file contents are aStream, otherwisefalse.

Returnstrue if the file contents arenull, otherwisefalse.

Returnstrue if the file represents a directory, otherwisefalse.

A file is considered a directory when:

• file.isNull() istrue
• file.stat is an object
• file.stat.isDirectory() returnstrue

When constructing a Vinyl object, pass in a validfs.Stats object viaoptions.stat. If you are mocking thefs.Stats object, you may need to stub theisDirectory() method.

Returnstrue if the file represents a symbolic link, otherwisefalse.

A file is considered symbolic when:

• file.isNull() istrue
• file.stat is an object
• file.stat.isSymbolicLink() returnstrue

When constructing a Vinyl object, pass in a validfs.Stats object viaoptions.stat. If you are mocking thefs.Stats object, you may need to stub theisSymbolicLink() method.

Returns a new Vinyl object with all attributes cloned.

By default custom attributes are cloned deeply.

Ifoptions oroptions.deep isfalse, custom attributes will not be cloned deeply.

Iffile.contents is aBuffer andoptions.contents isfalse, theBuffer reference will be reused instead of copied.

Returns a formatted-string interpretation of the Vinyl object. Automatically called by node'sconsole.log.

Each Vinyl object will have instance properties. Some may be unavailable based on what properties were set upon instantiation or modified since.

Gets and sets the contents of the file. If set to aReadableStream, it is wrapped in acloneable-readable stream.

Throws when set to any value other than aReadableStream, aBuffer ornull.

Type:ReadableStream,Buffer, ornull

Gets and sets current working directory. Will always be normalized and have trailing separators removed.

Throws when set to any value other than non-empty strings.

Type:String

Gets and sets base directory. Used for relative pathing (typically where a glob starts).Whennull orundefined, it simply proxies thefile.cwd property. Will always be normalized and have trailing separators removed.

Throws when set to any value other than non-empty strings ornull/undefined.

Type:String

Gets and sets the absolute pathname string orundefined. Setting to a different value appends the new path tofile.history. If set to the same value as the current path, it is ignored. All new values are normalized and have trailing separators removed.

Throws when set to any value other than a string.

Type:String

Array offile.path values the Vinyl object has had, fromfile.history[0] (original) throughfile.history[file.history.length - 1] (current).file.history and its elements should normally be treated as read-only and only altered indirectly by settingfile.path.

Type:Array

Gets the result ofpath.relative(file.base, file.path).

Throws when set or whenfile.path is not set.

Type:String

Example:

varfile=newFile({cwd:'/',base:'/test/',path:'/test/file.js',});console.log(file.relative);// file.js

Gets and sets the dirname offile.path. Will always be normalized and have trailing separators removed.

Throws whenfile.path is not set.

Type:String

Example:

varfile=newFile({cwd:'/',base:'/test/',path:'/test/file.js',});console.log(file.dirname);// /testfile.dirname='/specs';console.log(file.dirname);// /specsconsole.log(file.path);// /specs/file.js

Gets and sets the basename offile.path.

Throws whenfile.path is not set.

Type:String

Example:

varfile=newFile({cwd:'/',base:'/test/',path:'/test/file.js',});console.log(file.basename);// file.jsfile.basename='file.txt';console.log(file.basename);// file.txtconsole.log(file.path);// /test/file.txt

Gets and sets stem (filename without suffix) offile.path.

Throws whenfile.path is not set.

Type:String

Example:

varfile=newFile({cwd:'/',base:'/test/',path:'/test/file.js',});console.log(file.stem);// filefile.stem='foo';console.log(file.stem);// fooconsole.log(file.path);// /test/foo.js

Gets and sets extname offile.path.

Throws whenfile.path is not set.

Type:String

Example:

varfile=newFile({cwd:'/',base:'/test/',path:'/test/file.js',});console.log(file.extname);// .jsfile.extname='.txt';console.log(file.extname);// .txtconsole.log(file.path);// /test/file.txt

Gets and sets the path where the file points to if it's a symbolic link. Will always be normalized and have trailing separators removed.

Throws when set to any value other than a string.

Type:String

Static method used for checking if an object is a Vinyl file. Use this method instead ofinstanceof.

Takes an object and returnstrue if it is a Vinyl file, otherwise returnsfalse.

Note: This method uses an internal flag that some older versions of Vinyl didn't expose.

Example:

varVinyl=require('vinyl');varfile=newVinyl();varnotAFile={};Vinyl.isVinyl(file);// trueVinyl.isVinyl(notAFile);// false

Static method used by Vinyl when setting values inside the constructor or when copying properties infile.clone().

Takes a stringproperty and returnstrue if the property is not used internally, otherwise returnsfalse.

This method is useful for inheritting from the Vinyl constructor. Read more inExtending Vinyl.

Example:

varVinyl=require('vinyl');Vinyl.isCustomProp('sourceMap');// trueVinyl.isCustomProp('path');// false -> internal getter/setter

Since all properties are normalized in their setters, you can just concatenate with/, and normalization takes care of it properly on all platforms.

Example:

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

But never concatenate with\, since that is a valid filename character on posix system.

When extending Vinyl into your own class with extra features, you need to think about a few things.

When you have your own properties that are managed internally, you need to extend the staticisCustomProp method to returnfalse when one of these properties is queried.

varVinyl=require('vinyl');varbuiltInProps=['foo','_foo'];classSuperFileextendsVinyl{constructor(options){super(options);this._foo='example internal read-only value';}getfoo(){returnthis._foo;}staticisCustomProp(name){returnsuper.isCustomProp(name)&&builtInProps.indexOf(name)===-1;}}// `foo` won't be assigned to the object belownewSuperFile({foo:'something'});

This makes propertiesfoo and_foo skipped when passed in options toconstructor(options) so they don't get assigned to the new object and override your custom implementation. They also won't be copied when cloning.Note: The_foo andfoo properties will still exist on the created/cloned object because you are assigning_foo in the constructor andfoo is defined on the prototype.

Same goes forclone(). If you have your own internal stuff that needs special handling during cloning, you should extend it to do so.

MIT