to-vfile

vfile utility to read and write to the file system

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
to-vfile
5708.0.010 months ago9 years agoMinified + gzip package size for to-vfile in KB

Popular Searches

Readme

to-vfile
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
vfile utility to read and write to the file system.

Contents

*   [`toVFile(description)`](#tovfiledescription)
*   [`read(description[, options][, callback])`](#readdescription-options-callback)
*   [`readSync(description[, options])`](#readsyncdescription-options)
*   [`write(description[, options][, callback])`](#writedescription-options-callback)
*   [`writeSync(description[, options])`](#writesyncdescription-options)
*   [`BufferEncoding`](#bufferencoding)
*   [`Callback`](#callback)
*   [`Compatible`](#compatible)
*   [`ReadOptions`](#readoptions)
*   [`WriteOptions`](#writeoptions)

What is this?

This utility puts the file system first. Where vfile itself focusses on file values (the file contents), this instead focuses on the file system, which is a common case when working with actual files from Node.js.

When should I use this?

Use this if you know there’s a file system and want to use it. Use vfile if there might not be a file system.

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install to-vfile

In Deno with esm.shesmsh:
import {toVFile, read, readSync, write, writeSync} from 'https://esm.sh/to-vfile@8'

Use

import {toVFile, read} from 'to-vfile'

console.log(toVFile('readme.md'))
console.log(toVFile(new URL('readme.md', import.meta.url)))
console.log(await read('.git/HEAD'))
console.log(await read('.git/HEAD', 'utf8'))

Yields:
VFile {
  cwd: '/Users/tilde/Projects/oss/to-vfile',
  data: {},
  history: [ 'readme.md' ],
  messages: []
}
VFile {
  cwd: '/Users/tilde/Projects/oss/to-vfile',
  data: {},
  history: [ '/Users/tilde/Projects/oss/to-vfile/readme.md' ],
  messages: []
}
VFile {
  cwd: '/Users/tilde/Projects/oss/to-vfile',
  data: {},
  history: [ '.git/HEAD' ],
  messages: [],
  value: <Buffer 72 65 66 3a 20 72 65 66 73 2f 68 65 61 64 73 2f 6d 61 69 6e 0a>
}
VFile {
  cwd: '/Users/tilde/Projects/oss/to-vfile',
  data: {},
  history: [ '.git/HEAD' ],
  messages: [],
  value: 'ref: refs/heads/main\n'
}

API

This package exports the identifiers readapi-read, readSyncapi-read-sync, toVFileapi-to-vfile, writeapi-write, and writeSyncapi-write-sync. There is no default export.

toVFile(description)

Create a virtual file from a description.
This is like VFile, but it accepts a file path instead of file cotnents.
If options is a string, URL, or buffer, it’s used as the path. Otherwise, if it’s a file, that’s returned instead. Otherwise, the options are passed through to new VFile().
Parameters
— fath to file, file options, or file itself
Returns
Given file or new file (VFilevfile).

read(description[, options][, callback])

Create a virtual file and read it in, async.
Signatures
  • (description[, options], Callback): undefined
  • (description[, options]): Promise<VFile>
Parameters
— path to file, file options, or file itself
[`ReadOptions`][api-read-options], optional)
— callback called when done
Returns
Nothing when a callback is given, otherwise promise that resolves to given file or new file (VFilevfile).

readSync(description[, options])

Create a virtual file and read it in, synchronously.
Parameters
— path to file, file options, or file itself
[`ReadOptions`][api-read-options], optional)
Returns
Given file or new file (VFilevfile).

write(description[, options][, callback])

Create a virtual file and write it, async.
Signatures
  • (description[, options], Callback): undefined
  • (description[, options]): Promise<VFile>
Parameters
— path to file, file options, or file itself
[`WriteOptions`][api-write-options], optional)
— callback called when done
Returns
Nothing when a callback is given, otherwise promise that resolves to given file or new file (VFilevfile).

writeSync(description[, options])

Create a virtual file and write it, synchronously.
Parameters
— path to file, file options, or file itself
[`WriteOptions`][api-write-options], optional)
Returns
Given file or new file (VFilevfile).

BufferEncoding

Encodings supported by the buffer class (TypeScript type).
This is a copy of the types from Node.
Type
type BufferEncoding =
  | 'ascii'
  | 'base64'
  | 'base64url'
  | 'binary'
  | 'hex'
  | 'latin1'
  | 'ucs-2'
  | 'ucs2'
  | 'utf-8'
  | 'utf16le'
  | 'utf8'

Callback

Callback called after reading or writing a file (TypeScript type).
Parameters
  • error (Error, optional)
— error when reading or writing was not successful
— file when reading or writing was successful
Returns
Nothing (undefined).

Compatible

URL to file, path to file, options for file, or actual file (TypeScript type).
Type
type Compatible = Uint8Array | URL | VFile | VFileOptions | string

See VFileOptionsvfile-options and VFilevfile.

ReadOptions

Configuration for fs.readFile (TypeScript type).
Fields
— encoding to read file as, will turn `file.value` into a `string` if passed
  • flag (string, optional)
— file system flags to use

WriteOptions

Configuration for fs.writeFile (TypeScript type).
Fields
— encoding to write file as when `file.value` is a `string`
  • mode (number | string, optional)
— file mode (permission and sticky bits) if the file was newly created
  • flag (string, optional)
— file system flags to use

Types

This package is fully typed with TypeScript. It exports the additional types BufferEncodingapi-buffer-encoding, Callbackapi-callback, Compatibleapi-compatible, ReadOptionsapi-read-options, and WriteOptionsapi-write-options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, vfile@^8, compatible with Node.js 16.

Contribute

See contributing.mdcontributing in vfile/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor