.github/workflows/main.yml

@@ -7,18 +7,18 @@ jobs:
     name: '${{matrix.node}} on ${{matrix.os}}'
     runs-on: ${{matrix.os}}
     steps:
-      - uses: actions/checkout@v2
-      - uses: dcodeIO/setup-node-nvm@master
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{matrix.node}}
       - run: npm install
       - run: npm test
-      - uses: codecov/codecov-action@v1
+      - uses: codecov/codecov-action@v3
     strategy:
       matrix:
         os:
           - ubuntu-latest
           - windows-latest
         node:
-          - lts/erbium
+          - lts/gallium
           - node

.npmrc

@@ -1 +1,2 @@
 package-lock=false
+ignore-scripts=true

index.js

@@ -1,10 +1,14 @@
 /**
- * @typedef {import('./lib/index.js').Compatible} Compatible
- * @typedef {import('./lib/index.js').Callback} Callback
  * @typedef {import('./lib/index.js').BufferEncoding} BufferEncoding
- * @typedef {import('./lib/index.js').Mode} Mode
+ * @typedef {import('./lib/index.js').Callback} Callback
+ * @typedef {import('./lib/index.js').Compatible} Compatible
  * @typedef {import('./lib/index.js').ReadOptions} ReadOptions
  * @typedef {import('./lib/index.js').WriteOptions} WriteOptions
  */
 
+// To do: next major: don’t expose `Mode`.
+/**
+ * @typedef {number | string} Mode
+ */
+
 export {toVFile, read, readSync, write, writeSync} from './lib/index.js'

lib/index.js

@@ -2,21 +2,41 @@
  * @typedef {import('vfile').VFileValue} Value
  * @typedef {import('vfile').VFileOptions} Options
  * @typedef {import('vfile').BufferEncoding} BufferEncoding
+ *   Encodings supported by the buffer class.
  *
- * @typedef {number|string} Mode
- * @typedef {BufferEncoding|{encoding?: null|BufferEncoding, flag?: string}} ReadOptions
- * @typedef {BufferEncoding|{encoding?: null|BufferEncoding, mode: Mode?, flag?: string}} WriteOptions
+ *   This is a copy of the types from Node and `VFile`.
  *
- * @typedef {URL|Value} Path Path of the file.
- *   Note: `Value` is used here because it’s a smarter `Buffer`
- * @typedef {Path|Options|VFile} Compatible Things that can be
- *   passed to the function.
+ * @typedef ReadOptions
+ *   Configuration for `fs.readFile`.
+ * @property {BufferEncoding | null | undefined} [encoding]
+ *   Encoding to read file as, will turn `file.value` into a string if passed.
+ * @property {string | undefined} [flag]
+ *   File system flags to use.
+ *
+ * @typedef WriteOptions
+ *   Configuration for `fs.writeFile`.
+ * @property {BufferEncoding | null | undefined} [encoding]
+ *   Encoding to write file as.
+ * @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.
+ *
+ * @typedef {URL | Value} Path
+ *   URL to file or path to file.
+ *
+ *   > 👉 **Note**: `Value` is used here because it’s a smarter `Buffer`
+ * @typedef {Path | Options | VFile} Compatible
+ *   URL to file, path to file, options for file, or actual file.
  */
 
 /**
  * @callback Callback
- * @param {NodeJS.ErrnoException|null} error
- * @param {VFile|null} file
+ *   Callback called after reading or writing a file.
+ * @param {NodeJS.ErrnoException | null} error
+ *   Error when reading or writing was not successful.
+ * @param {VFile | null | undefined} file
+ *   File when reading or writing was successful.
  */
 
 import fs from 'fs'
@@ -25,31 +45,46 @@ import {URL} from 'url'
 import buffer from 'is-buffer'
 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`.
+
 /**
  * Create a virtual file from a description.
- * If `options` is a string or a buffer, it’s used as the path.
- * If it’s a VFile itself, it’s returned instead.
- * In all other cases, the options are passed through to `vfile()`.
  *
- * @param {Compatible} [options]
+ * 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()`.
+ *
+ * @param {Compatible | null | undefined} [description]
+ *   Path to file, file options, or file itself.
  * @returns {VFile}
+ *   Given file or new file.
  */
