Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

to-vfile

Package Overview
Dependencies
Maintainers
1
Versions
23
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

to-vfile - npm Package Compare versions

Comparing version 7.2.4 to 8.0.0

1

index.d.ts

@@ -6,3 +6,2 @@ export type BufferEncoding = import('./lib/index.js').BufferEncoding

export type WriteOptions = import('./lib/index.js').WriteOptions
export type Mode = number | string
export {toVFile, read, readSync, write, writeSync} from './lib/index.js'

5

index.js

@@ -9,7 +9,2 @@ /**

// To do: next major: don’t expose `Mode`.
/**
* @typedef {number | string} Mode
*/
export {toVFile, read, readSync, write, writeSync} from './lib/index.js'

114

lib/index.d.ts

@@ -1,6 +0,29 @@

/// <reference types="node" resolution-mode="require"/>
export function read(
description: Compatible,
options: BufferEncoding | ReadOptions | null | undefined,
callback: Callback
): undefined
export function read(description: Compatible, callback: Callback): undefined
export function read(
description: Compatible,
options?: BufferEncoding | ReadOptions | null | undefined
): Promise<VFile>
/**
* Create a virtual file and read it in, synchronously.
*
* @param {Compatible} description
* Path to file, file options, or file itself.
* @param {BufferEncoding | ReadOptions | null | undefined} [options]
* Encoding to use or Node.JS read options.
* @returns {VFile}
* Given file or new file.
*/
export function readSync(
description: Compatible,
options?: BufferEncoding | ReadOptions | null | undefined
): VFile
/**
* Create a virtual file from a description.
*
* This is like `VFile`, but it accepts a file path instead of file cotnents.
* This is like `VFile`, but it accepts a file path instead of file contents.
*

@@ -17,22 +40,12 @@ * If `options` is a string, URL, or buffer, it’s used as the path.

export function toVFile(description?: Compatible | null | undefined): VFile
export namespace toVFile {
export {readSync}
export {writeSync}
export {read}
export {write}
}
/**
* Create a virtual file and read it in, synchronously.
*
* @param {Compatible} description
* Path to file, file options, or file itself.
* @param {BufferEncoding | ReadOptions | null | undefined} [options]
* Encoding to use or Node.JS read options.
* @returns {VFile}
* Given file or new file.
*/
export function readSync(
export function write(
description: Compatible,
options?: BufferEncoding | ReadOptions | null | undefined
): VFile
options: BufferEncoding | WriteOptions | null | undefined,
callback: Callback
): undefined
export function write(description: Compatible, callback: Callback): undefined
export function write(
description: Compatible,
options?: BufferEncoding | WriteOptions | null | undefined
): Promise<VFile>
/**

@@ -52,30 +65,23 @@ * Create a virtual file and write it, synchronously.

): VFile
export function read(
description: Compatible,
options: BufferEncoding | ReadOptions | null | undefined,
callback: Callback
): void
export function read(description: Compatible, callback: Callback): void
export function read(
description: Compatible,
options?: BufferEncoding | ReadOptions | null | undefined
): Promise<VFile>
export function write(
description: Compatible,
options: BufferEncoding | WriteOptions | null | undefined,
callback: Callback
): void
export function write(description: Compatible, callback: Callback): void
export function write(
description: Compatible,
options?: BufferEncoding | WriteOptions | null | undefined
): Promise<VFile>
export type Options = import('vfile').VFileOptions
export type Value = import('vfile').VFileValue
export type Options = import('vfile').VFileOptions
/**
* Encodings supported by the buffer class.
*
* This is a copy of the types from Node and `VFile`.
* This is a copy of the types from Node, copied to prevent Node globals from
* being needed.
* Copied from: <https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1761eec/types/node/buffer.d.ts#L223>.
*/
export type BufferEncoding = import('vfile').BufferEncoding
export type BufferEncoding =
| 'ascii'
| 'base64'
| 'base64url'
| 'binary'
| 'hex'
| 'latin1'
| 'ucs-2'
| 'ucs2'
| 'utf-8'
| 'utf16le'
| 'utf8'
/**

@@ -103,9 +109,9 @@ * Configuration for `fs.readFile`.

/**
* File system flags to use.
*/
flag?: string | undefined
/**
* File mode (permission and sticky bits) if the file was newly created.
*/
mode?: number | string | undefined
/**
* File system flags to use.
*/
flag?: string | undefined
}

@@ -121,3 +127,3 @@ /**

*/
export type Compatible = Path | Options | VFile
export type Compatible = Options | Path | VFile
/**

@@ -127,6 +133,10 @@ * Callback called after reading or writing a file.

export type Callback = (
error: NodeJS.ErrnoException | null,
error: NodeJS.ErrnoException | undefined,
file: VFile | null | undefined
) => any
) => undefined
export type Resolve = (result: VFile) => void
export type Reject = (
error: NodeJS.ErrnoException,
result?: VFile | undefined
) => void
import {VFile} from 'vfile'
import {URL} from 'url'

396

lib/index.js
/**
* @typedef {import('vfile').VFileOptions} Options
* @typedef {import('vfile').VFileValue} Value
* @typedef {import('vfile').VFileOptions} Options
* @typedef {import('vfile').BufferEncoding} BufferEncoding
*/
/**
* @typedef {'ascii' | 'base64' | 'base64url' | 'binary' | 'hex' | 'latin1' | 'ucs-2' | 'ucs2' | 'utf-8' | 'utf16le' | 'utf8'} BufferEncoding
* Encodings supported by the buffer class.
*
* This is a copy of the types from Node and `VFile`.
* This is a copy of the types from Node, copied to prevent Node globals from
* being needed.
* Copied from: <https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1761eec/types/node/buffer.d.ts#L223>.
*

@@ -20,6 +25,6 @@ * @typedef ReadOptions

* Encoding to write file as.
* @property {string | undefined} [flag]
* File system flags to use.
* @property {number | string | undefined} [mode]
* File mode (permission and sticky bits) if the file was newly created.
* @property {string | undefined} [flag]
* File system flags to use.
*

@@ -30,3 +35,3 @@ * @typedef {URL | Value} Path

* > 👉 **Note**: `Value` is used here because it’s a smarter `Buffer`
* @typedef {Path | Options | VFile} Compatible
* @typedef {Options | Path | VFile} Compatible
* URL to file, path to file, options for file, or actual file.

@@ -38,43 +43,115 @@ */

* Callback called after reading or writing a file.
* @param {NodeJS.ErrnoException | null} error
* @param {NodeJS.ErrnoException | undefined} error
* Error when reading or writing was not successful.
* @param {VFile | null | undefined} file
* File when reading or writing was successful.
* @returns {undefined}
* Nothing.
*
* @callback Resolve
* @param {VFile} result
* File.
* @returns {void}
* Nothing (note: has to be `void` for TSs `Promise` interface).
*
* @callback Reject
* @param {NodeJS.ErrnoException} error
* Error.
* @param {VFile | undefined} [result]
* File.
* @returns {void}
* Nothing (note: has to be `void` for TSs `Promise` interface).
*/
import fs from 'fs'
import path from 'path'
import {URL} from 'url'
import buffer from 'is-buffer'
import fs from 'node:fs'
import path from 'node:path'
import {VFile} from 'vfile'
// To do: next major: use `node:` prefix.
// To do: next major: use `URL` from global.
// To do: next major: Only pass `undefined`.
// To do: next major: remove `toVFile`, only accept `VFile`s,
// do not return anything.
/**
* Create a virtual file from a description.
* Create a virtual file and read it in, async.
*
* This is like `VFile`, but it accepts a file path instead of file cotnents.
* @overload
* @param {Compatible} description
* @param {BufferEncoding | ReadOptions | null | undefined} options
* @param {Callback} callback
* @returns {undefined}
*
* 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()`.
* @overload
* @param {Compatible} description
* @param {Callback} callback
* @returns {undefined}
*
* @param {Compatible | null | undefined} [description]
* @overload
* @param {Compatible} description
* @param {BufferEncoding | ReadOptions | null | undefined} [options]
* @returns {Promise<VFile>}
*
* @param {Compatible} description
* Path to file, file options, or file itself.
* @returns {VFile}
* Given file or new file.
* @param {BufferEncoding | Callback | ReadOptions | null | undefined} [options]
* Encoding to use or Node.JS read options.
* @param {Callback | null | undefined} [callback]
* Callback called when done.
* @returns {Promise<VFile> | undefined}
* Nothing when a callback is given, otherwise promise that resolves to given
* file or new file.
*/
export function toVFile(description) {
if (typeof description === 'string' || description instanceof URL) {
description = {path: description}
} else if (buffer(description)) {
description = {path: String(description)}
export function read(description, options, callback) {
const file = toVFile(description)
if (!callback && typeof options === 'function') {
callback = options
options = undefined
}
return looksLikeAVFile(description)
? description
: // To do: remove when `VFile` allows explicit `null`.
new VFile(description || undefined)
if (!callback) {
return new Promise(executor)
}
executor(resolve, callback)
/**
* @param {VFile} result
*/
function resolve(result) {
// @ts-expect-error: `callback` always defined.
callback(undefined, result)
}
/**
* @param {Resolve} resolve
* @param {Reject} reject
* @returns {void}
* Nothing (note: has to be `void` for TSs `Promise` interface).
*/
function executor(resolve, reject) {
/** @type {string} */
let fp
try {
fp = path.resolve(file.cwd, file.path)
} catch (error) {
const exception = /** @type {NodeJS.ErrnoException} */ (error)
return reject(exception)
}
// @ts-expect-error: `options` is not a callback.
fs.readFile(fp, options, done)
/**
* @param {NodeJS.ErrnoException | undefined} error
* @param {Value} result
*/
function done(error, result) {
if (error) {
reject(error)
} else {
file.value = result
resolve(file)
}
}
}
}

@@ -99,25 +176,49 @@

/**
* Create a virtual file and write it, synchronously.
* Create a virtual file from a description.
*
* @param {Compatible} description
* This is like `VFile`, but it accepts a file path instead of file contents.
*
* 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()`.
*
* @param {Compatible | null | undefined} [description]
* Path to file, file options, or file itself.
* @param {BufferEncoding | WriteOptions | null | undefined} [options]
* Encoding to use or Node.JS write options.
* @returns {VFile}
* Given file or new file.
*/
export function writeSync(description, options) {
const file = toVFile(description)
fs.writeFileSync(path.resolve(file.cwd, file.path), file.value || '', options)
return file
export function toVFile(description) {
if (typeof description === 'string' || description instanceof URL) {
description = {path: description}
} else if (isUint8Array(description)) {
description = {path: new TextDecoder().decode(description)}
}
return looksLikeAVFile(description) ? description : new VFile(description)
}
/**
* Create a virtual file and read it in, async.
* Create a virtual file and write it, async.
*
* @param description
* @overload
* @param {Compatible} description
* @param {BufferEncoding | WriteOptions | null | undefined} options
* @param {Callback} callback
* @returns {undefined}
*
* @overload
* @param {Compatible} description
* @param {Callback} callback
* @returns {undefined}
*
* @overload
* @param {Compatible} description
* @param {BufferEncoding | WriteOptions | null | undefined} [options]
* @returns {Promise<VFile>}
*
* @param {Compatible} description
* Path to file, file options, or file itself.
* @param options
* Encoding to use or Node.JS read options.
* @param callback
* @param {BufferEncoding | Callback | WriteOptions | null | undefined} [options]
* Encoding to use or Node.JS write options.
* @param {Callback | null | undefined} [callback]
* Callback called when done.

@@ -128,152 +229,72 @@ * @returns

*/
export const read =
/**
* @type {{
* (description: Compatible, options: BufferEncoding | ReadOptions | null | undefined, callback: Callback): void
* (description: Compatible, callback: Callback): void
* (description: Compatible, options?: BufferEncoding | ReadOptions | null | undefined): Promise<VFile>
* }}
*/
(
/**
* @param {Compatible} description
* @param {BufferEncoding | ReadOptions | null | undefined} [options]
* @param {Callback | null | undefined} [callback]
*/
function (description, options, callback) {
const file = toVFile(description)
export function write(description, options, callback) {
const file = toVFile(description)
if (!callback && typeof options === 'function') {
callback = options
options = null
}
// Weird, right? Otherwise `fs` doesn’t accept it.
if (!callback && typeof options === 'function') {
callback = options
options = undefined
}
if (!callback) {
return new Promise(executor)
}
if (!callback) {
return new Promise(executor)
}
executor(resolve, callback)
executor(resolve, callback)
/**
* @param {VFile} result
*/
function resolve(result) {
// @ts-expect-error: `callback` always defined.
callback(null, result)
}
/**
* @param {VFile} result
*/
function resolve(result) {
// @ts-expect-error: `callback` always defined.
callback(undefined, result)
}
/**
* @param {(error: VFile) => void} resolve
* @param {(error: NodeJS.ErrnoException, file?: VFile | undefined) => void} reject
*/
function executor(resolve, reject) {
/** @type {string} */
let fp
/**
* @param {Resolve} resolve
* @param {Reject} reject
*/
function executor(resolve, reject) {
/** @type {string} */
let fp
try {
fp = path.resolve(file.cwd, file.path)
} catch (error) {
const exception = /** @type {NodeJS.ErrnoException} */ (error)
return reject(exception)
}
try {
fp = path.resolve(file.cwd, file.path)
} catch (error) {
const exception = /** @type {NodeJS.ErrnoException} */ (error)
return reject(exception)
}
fs.readFile(fp, options, done)
// @ts-expect-error: `options` is not a callback.
fs.writeFile(fp, file.value || '', options || undefined, done)
/**
* @param {NodeJS.ErrnoException | null} error
* @param {Value} result
*/
function done(error, result) {
if (error) {
reject(error)
} else {
file.value = result
resolve(file)
}
}
/**
* @param {NodeJS.ErrnoException | undefined} error
*/
function done(error) {
if (error) {
reject(error)
} else {
resolve(file)
}
}
)
}
}
/**
* Create a virtual file and write it, async.
* Create a virtual file and write it, synchronously.
*
* @param description
* @param {Compatible} description
* Path to file, file options, or file itself.
* @param options
* @param {BufferEncoding | WriteOptions | null | undefined} [options]
* Encoding to use or Node.JS write options.
* @param callback
* Callback called when done.
* @returns
* Nothing when a callback is given, otherwise promise that resolves to given
* file or new file.
* @returns {VFile}
* Given file or new file.
*/
export const write =
/**
* @type {{
* (description: Compatible, options: BufferEncoding | WriteOptions | null | undefined, callback: Callback): void
* (description: Compatible, callback: Callback): void
* (description: Compatible, options?: BufferEncoding | WriteOptions | null | undefined): Promise<VFile>
* }}
*/
(
/**
* @param {Compatible} description
* @param {BufferEncoding | WriteOptions | null | undefined} [options]
* @param {Callback | null | undefined} [callback]
*/
function (description, options, callback) {
const file = toVFile(description)
export function writeSync(description, options) {
const file = toVFile(description)
fs.writeFileSync(path.resolve(file.cwd, file.path), file.value || '', options)
return file
}
// Weird, right? Otherwise `fs` doesn’t accept it.
if (!callback && typeof options === 'function') {
callback = options
options = undefined
}
if (!callback) {
return new Promise(executor)
}
executor(resolve, callback)
/**
* @param {VFile} result
*/
function resolve(result) {
// @ts-expect-error: `callback` always defined.
callback(null, result)
}
/**
* @param {(error: VFile) => void} resolve
* @param {(error: NodeJS.ErrnoException, file: VFile | null) => void} reject
*/
function executor(resolve, reject) {
/** @type {string} */
let fp
try {
fp = path.resolve(file.cwd, file.path)
} catch (error) {
const exception = /** @type {NodeJS.ErrnoException} */ (error)
return reject(exception, null)
}
fs.writeFile(fp, file.value || '', options || null, done)
/**
* @param {NodeJS.ErrnoException | null} error
*/
function done(error) {
if (error) {
reject(error, null)
} else {
resolve(file)
}
}
}
}
)
/**

@@ -296,6 +317,17 @@ * Check if something looks like a vfile.

// To do: next major: remove?
toVFile.readSync = readSync
toVFile.writeSync = writeSync
toVFile.read = read
toVFile.write = write
/**
* Check whether `value` is an `Uint8Array`.
*
* @param {unknown} value
* thing.
* @returns {value is Uint8Array}
* Whether `value` is an `Uint8Array`.
*/
function isUint8Array(value) {
return Boolean(
value &&
typeof value === 'object' &&
'byteLength' in value &&
'byteOffset' in value
)
}

42

package.json
{
"name": "to-vfile",
"version": "7.2.4",
"description": "vfile utility to create a vfile from a filepath",
"version": "8.0.0",
"description": "vfile utility to read and write to the file system",
"license": "MIT",

@@ -30,4 +30,3 @@ "keywords": [

"type": "module",
"main": "index.js",
"types": "index.d.ts",
"exports": "./index.js",
"files": [

@@ -39,8 +38,8 @@ "lib/",

"dependencies": {
"is-buffer": "^2.0.0",
"vfile": "^5.1.0"
"vfile": "^6.0.0"
},
"devDependencies": {
"@types/node": "^18.0.0",
"@types/node": "^20.0.0",
"c8": "^7.0.0",
"is-buffer": "^2.0.0",
"prettier": "^2.0.0",

@@ -50,4 +49,4 @@ "remark-cli": "^11.0.0",

"type-coverage": "^2.0.0",
"typescript": "^4.0.0",
"xo": "^0.53.0"
"typescript": "^5.0.0",
"xo": "^0.54.0"
},

@@ -59,22 +58,16 @@ "scripts": {

"test-api": "node --conditions development test.js",
"test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
"test-coverage": "c8 --100 --reporter lcov npm run test-api",
"test": "npm run build && npm run format && npm run test-coverage"
},
"prettier": {
"tabWidth": 2,
"useTabs": false,
"singleQuote": true,
"bracketSpacing": false,
"semi": false,
"trailingComma": "none"
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "none",
"useTabs": false
},
"xo": {
"prettier": true,
"rules": {
"unicorn/prefer-node-protocol": "off"
}
},
"remarkConfig": {
"plugins": [
"preset-wooorm"
"remark-preset-wooorm"
]

@@ -85,5 +78,8 @@ },

"detail": true,
"strict": true,
"ignoreCatch": true
"ignoreCatch": true,
"strict": true
},
"xo": {
"prettier": true
}
}

74

readme.md

@@ -36,5 +36,6 @@ # to-vfile

This utility places file paths and the file system first.
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 files.
focuses on the file system, which is a common case when working with *actual*
files from Node.js.

@@ -49,3 +50,3 @@ ## When should I use this?

This package is [ESM only][esm].
In Node.js (version 14.14+ and 16.0+), install with [npm][]:
In Node.js (version 16+), install with [npm][]:

@@ -59,13 +60,5 @@ ```sh

```js
import {toVFile, read, readSync, write, writeSync} from 'https://esm.sh/to-vfile@7'
import {toVFile, read, readSync, write, writeSync} from 'https://esm.sh/to-vfile@8'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import {toVFile, read, readSync, write, writeSync} from 'https://esm.sh/to-vfile@7?bundle'
</script>
```
## Use

@@ -86,25 +79,25 @@

VFile {
cwd: '/Users/tilde/Projects/oss/to-vfile',
data: {},
messages: [],
history: [ 'readme.md' ],
cwd: '/Users/tilde/Projects/oss/to-vfile'
messages: []
}
VFile {
cwd: '/Users/tilde/Projects/oss/to-vfile',
data: {},
messages: [],
history: [ '/Users/tilde/Projects/oss/to-vfile/readme.md' ],
cwd: '/Users/tilde/Projects/oss/to-vfile'
messages: []
}
VFile {
cwd: '/Users/tilde/Projects/oss/to-vfile',
data: {},
history: [ '.git/HEAD' ],
messages: [],
history: [ '.git/HEAD' ],
cwd: '/Users/tilde/Projects/oss/to-vfile',
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: [],
history: [ '.git/HEAD' ],
cwd: '/Users/tilde/Projects/oss/to-vfile',
value: 'ref: refs/heads/main\n'

@@ -146,3 +139,3 @@ }

* `(description[, options], Callback): void`
* `(description[, options], Callback): undefined`
* `(description[, options]): Promise<VFile>`

@@ -185,3 +178,3 @@

* `(description[, options], Callback): void`
* `(description[, options], Callback): undefined`
* `(description[, options]): Promise<VFile>`

@@ -222,3 +215,3 @@

This is a copy of the types from Node and [`VFile`][vfile].
This is a copy of the types from Node.

@@ -230,12 +223,12 @@ ###### Type

| 'ascii'
| 'utf8'
| 'utf-8'
| 'utf16le'
| 'ucs2'
| 'ucs-2'
| 'base64'
| 'base64url'
| 'latin1'
| 'binary'
| 'hex'
| 'latin1'
| 'ucs-2'
| 'ucs2'
| 'utf-8'
| 'utf16le'
| 'utf8'
```

@@ -256,3 +249,3 @@

Nothing (`void`).
Nothing (`undefined`).

@@ -266,9 +259,7 @@ ### `Compatible`

```ts
type Compatible = Buffer | URL | VFileOptions | VFile | string
type Compatible = Uint8Array | URL | VFile | VFileOptions | string
```
<!-- To do: fix link to `VFileOptions` when `VFile` is updated -->
See [`VFileOptions`][vfile-options] and [`VFile`][vfile].
See [`VFileOptions`][vfile] and [`VFile`][vfile].
### `ReadOptions`

@@ -281,3 +272,3 @@

* `encoding` ([`BufferEncoding`][api-buffer-encoding], optional)
— encoding to read file as, will turn `file.value` into a string if passed
— encoding to read file as, will turn `file.value` into a `string` if passed
* `flag` (`string`, optional)

@@ -293,3 +284,3 @@ — file system flags to use

* `encoding` ([`BufferEncoding`][api-buffer-encoding], optional)
— encoding to write file as
— encoding to write file as when `file.value` is a `string`
* `mode` (`number | string`, optional)

@@ -312,7 +303,10 @@ — file mode (permission and sticky bits) if the file was newly created

Projects maintained by the unified collective are compatible with all maintained
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
As of now, that is Node.js 14.14+ and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
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

@@ -378,2 +372,4 @@

[vfile-options]: https://github.com/vfile/vfile#options
[promise]: https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Promise

@@ -380,0 +376,0 @@

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc