vfile is a virtual file format part of the unified collective.

Intro

vfile is a virtual file format used by unified, a text processing umbrella (it powers retext for natural language, remark for markdown, and rehype for HTML). Each processors that parse, transform, and compile text, and need a virtual representation of files and a place to store messages about them. Plus, they work in the browser. vfile provides these requirements at a small size.

• Visit unified.js.org and try its guides for an overview
• Read unified’s readme for a technical intro
• Follow us on Medium and Twitter to see what we’re up to
• Check out Contribute below to find out how to help out

vfile is different from the excellent vinyl in that it has a smaller API, a smaller size, and focuses on messages.

vfile can be used anywhere where files need a lightweight representation. For example, it’s used in:

• documentation — The documentation system for modern JavaScript
• awoo — Declarative small site generator
• geojsonhint — Complete, fast, standards-based validation for geojson

Sponsors

🥇 ZEIT

🥇 Gatsby

🥉 Compositor

Holloway

You?

Read more about the unified collective on Medium »

Install

npm:

npm install vfile

Table of Contents

• Usage
• API
  • VFile([options])
  • vfile.contents
  • vfile.cwd
  • vfile.path
  • vfile.basename
  • vfile.stem
  • vfile.extname
  • vfile.dirname
  • vfile.history
  • vfile.messages
  • vfile.data
  • VFile#toString([encoding])
  • VFile#message(reason[, position][, origin])
  • VFile#info(reason[, position][, origin])
  • VFile#fail(reason[, position][, origin])
• Utilities
• Reporters
• Contribute
• Acknowledgments
• License

Usage

var vfile = require('vfile')

var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'})

file.path // => '~/example.txt'
file.dirname // => '~'

file.extname = '.md'

file.basename // => 'example.md'

file.basename = 'index.text'

file.history // => ['~/example.txt', '~/example.md', '~/index.text']

file.message('`braavo` is misspelt; did you mean `bravo`?', {
  line: 1,
  column: 8
})

console.log(file.messages)

Yields:

[ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?]
    message: '`braavo` is misspelt; did you mean `bravo`?',
    name: '~/index.text:1:8',
    file: '~/index.text',
    reason: '`braavo` is misspelt; did you mean `bravo`?',
    line: 1,
    column: 8,
    location: { start: [Object], end: [Object] },
    ruleId: null,
    source: null,
    fatal: false } ]

API

VFile([options])

Create a new virtual file. If options is string or Buffer, treats it as {contents: options}. If options is a VFile, returns it. All other options are set on the newly created vfile.

Path related properties are set in the following order (least specific to most specific): history, path, basename, stem, extname, dirname.

It’s not possible to set either dirname or extname without setting either history, path, basename, or stem as well.

Example

vfile()
vfile('console.log("alpha");')
vfile(Buffer.from('exit 1'))
vfile({path: path.join(__dirname, 'readme.md')})
vfile({stem: 'readme', extname: '.md', dirname: __dirname})
vfile({other: 'properties', are: 'copied', ov: {e: 'r'}})

vfile.contents

Buffer, string, null — Raw value.

vfile.cwd

string — Base of path. Defaults to process.cwd().

vfile.path

string? — Path of vfile. Cannot be nullified.

vfile.basename

string? — Current name (including extension) of vfile. Cannot contain path separators. Cannot be nullified either (use file.path = file.dirname instead).

vfile.stem

string? — Name (without extension) of vfile. Cannot be nullified, and cannot contain path separators.

vfile.extname

string? — Extension (with dot) of vfile. Cannot be set if there’s no path yet and cannot contain path separators.

vfile.dirname

string? — Path to parent directory of vfile. Cannot be set if there’s no path yet.

vfile.history

Array.<string> — List of file-paths the file moved between.

vfile.messages

Array.<VMessage> — List of messages associated with the file.

vfile.data

Object — Place to store custom information. It’s OK to store custom data directly on the vfile, moving it to data gives a little more privacy.

VFile#toString([encoding])

Convert contents of vfile to string. If contents is a buffer, encoding is used to stringify buffers (default: 'utf8').

VFile#message(reason[, position][, origin])

Associates a message with the file, where fatal is set to false. Constructs a new VMessage and adds it to vfile.messages.

Returns

VMessage.

VFile#info(reason[, position][, origin])

Associates an informational message with the file, where fatal is set to null. Calls #message() internally.

Returns

VMessage.

VFile#fail(reason[, position][, origin])

Associates a fatal message with the file, then immediately throws it. Note: fatal errors mean a file is no longer processable. Calls #message() internally.

Throws

VMessage.

Utilities

The following list of projects includes tools for working with virtual files. See unist for projects working with nodes.

• convert-vinyl-to-vfile — Convert from Vinyl
• is-vfile-message — Check if a value is a VMessage object
• to-vfile — Create a virtual file from a file-path (and optionally read it)
• vfile-find-down — Find files by searching the file system downwards
• vfile-find-up — Find files by searching the file system upwards
• vfile-glob — Find files by glob patterns
• vfile-is — Check if a file passes a test
• vfile-location — Convert between line/column- and range-based locations
• vfile-message — Create a VMessage object (used in vfile itself)
• vfile-messages-to-vscode-diagnostics — Convert to VS Code diagnostics
• vfile-statistics — Count messages per category
• vfile-sort — Sort messages by line/column
• vfile-to-eslint — Convert vfiles to ESLint formatter compatible output

Reporters

The following list of projects show linting results for given virtual files. Reporters must accept Array.<VFile> as their first argument, and return string. Reporters may accept other values too, in which case it’s suggested to stick to vfile-reporters interface.

• vfile-reporter — Stylish reporter
• vfile-reporter-json — JSON reporter
• vfile-reporter-folder-json — JSON reporter with a folder structure
• vfile-reporter-pretty — Pretty reporter

Contribute

See contributing.md in vfile/.github for ways to get started. See support.md for ways to get help. Ideas for new utilities and tools can be posted in vfile/ideas.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

Acknowledgments

The initial release of this project was authored by @wooorm.

Thanks to @contra, @phated, and others for their work on Vinyl, which was a huge inspiration.

Thanks to @brendo, @shinnn, @KyleAMathews, @sindresorhus, and @denysdovhan for contributing commits since!

License

MIT © Titus Wormer