-export function toVFile(options) {
-  if (typeof options === 'string' || options instanceof URL) {
-    options = {path: options}
-  } else if (buffer(options)) {
-    options = {path: String(options)}
+export function toVFile(description) {
+  if (typeof description === 'string' || description instanceof URL) {
+    description = {path: description}
+  } else if (buffer(description)) {
+    description = {path: String(description)}
   }
 
-  return looksLikeAVFile(options) ? options : new VFile(options)
+  return looksLikeAVFile(description)
+    ? description
+    : // To do: remove when `VFile` allows explicit `null`.
+      new VFile(description || undefined)
 }
 
 /**
  * Create a virtual file and read it in, synchronously.
  *
  * @param {Compatible} description
- * @param {ReadOptions} [options]
+ *   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, options) {
   const file = toVFile(description)
@@ -58,33 +93,47 @@ export function readSync(description, options) {
 }
 
 /**
- * Create a virtual file and write it in, synchronously.
+ * Create a virtual file and write it, synchronously.
  *
  * @param {Compatible} description
- * @param {WriteOptions} [options]
+ *   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
 }
 
+/**
+ * Create a virtual file and read it in, async.
+ *
+ * @param description
+ *   Path to file, file options, or file itself.
+ * @param options
+ *   Encoding to use or Node.JS read options.
+ * @param callback
+ *   Callback called when done.
+ * @returns
+ *   Nothing when a callback is given, otherwise promise that resolves to given
+ *   file or new file.
+ */
 export const read =
   /**
    * @type {{
-   *   (description: Compatible, options: ReadOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | ReadOptions | null | undefined, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
-   *   (description: Compatible, options?: ReadOptions): Promise<VFile>
+   *   (description: Compatible, options?: BufferEncoding | ReadOptions | null | undefined): Promise<VFile>
    * }}
    */
   (
     /**
-     * Create a virtual file and read it in, asynchronously.
-     *
      * @param {Compatible} description
-     * @param {ReadOptions} [options]
-     * @param {Callback} [callback]
+     * @param {BufferEncoding | ReadOptions | null | undefined} [options]
+     * @param {Callback | null | undefined} [callback]
      */
     function (description, options, callback) {
       const file = toVFile(description)
@@ -104,12 +153,13 @@ export const read =
        * @param {VFile} result
        */
       function resolve(result) {
+        // @ts-expect-error: `callback` always defined.
         callback(null, result)
       }
 
       /**
-       * @param {(x: VFile) => void} resolve
-       * @param {(x: Error, y?: VFile) => void} reject
+       * @param {(error: VFile) => void} resolve
+       * @param {(error: NodeJS.ErrnoException, file?: VFile | undefined) => void} reject
        */
       function executor(resolve, reject) {
         /** @type {string} */
@@ -118,13 +168,14 @@ export const read =
         try {
           fp = path.resolve(file.cwd, file.path)
         } catch (error) {
-          return reject(error)
+          const exception = /** @type {NodeJS.ErrnoException} */ (error)
+          return reject(exception)
         }
 
         fs.readFile(fp, options, done)
 
         /**
-         * @param {Error} error
+         * @param {NodeJS.ErrnoException | null} error
          * @param {Value} result
          */
         function done(error, result) {
@@ -139,21 +190,32 @@ export const read =
     }
   )
 
+/**
+ * Create a virtual file and write it, async.
+ *
+ * @param description
+ *   Path to file, file options, or file itself.
+ * @param 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.
+ */
 export const write =
   /**
    * @type {{
-   *   (description: Compatible, options: WriteOptions, callback: Callback): void
+   *   (description: Compatible, options: BufferEncoding | WriteOptions | null | undefined, callback: Callback): void
    *   (description: Compatible, callback: Callback): void
-   *   (description: Compatible, options?: WriteOptions): Promise<VFile>
+   *   (description: Compatible, options?: BufferEncoding | WriteOptions | null | undefined): Promise<VFile>
    * }}
    */
   (
     /**
-     * Create a virtual file and write it in, asynchronously.
-     *
      * @param {Compatible} description
-     * @param {WriteOptions} [options]
-     * @param {Callback} [callback]
+     * @param {BufferEncoding | WriteOptions | null | undefined} [options]
+     * @param {Callback | null | undefined} [callback]
      */
     function (description, options, callback) {
       const file = toVFile(description)
@@ -174,12 +236,13 @@ export const write =
        * @param {VFile} result
        */
       function resolve(result) {
+        // @ts-expect-error: `callback` always defined.
         callback(null, result)
       }
 
       /**
-       * @param {(x: VFile) => void} resolve
-       * @param {(x: Error, y?: VFile) => void} reject
+       * @param {(error: VFile) => void} resolve
+       * @param {(error: NodeJS.ErrnoException, file: VFile | null) => void} reject
        */
       function executor(resolve, reject) {
         /** @type {string} */
@@ -188,17 +251,18 @@ export const write =
         try {
           fp = path.resolve(file.cwd, file.path)
         } catch (error) {
-          return reject(error)
+          const exception = /** @type {NodeJS.ErrnoException} */ (error)
+          return reject(exception, null)
         }
 
-        fs.writeFile(fp, file.value || '', options, done)
+        fs.writeFile(fp, file.value || '', options || null, done)
 
         /**
-         * @param {Error} error
+         * @param {NodeJS.ErrnoException | null} error
          */
         function done(error) {
           if (error) {
-            reject(error)
+            reject(error, null)
           } else {
             resolve(file)
           }
@@ -208,18 +272,23 @@ export const write =
   )
 
 /**
- * @param {Compatible} value
+ * Check if something looks like a vfile.
+ *
+ * @param {Compatible | null | undefined} value
+ *   Value.
  * @returns {value is VFile}
+ *   Whether `value` looks like a `VFile`.
  */
 function looksLikeAVFile(value) {
-  return (
+  return Boolean(
     value &&
-    typeof value === 'object' &&
-    'message' in value &&
-    'messages' in value
+      typeof value === 'object' &&
+      'message' in value &&
+      'messages' in value
   )
 }
 
+// To do: next major: remove?
 toVFile.readSync = readSync
 toVFile.writeSync = writeSync
 toVFile.read = read

package.json

@@ -1,6 +1,6 @@
 {
   "name": "to-vfile",
-  "version": "7.2.3",
+  "version": "7.2.4",
   "description": "vfile utility to create a vfile from a filepath",
   "license": "MIT",
   "keywords": [
@@ -39,23 +39,21 @@
     "vfile": "^5.1.0"
   },
   "devDependencies": {
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
-    "remark-cli": "^10.0.0",
+    "remark-cli": "^11.0.0",
     "remark-preset-wooorm": "^9.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
-    "xo": "^0.47.0"
+    "xo": "^0.53.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"{lib/**,}*.d.ts\" && tsc && type-coverage",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node test.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
+    "test-api": "node --conditions development test.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {