The vfile npm package is a virtual file format for text processing systems, which allows for the manipulation and handling of file-related information in a structured and consistent way. It is commonly used in projects involving the processing of markdown, text, and similar content, providing a standardized interface for plugins and utilities.
Creating and modifying virtual files
This feature allows users to create a new virtual file and modify its contents. The example demonstrates creating a vfile with initial content and then appending additional text to it.
const vfile = require('vfile');
const file = vfile({path: './example.txt', contents: 'Hello, world!'});
file.contents += ' Modified content.';
console.log(file.contents);Accessing file metadata
This feature enables users to access metadata of the file such as the path and basename. The example shows how to create a vfile and retrieve its path and basename properties.
const vfile = require('vfile');
const file = vfile({path: './example.txt', contents: 'Hello, world!'});
console.log(file.path); // Outputs: './example.txt'
console.log(file.basename); // Outputs: 'example.txt'Handling errors and messages
This feature is useful for adding error or warning messages to a file, which can be particularly helpful in linting tools or compilers. The example demonstrates adding an error message to a vfile and logging all associated messages.
const vfile = require('vfile');
const file = vfile();
file.message('Unknown error', {line: 1, column: 1});
console.log(file.messages);Vinyl is a virtual file format that is often used in the gulp build system. It is similar to vfile in that it represents file objects in a virtual form, but it is more focused on being used with streams, particularly in the context of gulp's pipelines.
mem-fs provides an in-memory file system which stores file representations similar to vfile. While vfile is designed for text processing with a focus on linting and transformation, mem-fs is geared more towards temporary storage and manipulation of files in memory during tasks like scaffolding or testing.
VFile is a virtual file format used by retext (natural language) and mdast (markdown). Two processors which parse, transform, and compile text. Both need a virtual representation of files and a place to store metadata and messages. And, they work in the browser. VFile provides these requirements.
Also, VFile exposes a warning mechanism compatible with ESLints formatters, making it easy to expose stylish warnings, or export tap compliant messages.
VFile is different from (the excellent :+1:) vinyl in that it does not include file-system or node-only functionality. No buffers, streams, or stats. In addition, the focus on metadata and messages are useful when processing a file through a middleware pipeline.
npm:
npm install vfile
VFile is also available for bower, component, and duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.
var VFile = require('vfile');
var file = new VFile({
'directory': '~',
'filename': 'example',
'extension': 'txt',
'contents': 'Foo *bar* baz'
});
file.toString(); // 'Foo *bar* baz'
file.filePath(); // '~/example.txt'
file.move({'extension': 'md'});
file.filePath(); // '~/example.md'
file.warn('Something went wrong', {'line': 1, 'column': 3});
// { [~/example.md:1:3: Something went wrong]
// name: '~/example.md:1:3',
// file: '~/example.md',
// reason: 'Something went wrong',
// line: 1,
// column: 3,
// fatal: false }
VFiles are used by both retext and mdast.
In addition, here’s a list of useful tools:
wooorm/to-vfile
— Create a virtual file from a file-path;
wooorm/vfile-sort
— Sort virtual file messages by line/column;
wooorm/vfile-reporter
— Stylish reporter for virtual files.
VFile objects make it easy to move files, to trigger warnings and errors, and to store supplementary metadata relating to files, all without accessing the file-system.
Example
var file = new VFile({
'directory': '~',
'filename': 'example',
'extension': 'txt',
'contents': 'Foo *bar* baz'
});
file === VFile(file); // true
file === new VFile(file); // true
VFile('foo') instanceof VFile; // true
Signatures
file = VFile(contents|options|vFile?).Parameters
contents (string) — Contents of the file;
vFile (VFile) — Existing representation, returned without modification;
options (Object):
directory (string?, default: '')
— Parent directory;
filename (string?, default: '')
— Name, without extension;
extension (string?, default: '')
— Extension(s), without initial dot;
contents (string?, default: '')
— Raw value.
Returns
vFile — Instance.
Notes
VFile exposes an interface compatible with ESLint’s formatters. For example,
to expose warnings using ESLint’s compact formatter, execute the following:
var compact = require('eslint/lib/formatters/compact');
var VFile = require('vfile');
var vFile = new VFile({
'directory': '~',
'filename': 'hello',
'extension': 'txt'
});
vFile.warn('Whoops, something happened!');
console.log(compact([vFile]));
Which would yield the following:
~/hello.txt: line 0, col 0, Warning - Whoops, something happened!
1 problem
string — Content of file.
string — Path to parent directory.
string — Filename. A file-path can still be generated when no filename exists.
string — Extension. A file-path can still be generated when no extension
exists.
boolean? — Whether an error created by VFile#fail()
is returned (when truthy) or thrown (when falsey).
Ensure all messages associated with a file are handled properly when setting
this to true.
Array.<VFileMessage> — List of associated messages.
Notes
VFile#message(), and in turn VFile#warn() and VFile#fail(), return
Error objects that adhere to the VFileMessage schema.
Its results can populate messages.
Get the value of the file.
Example
var vFile = new VFile('Foo');
String(vFile); // 'Foo'
Signatures
string = vFile.toString().Returns
string — Contents.
Get the filename, with extension and directory, if applicable.
Example
var file = new VFile({
'directory': '~',
'filename': 'example',
'extension': 'txt'
});
String(file.filePath); // ~/example.txt
file.filePath() // ~/example.txt
Signatures
string = vFile.filePath().Returns
string — If the vFile has a filename, it will be prefixed with the
directory (slashed), if applicable, and suffixed with the (dotted) extension
(if applicable). Otherwise, an empty string is returned.
Move a file by passing a new directory, filename, and extension. When these are not given, the default values are kept.
Example
var file = new VFile({
'directory': '~',
'filename': 'example',
'extension': 'txt',
'contents': 'Foo *bar* baz'
});
file.move({'directory': '/var/www'});
file.filePath(); // '/var/www/example.txt'
file.move({'extension': 'md'});
file.filePath(); // '/var/www/example.md'
Signatures
vFile = vFile.move(options?).Parameters
options (Object):
directory (string, default: '')
— Parent directory;
filename (string?, default: '')
— Name, without extension;
extension (string, default: '')
— Extension(s), without initial dot.
Returns
vFile — Context object (chainable).
Access metadata.
Example
var file = new VFile('Foo');
file.namespace('foo').bar = 'baz';
console.log(file.namespace('foo').bar) // 'baz';
Parameters
key (string) — Namespace key.Returns
Object — Private namespace for metadata.
Create a message with reason at position. When an error is passed in as
reason, copies the stack. This does not add a message to messages.
Example
var file = new VFile();
file.message('Something went wrong');
// { [1:1: Something went wrong]
// name: '1:1',
// file: '',
// reason: 'Something went wrong',
// line: null,
// column: null }
Signatures
VFileMessage = vFile.message(err|reason, node|location|position?).Parameters
err (Error) — Original error, whose stack and message are used;
reason (string) — Reason for message;
node (Node) — Syntax tree object;
location (Object) — Syntax tree location (found at node.position);
position (Object) — Syntax tree position (found at
node.position.start or node.position.end).
Returns
VFileMessage — File-related message with location
information.
Warn. Creates a non-fatal message (see VFile#message()),
and adds it to the file's messages list.
Example
var file = new VFile();
file.warn('Something went wrong');
// { [1:1: Something went wrong]
// name: '1:1',
// file: '',
// reason: 'Something went wrong',
// line: null,
// column: null,
// fatal: false }
See
Fail. Creates a fatal message (see VFile#message()), sets fatal: true,
adds it to the file's messages list.
If quiet is not true, throws the error.
Example
var file = new VFile();
file.fail('Something went wrong');
// 1:1: Something went wrong
// at VFile.exception (vfile/index.js:296:11)
// at VFile.fail (vfile/index.js:360:20)
// at repl:1:6
file.quiet = true;
file.fail('Something went wrong');
// { [1:1: Something went wrong]
// name: '1:1',
// file: '',
// reason: 'Something went wrong',
// line: null,
// column: null,
// fatal: true }
See
Check if a fatal message occurred making the file no longer processable.
Example
var file = new VFile();
file.quiet = true;
file.hasFailed(); // false
file.fail('Something went wrong');
file.hasFailed(); // true
Signatures
boolean = vFile.hasFailed().Returns
boolean — true if at least one of file’s messages has a fatal
property set to true.
Error — File-related message with location information.
Properties
name (string)
— (Starting) location of the message, preceded by its file-path when
available, and joined by ':'. Used by the native
Error#toString();
file (string) — File-path;
reason (string) — Reason for message;
line (number?) — Line of error, when available;
column (number?) — Column of error, when available;
stack (string?) — Stack of message, when available;
fatal (boolean?) — Whether the associated file is still processable.
FAQs
Virtual file format for text processing
The npm package vfile receives a total of 4,999,513 weekly downloads. As such, vfile popularity was classified as popular.
We found that vfile demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.