README

vile">

vile is my fork of the vfile project, which is part of the unified collective.

Why the fork!?

Well, I got kinda peeved with the typings not being accurate anymore, so I said "fork it" it, I'll fix it myself and publish it on npm or something. Everything is the same except for one of the following changes, which will occur in types/index.d.ts:

Note: The interface is simplified for brevity in these examples. The only change so far is the result field.

Option One

This is the simplist solution, but with the least benefit as well.

interface VFile {
    
    <F extends VFile>(input?: VFileContents | F | VFileOptions): F
    /**
     * List of file-paths the file moved between.
     */
    history: string[]
    /**
     * 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.
     */
    data: unknown
    /**
     * Result from either `.process` or `.processSync`, can be anything
     */
    result: any
}

Option Two

Option two is slightly more robust, but still poses limitations on plugin authors.

interface VFile<T> {
    <F extends VFile>(input?: VFileContents | F | VFileOptions): F
    /**
     * List of file-paths the file moved between.
     */
    history: string[]
    /**
     * 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.
     */
    data: unknown
    /**
     * Result from either `.process` or `.processSync`, can be anything
     */
    result: T
}

Option Three

This is the most robust solution, but also the most verbose.

interface VFile {
    <F extends VFile>(input?: VFileContents | F | VFileOptions): F
    /**
     * List of file-paths the file moved between.
     */
    history: string[]
    /**
     * 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.
     */
    data: unknown
}

interface CustomVFile<T> extends VFile{
  /**
   * Result from either `.process` or `.processSync`, can be anything
   */
  result: T
}

These options are not final, and are subject to change.

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 unifiedjs.com and see its learn section 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

Install

npm:

npm install vfile

Use
API
Utilities
Reporters
Contribute
Acknowledgments
License

Use

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 — transform from Vinyl to vfile
to-vfile — create a vfile from a filepath
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 vfile passes a test
vfile-location — convert between positional and offset locations
vfile-matter — parse the YAML front matter
vfile-message — create a vfile message
vfile-messages-to-vscode-diagnostics — transform vfile messages to VS Code diagnostics
vfile-mkdirp — make sure the directory of a vfile exists on the file system
vfile-rename — rename the path parts of a vfile
vfile-sort — sort messages by line/column
vfile-statistics — count messages per category: failures, warnings, etc
vfile-to-eslint — convert 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 — create a report
vfile-reporter-json — create a JSON report
vfile-reporter-folder-json — create a JSON representation of vfiles
vfile-reporter-pretty — create a pretty report
vfile-reporter-junit — create a jUnit report
vfile-reporter-position — create a report with content excerpts

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, organization, 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!

Gatsby 🥇		Vercel 🥇		Netlify
Holloway	ThemeIsle 🥉	BoostIO 🥉	Expo 🥉	You?

@ifabs/vile

Usage no npm install needed!

README

vile">

Why the fork!?

Option One

Option Two

Option Three

Intro

Sponsors

Install

Contents

Use

API

`VFile([options])`

Example

`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])`

Returns

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

Returns

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

Throws

Utilities

Reporters

Contribute

Acknowledgments

License