Skip to content

Commit 470ebc4

Browse files
wooormwooorm
committedFeb 8, 2023
Add improved docs
·
8.0.07.2.4
1 parent 164d3a7 commit 470ebc4

File tree

4 files changed

+238
-53
lines changed

4 files changed

+238
-53
lines changed
 

‎index.js

+7-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
/**
2-
* @typedef {import('./lib/index.js').Compatible} Compatible
3-
* @typedef {import('./lib/index.js').Callback} Callback
42
* @typedef {import('./lib/index.js').BufferEncoding} BufferEncoding
5-
* @typedef {import('./lib/index.js').Mode} Mode
3+
* @typedef {import('./lib/index.js').Callback} Callback
4+
* @typedef {import('./lib/index.js').Compatible} Compatible
65
* @typedef {import('./lib/index.js').ReadOptions} ReadOptions
76
* @typedef {import('./lib/index.js').WriteOptions} WriteOptions
87
*/
98

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

‎lib/index.js

+28-11
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,25 @@
22
* @typedef {import('vfile').VFileValue} Value
33
* @typedef {import('vfile').VFileOptions} Options
44
* @typedef {import('vfile').BufferEncoding} BufferEncoding
5+
* Encodings supported by the buffer class.
56
*
6-
* @typedef {number | string} Mode
7-
* @typedef {{encoding?: BufferEncoding | null | undefined, flag?: string | undefined}} ReadOptions
8-
* @typedef {{encoding?: null | undefined | BufferEncoding, mode?: Mode | undefined, flag?: string | undefined}} WriteOptions
7+
* This is a copy of the types from Node and `VFile`.
98
*
9+
* @typedef ReadOptions
10+
* Configuration for `fs.readFile`.
11+
* @property {BufferEncoding | null | undefined} [encoding]
12+
* Encoding to read file as, will turn `file.value` into a string if passed.
13+
* @property {string | undefined} [flag]
14+
* File system flags to use.
15+
*
16+
* @typedef WriteOptions
17+
* Configuration for `fs.writeFile`.
18+
* @property {BufferEncoding | null | undefined} [encoding]
19+
* Encoding to write file as.
20+
* @property {number | string | undefined} [mode]
21+
* File mode (permission and sticky bits) if the file was newly created.
22+
* @property {string | undefined} [flag]
23+
* File system flags to use.
1024
*
1125
* @typedef {URL | Value} Path
1226
* URL to file or path to file.
@@ -38,14 +52,16 @@ import {VFile} from 'vfile'
3852
/**
3953
* Create a virtual file from a description.
4054
*
55+
* This is like `VFile`, but it accepts a file path instead of file cotnents.
56+
*
4157
* If `options` is a string, URL, or buffer, it’s used as the path.
42-
* Otherwise, if it’s a `VFile`, that’s returned instead.
58+
* Otherwise, if it’s a file, that’s returned instead.
4359
* Otherwise, the options are passed through to `new VFile()`.
4460
*
4561
* @param {Compatible | null | undefined} [description]
4662
* Path to file, file options, or file itself.
4763
* @returns {VFile}
48-
* Given `VFile` or new `VFile`.
64+
* Given file or new file.
4965
*/
5066
export function toVFile(description) {
5167
if (typeof description === 'string' || description instanceof URL) {
@@ -68,7 +84,7 @@ export function toVFile(description) {
6884
* @param {BufferEncoding | ReadOptions | null | undefined} [options]
6985
* Encoding to use or Node.JS read options.
7086
* @returns {VFile}
71-
* Given `VFile` or new `VFile`.
87+
* Given file or new file.
7288
*/
7389
export function readSync(description, options) {
7490
const file = toVFile(description)
@@ -84,7 +100,7 @@ export function readSync(description, options) {
84100
* @param {BufferEncoding | WriteOptions | null | undefined} [options]
85101
* Encoding to use or Node.JS write options.
86102
* @returns {VFile}
87-
* Given `VFile` or new `VFile`.
103+
* Given file or new file.
88104
*/
89105
export function writeSync(description, options) {
90106
const file = toVFile(description)
@@ -103,12 +119,12 @@ export function writeSync(description, options) {
103119
* Callback called when done.
104120
* @returns
105121
* Nothing when a callback is given, otherwise promise that resolves to given
106-
* `VFile` or new `VFile`.
122+
* file or new file.
107123
*/
108124
export const read =
109125
/**
110126
* @type {{
111-
* (description: Compatible, options: BufferEncoding | ReadOptions, callback: Callback): void
127+
* (description: Compatible, options: BufferEncoding | ReadOptions | null | undefined, callback: Callback): void
112128
* (description: Compatible, callback: Callback): void
113129
* (description: Compatible, options?: BufferEncoding | ReadOptions | null | undefined): Promise<VFile>
114130
* }}
@@ -185,12 +201,12 @@ export const read =
185201
* Callback called when done.
186202
* @returns
187203
* Nothing when a callback is given, otherwise promise that resolves to given
188-
* `VFile` or new `VFile`.
204+
* file or new file.
189205
*/
190206
export const write =
191207
/**
192208
* @type {{
193-
* (description: Compatible, options: BufferEncoding | WriteOptions, callback: Callback): void
209+
* (description: Compatible, options: BufferEncoding | WriteOptions | null | undefined, callback: Callback): void
194210
* (description: Compatible, callback: Callback): void
195211
* (description: Compatible, options?: BufferEncoding | WriteOptions | null | undefined): Promise<VFile>
196212
* }}
@@ -272,6 +288,7 @@ function looksLikeAVFile(value) {
272288
)
273289
}
274290

291+
// To do: next major: remove?
275292
toVFile.readSync = readSync
276293
toVFile.writeSync = writeSync
277294
toVFile.read = read

‎readme.md

+202-38
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,16 @@
1616
* [Install](#install)
1717
* [Use](#use)
1818
* [API](#api)
19-
* [`toVFile(options)`](#tovfileoptions)
20-
* [`read(options[, encoding][, callback])`](#readoptions-encoding-callback)
21-
* [`readSync(options[, encoding])`](#readsyncoptions-encoding)
22-
* [`write(options[, fsOptions][, callback])`](#writeoptions-fsoptions-callback)
23-
* [`writeSync(options[, fsOptions])`](#writesyncoptions-fsoptions)
19+
* [`toVFile(description)`](#tovfiledescription)
20+
* [`read(description[, options][, callback])`](#readdescription-options-callback)
21+
* [`readSync(description[, options])`](#readsyncdescription-options)
22+
* [`write(description[, options][, callback])`](#writedescription-options-callback)
23+
* [`writeSync(description[, options])`](#writesyncdescription-options)
24+
* [`BufferEncoding`](#bufferencoding)
25+
* [`Callback`](#callback)
26+
* [`Compatible`](#compatible)
27+
* [`ReadOptions`](#readoptions)
28+
* [`WriteOptions`](#writeoptions)
2429
* [Types](#types)
2530
* [Compatibility](#compatibility)
2631
* [Contribute](#contribute)
@@ -40,7 +45,7 @@ Use `vfile` if there might not be a file system.
4045
## Install
4146

4247
This package is [ESM only][esm].
43-
In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
48+
In Node.js (version 14.14+ and 16.0+), install with [npm][]:
4449

4550
```sh
4651
npm install to-vfile
@@ -104,58 +109,197 @@ VFile {
104109
105110
## API
106111
107-
This package exports the identifiers `toVFile`, `read`, `readSync`, `write`,
108-
and `writeSync`.
112+
This package exports the identifiers [`read`][api-read],
113+
[`readSync`][api-read-sync], [`toVFile`][api-to-vfile],
114+
[`write`][api-write], and [`writeSync`][api-write-sync].
109115
There is no default export.
110116
111-
### `toVFile(options)`
117+
### `toVFile(description)`
112118
113-
Create a virtual file.
114-
Works like the [`VFile`][vfile] constructor, except when `options` is `string`
115-
or `Buffer`, in which case it’s treated as `{path: options}` instead of
116-
`{value: options}`, or when `options` is a `URL` object, in which case it’s
117-
treated as `{path: fileURLToPath(options)}`.
119+
Create a virtual file from a description.
118120
119-
### `read(options[, encoding][, callback])`
121+
This is like `VFile`, but it accepts a file path instead of file cotnents.
120122
121-
Creates a virtual file from options (`toVFile(options)`), reads the file from
122-
the file system and populates `file.value` with the result.
123-
If `encoding` is specified, it’s passed to `fs.readFile`.
124-
If `callback` is given, calls it with either an error or the populated virtual
125-
file.
126-
If `callback` is not given, returns a [`Promise`][promise] that is rejected
127-
with an error or resolved with the populated virtual file.
123+
If `options` is a string, URL, or buffer, it’s used as the path.
124+
Otherwise, if it’s a file, that’s returned instead.
125+
Otherwise, the options are passed through to `new VFile()`.
128126
129-
### `readSync(options[, encoding])`
127+
###### Parameters
130128
131-
Like `read` but synchronous.
132-
Either throws an error or returns a populated virtual file.
129+
* `description` ([`Compatible`][api-compatible], optional)
130+
— fath to file, file options, or file itself
133131
134-
### `write(options[, fsOptions][, callback])`
132+
###### Returns
135133
136-
Creates a virtual file from `options` (`toVFile(options)`), writes the file to
137-
the file system.
138-
`fsOptions` are passed to `fs.writeFile`.
139-
If `callback` is given, calls it with an error, if any.
140-
If `callback` is not given, returns a [`Promise`][promise] that is rejected
141-
with an error or resolved with the written virtual file.
134+
Given file or new file ([`VFile`][vfile]).
142135
143-
### `writeSync(options[, fsOptions])`
136+
### `read(description[, options][, callback])`
144137
145-
Like `write` but synchronous.
146-
Either throws an error or returns a populated virtual file.
138+
Create a virtual file and read it in, async.
139+
140+
###### Signatures
141+
142+
* `(description[, options], Callback): void`
143+
* `(description[, options]): Promise<VFile>`
144+
145+
###### Parameters
146+
147+
* `description` ([`Compatible`][api-compatible])
148+
— path to file, file options, or file itself
149+
* `options` ([`BufferEncoding`][api-buffer-encoding],
150+
[`ReadOptions`][api-read-options], optional)
151+
* `callback` ([`Callback`][api-callback], optional)
152+
— callback called when done
153+
154+
###### Returns
155+
156+
Nothing when a callback is given, otherwise [promise][] that resolves to given
157+
file or new file ([`VFile`][vfile]).
158+
159+
### `readSync(description[, options])`
160+
161+
Create a virtual file and read it in, synchronously.
162+
163+
###### Parameters
164+
165+
* `description` ([`Compatible`][api-compatible])
166+
— path to file, file options, or file itself
167+
* `options` ([`BufferEncoding`][api-buffer-encoding],
168+
[`ReadOptions`][api-read-options], optional)
169+
170+
###### Returns
171+
172+
Given file or new file ([`VFile`][vfile]).
173+
174+
### `write(description[, options][, callback])`
175+
176+
Create a virtual file and write it, async.
177+
178+
###### Signatures
179+
180+
* `(description[, options], Callback): void`
181+
* `(description[, options]): Promise<VFile>`
182+
183+
###### Parameters
184+
185+
* `description` ([`Compatible`][api-compatible])
186+
— path to file, file options, or file itself
187+
* `options` ([`BufferEncoding`][api-buffer-encoding],
188+
[`WriteOptions`][api-write-options], optional)
189+
* `callback` ([`Callback`][api-callback], optional)
190+
— callback called when done
191+
192+
###### Returns
193+
194+
Nothing when a callback is given, otherwise [promise][] that resolves to given
195+
file or new file ([`VFile`][vfile]).
196+
197+
### `writeSync(description[, options])`
198+
199+
Create a virtual file and write it, async.
200+
201+
###### Parameters
202+
203+
* `description` ([`Compatible`][api-compatible])
204+
— path to file, file options, or file itself
205+
* `options` ([`BufferEncoding`][api-buffer-encoding],
206+
[`WriteOptions`][api-write-options], optional)
207+
208+
###### Returns
209+
210+
Given file or new file ([`VFile`][vfile]).
211+
212+
### `BufferEncoding`
213+
214+
Encodings supported by the buffer class (TypeScript type).
215+
216+
This is a copy of the types from Node and [`VFile`][vfile].
217+
218+
###### Type
219+
220+
```ts
221+
export type BufferEncoding =
222+
| 'ascii'
223+
| 'utf8'
224+
| 'utf-8'
225+
| 'utf16le'
226+
| 'ucs2'
227+
| 'ucs-2'
228+
| 'base64'
229+
| 'base64url'
230+
| 'latin1'
231+
| 'binary'
232+
| 'hex'
233+
```
234+
235+
### `Callback`
236+
237+
Callback called after reading or writing a file (TypeScript type).
238+
239+
###### Parameters
240+
241+
* `error` (`Error`, optional)
242+
— error when reading or writing was not successful
243+
* `file` ([`VFile`][vfile], optional)
244+
— file when reading or writing was successful
245+
246+
###### Returns
247+
248+
Nothing (`void`).
249+
250+
### `Compatible`
251+
252+
URL to file, path to file, options for file, or actual file (TypeScript type).
253+
254+
###### Type
255+
256+
```ts
257+
export type Compatible = Buffer | URL | VFileOptions | VFile | string
258+
```
259+
260+
<!-- To do: fix link to `VFileOptions` when `VFile` is updated -->
261+
262+
See [`VFileOptions`][vfile] and [`VFile`][vfile].
263+
264+
### `ReadOptions`
265+
266+
Configuration for `fs.readFile` (TypeScript type).
267+
268+
###### Fields
269+
270+
* `encoding` ([`BufferEncoding`][api-buffer-encoding], optional)
271+
— encoding to read file as, will turn `file.value` into a string if passed
272+
* `flag` (`string`, optional)
273+
— file system flags to use
274+
275+
### `WriteOptions`
276+
277+
Configuration for `fs.writeFile` (TypeScript type).
278+
279+
###### Fields
280+
281+
* `encoding` ([`BufferEncoding`][api-buffer-encoding], optional)
282+
— encoding to write file as
283+
* `mode` (`number | string`, optional)
284+
— file mode (permission and sticky bits) if the file was newly created
285+
* `flag` (`string`, optional)
286+
— file system flags to use
147287
148288
## Types
149289
150290
This package is fully typed with [TypeScript][].
151-
It exports the additional types `Compatible`, `Callback`, `BufferEncoding`,
152-
`Mode`, `ReadOptions`, and `WriteOptions`.
291+
It exports the additional types
292+
[`BufferEncoding`][api-buffer-encoding],
293+
[`Callback`][api-callback],
294+
[`Compatible`][api-compatible],
295+
[`ReadOptions`][api-read-options], and
296+
[`WriteOptions`][api-write-options].
153297
154298
## Compatibility
155299
156300
Projects maintained by the unified collective are compatible with all maintained
157301
versions of Node.js.
158-
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
302+
As of now, that is Node.js 14.14+ and 16.0+.
159303
Our projects sometimes work with older versions, but this is not guaranteed.
160304
161305
## Contribute
@@ -219,3 +363,23 @@ abide by its terms.
219363
[vfile]: https://github.com/vfile/vfile
220364
221365
[promise]: https://developer.mozilla.org/Web/JavaScript/Reference/Global_Objects/Promise
366+
367+
[api-read]: #readdescription-options-callback
368+
369+
[api-read-sync]: #readsyncdescription-options
370+
371+
[api-to-vfile]: #tovfiledescription
372+
373+
[api-write]: #writedescription-options-callback
374+
375+
[api-write-sync]: #writesyncdescription-options
376+
377+
[api-buffer-encoding]: #bufferencoding
378+
379+
[api-callback]: #callback
380+
381+
[api-compatible]: #compatible
382+
383+
[api-read-options]: #readoptions
384+
385+
[api-write-options]: #writeoptions

‎test.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ const join = path.join
1313

1414
const fixture = fs.readFileSync('readme.md', 'utf8')
1515

16-
test('toVFile()', async (t) => {
16+
test('toVFile', async (t) => {
1717
assert.deepEqual(
1818
Object.keys(mod).sort(),
1919
['read', 'readSync', 'toVFile', 'write', 'writeSync'],

0 commit comments

Comments
 (0)
Please sign in to comment.