vfile - npm Package Compare versions

Comparing version 5.3.6 to 5.3.7

index.d.ts

@@ -14,8 +14,9 @@ import type {Reporter} from './lib/index.js'
  * Contents of the file.
- * Can either be text, or a Buffer like structure.
- * This does not directly use type `Buffer`, because it can also be used in a
- * browser context.
- * Instead this leverages `Uint8Array` which is the base type for `Buffer`,
- * and a native JavaScript construct.
+ *
+ * Can either be text or a `Buffer` structure.
  */
+// Note: this does not directly use type `Buffer`, because it can also be used
+// in a browser context.
+// Instead this leverages `Uint8Array` which is the base type for `Buffer`,
+// and a native JavaScript construct.
 export type Value = string | MaybeBuffer
@@ -41,3 +42,3 @@
 /**
- * Place to store custom information.
+ * Custom information.
  *
@@ -44,0 +45,0 @@ * Known attributes can be added to @see {@link DataMap}

lib/index.d.ts

@@ -5,7 +5,9 @@ export class VFile {
    *
-   * If `options` is `string` or `Buffer`, it’s treated as `{value: options}`.
-   * If `options` is a `URL`, it’s treated as `{path: options}`.
-   * If `options` is a `VFile`, shallow copies its data over to the new file.
-   * All fields in `options` are set on the newly created `VFile`.
+   * `options` is treated as:
    *
+   * *   `string` or `Buffer` — `{value: options}`
+   * *   `URL` — `{path: options}`
+   * *   `VFile` — shallow copies its data over to the new file
+   * *   `object` — all fields are shallow copied over to the new file
+   *
    * Path related fields are set in the following order (least specific to
@@ -15,12 +17,17 @@ * most specific): `history`, `path`, `basename`, `stem`, `extname`,
    *
-   * It’s not possible to set either `dirname` or `extname` without setting
-   * either `history`, `path`, `basename`, or `stem` as well.
+   * You cannot set `dirname` or `extname` without setting either `history`,
+   * `path`, `basename`, or `stem` too.
    *
-   * @param {Compatible} [value]
+   * @param {Compatible | null | undefined} [value]
+   *   File value.
+   * @returns
+   *   New instance.
    */
-  constructor(value?: Compatible | undefined)
+  constructor(value?: Compatible | null | undefined)
   /**
    * Place to store custom information (default: `{}`).
+   *
    * It’s OK to store custom data directly on the file but moving it to
    * `data` is recommended.
+   *
    * @type {Data}
@@ -31,2 +38,3 @@ */
    * List of messages associated with the file.
+   *
    * @type {Array<VFileMessage>}
@@ -37,3 +45,5 @@ */
    * List of filepaths the file moved between.
+   *
    * The first is the original path and the last is the current path.
+   *
    * @type {Array<string>}
@@ -44,2 +54,3 @@ */
    * Base of `path` (default: `process.cwd()` or `'/'` in browsers).
+   *
    * @type {string}
@@ -50,2 +61,3 @@ */
    * Raw value.
+   *
    * @type {Value}
@@ -56,3 +68,5 @@ */
    * Whether a file was saved to disk.
+   *
    * This is used by vfile reporters.
+   *
    * @type {boolean}
@@ -62,6 +76,7 @@ */
   /**
-   * Sometimes files have a non-string, compiled, representation.
-   * This can be stored in the `result` field.
+   * Custom, non-string, compiled, representation.
+   *
+   * This is used by unified to store non-string results.
    * One example is when turning markdown into React nodes.
-   * This is used by unified to store non-string results.
+   *
    * @type {unknown}
@@ -71,15 +86,18 @@ */
   /**
-   * Sometimes files have a source map associated with them.
-   * This can be stored in the `map` field.
-   * This should be a `Map` type, which is equivalent to the `RawSourceMap`
-   * type from the `source-map` module.
-   * @type {Map|undefined}
+   * Source map.
+   *
+   * This type is equivalent to the `RawSourceMap` type from the `source-map`
+   * module.
+   *
+   * @type {Map | null | undefined}
    */
-  map: Map | undefined
+  map: Map | null | undefined
   /**
    * Set the full path (example: `'~/index.min.js'`).
+   *
    * Cannot be nullified.
    * You can set a file URL (a `URL` object with a `file:` protocol) which will
    * be turned into a path with `url.fileURLToPath`.
-   * @param {string|URL} path
+   *
+   * @param {string | URL} path
    */
@@ -89,2 +107,3 @@ set path(arg: string)
    * Get the full path (example: `'~/index.min.js'`).
+   *
    * @returns {string}
@@ -95,2 +114,3 @@ */
    * Set the parent path (example: `'~'`).
+   *
    * Cannot be set if there’s no `path` yet.
@@ -105,2 +125,3 @@ */
    * Set basename (including extname) (`'index.min.js'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -117,2 +138,3 @@ * on windows).
    * Set the extname (including dot) (example: `'.js'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -129,2 +151,3 @@ * on windows).
    * Set the stem (basename w/o extname) (example: `'index.min'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -142,20 +165,22 @@ * on windows).
    *
-   * @param {BufferEncoding} [encoding='utf8']
-   *   When `value` is a `Buffer`, `encoding` is a character encoding to
-   *   understand it as (default: `'utf8'`).
+   * @param {BufferEncoding | null | undefined} [encoding='utf8']
+   *   Character encoding to understand `value` as when it’s a `Buffer`
+   *   (default: `'utf8'`).
    * @returns {string}
    *   Serialized file.
    */
-  toString(encoding?: BufferEncoding | undefined): string
+  toString(encoding?: BufferEncoding | null | undefined): string
   /**
-   * Constructs a new `VFileMessage`, where `fatal` is set to `false`, and
-   * associates it with the file by adding it to `vfile.messages` and setting
-   * `message.file` to the current filepath.
+   * Create a warning message associated with the file.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * Its `fatal` is set to `false` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {VFileMessage}
@@ -166,20 +191,18 @@ *   Message.
     reason: string | Error | VFileMessage,
-    place?:
-      | import('unist').Node<import('unist').Data>
-      | import('unist').Position
-      | import('unist').Point
-      | NodeLike
-      | undefined,
-    origin?: string | undefined
+    place?: Node | NodeLike | Position | Point | null | undefined,
+    origin?: string | null | undefined
   ): VFileMessage
   /**
-   * Like `VFile#message()`, but associates an informational message where
-   * `fatal` is set to `null`.
+   * Create an info message associated with the file.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * Its `fatal` is set to `null` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {VFileMessage}
@@ -190,34 +213,29 @@ *   Message.
     reason: string | Error | VFileMessage,
-    place?:
-      | import('unist').Node<import('unist').Data>
-      | import('unist').Position
-      | import('unist').Point
-      | NodeLike
-      | undefined,
-    origin?: string | undefined
+    place?: Node | NodeLike | Position | Point | null | undefined,
+    origin?: string | null | undefined
   ): VFileMessage
   /**
-   * Like `VFile#message()`, but associates a fatal message where `fatal` is
-   * set to `true`, and then immediately throws it.
+   * Create a fatal error associated with the file.
    *
+   * Its `fatal` is set to `true` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
    * > 👉 **Note**: a fatal error means that a file is no longer processable.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {never}
    *   Message.
+   * @throws {VFileMessage}
+   *   Message.
    */
   fail(
     reason: string | Error | VFileMessage,
-    place?:
-      | import('unist').Node<import('unist').Data>
-      | import('unist').Position
-      | import('unist').Point
-      | NodeLike
-      | undefined,
-    origin?: string | undefined
+    place?: Node | NodeLike | Position | Point | null | undefined,
+    origin?: string | null | undefined
   ): never
@@ -228,2 +246,5 @@ }
 export type Point = import('unist').Point
+export type URL = import('./minurl.shared.js').URL
+export type Data = import('../index.js').Data
+export type Value = import('../index.js').Value
 export type NodeLike = Record<string, unknown> & {
@@ -233,8 +254,6 @@ type: string
 }
-export type URL = import('./minurl.shared.js').URL
-export type Data = import('../index.js').Data
-export type Value = import('../index.js').Value
 /**
  * Encodings supported by the buffer class.
- * This is a copy of the typing from Node, copied to prevent Node globals from
+ *
+ * This is a copy of the types from Node, copied to prevent Node globals from
  * being needed.
@@ -258,30 +277,84 @@ * Copied from: <https://github.com/DefinitelyTyped/DefinitelyTyped/blob/90a4ec8/types/node/buffer.d.ts#L170>
  */
-export type Compatible = Value | Options | VFile | URL
+export type Compatible = Options | URL | Value | VFile
+/**
+ * Set multiple values.
+ */
 export type VFileCoreOptions = {
-  value?: import('../index.js').Value | undefined
-  cwd?: string | undefined
-  history?: string[] | undefined
-  path?: string | import('./minurl.shared.js').URL | undefined
-  basename?: string | undefined
-  stem?: string | undefined
-  extname?: string | undefined
-  dirname?: string | undefined
-  data?: import('../index.js').Data | undefined
+  /**
+   * Set `value`.
+   */
+  value?: Value | null | undefined
+  /**
+   * Set `cwd`.
+   */
+  cwd?: string | null | undefined
+  /**
+   * Set `history`.
+   */
+  history?: Array<string> | null | undefined
+  /**
+   * Set `path`.
+   */
+  path?: URL | string | null | undefined
+  /**
+   * Set `basename`.
+   */
+  basename?: string | null | undefined
+  /**
+   * Set `stem`.
+   */
+  stem?: string | null | undefined
+  /**
+   * Set `extname`.
+   */
+  extname?: string | null | undefined
+  /**
+   * Set `dirname`.
+   */
+  dirname?: string | null | undefined
+  /**
+   * Set `data`.
+   */
+  data?: Data | null | undefined
 }
 /**
- * Raw source map, see:
+ * Raw source map.
+ *
+ * See:
  * <https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23>.
  */
 export type Map = {
+  /**
+   *  Which version of the source map spec this map is following.
+   */
   version: number
+  /**
+   *  An array of URLs to the original source files.
+   */
   sources: Array<string>
+  /**
+   *  An array of identifiers which can be referenced by individual mappings.
+   */
   names: Array<string>
+  /**
+   * The URL root from which all sources are relative.
+   */
   sourceRoot?: string | undefined
+  /**
+   * An array of contents of the original source files.
+   */
   sourcesContent?: Array<string> | undefined
+  /**
+   *  A string of base64 VLQs which contain the actual mappings.
+   */
   mappings: string
+  /**
+   *  The generated file this source map is associated with.
+   */
   file: string
 }
 /**
- * Configuration: a bunch of keys that will be shallow copied over to the new
- * file.
+ * Configuration.
+ *
+ * A bunch of keys that will be shallow copied over to the new file.
  */
@@ -291,7 +364,13 @@ export type Options = {
 } & VFileCoreOptions
+/**
+ * Configuration for reporters.
+ */
 export type ReporterSettings = Record<string, unknown>
-export type Reporter = <T = ReporterSettings>(
+/**
+ * Type for a reporter.
+ */
+export type Reporter<Settings extends ReporterSettings> = (
   files: Array<VFile>,
-  options: T
+  options: Settings
 ) => string
 import {VFileMessage} from 'vfile-message'

lib/index.js

@@ -5,47 +5,84 @@ /**
  * @typedef {import('unist').Point} Point
- * @typedef {Record<string, unknown> & {type: string, position?: Position|undefined}} NodeLike
  * @typedef {import('./minurl.shared.js').URL} URL
  * @typedef {import('../index.js').Data} Data
  * @typedef {import('../index.js').Value} Value
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {type: string, position?: Position | undefined}} NodeLike
  *
- * @typedef {'ascii'|'utf8'|'utf-8'|'utf16le'|'ucs2'|'ucs-2'|'base64'|'base64url'|'latin1'|'binary'|'hex'} BufferEncoding
+ * @typedef {'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex'} BufferEncoding
  *   Encodings supported by the buffer class.
- *   This is a copy of the typing from Node, copied to prevent Node globals from
+ *
+ *   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/90a4ec8/types/node/buffer.d.ts#L170>
  *
- * @typedef {Value|Options|VFile|URL} Compatible
+ * @typedef {Options | URL | Value | VFile} Compatible
  *   Things that can be passed to the constructor.
  *
  * @typedef VFileCoreOptions
- * @property {Value} [value]
- * @property {string} [cwd]
- * @property {Array<string>} [history]
- * @property {string|URL} [path]
- * @property {string} [basename]
- * @property {string} [stem]
- * @property {string} [extname]
- * @property {string} [dirname]
- * @property {Data} [data]
+ *   Set multiple values.
+ * @property {Value | null | undefined} [value]
+ *   Set `value`.
+ * @property {string | null | undefined} [cwd]
+ *   Set `cwd`.
+ * @property {Array<string> | null | undefined} [history]
+ *   Set `history`.
+ * @property {URL | string | null | undefined} [path]
+ *   Set `path`.
+ * @property {string | null | undefined} [basename]
+ *   Set `basename`.
+ * @property {string | null | undefined} [stem]
+ *   Set `stem`.
+ * @property {string | null | undefined} [extname]
+ *   Set `extname`.
+ * @property {string | null | undefined} [dirname]
+ *   Set `dirname`.
+ * @property {Data | null | undefined} [data]
+ *   Set `data`.
  *
  * @typedef Map
- *   Raw source map, see:
+ *   Raw source map.
+ *
+ *   See:
  *   <https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23>.
  * @property {number} version
+ *   Which version of the source map spec this map is following.
  * @property {Array<string>} sources
+ *   An array of URLs to the original source files.
  * @property {Array<string>} names
- * @property {string|undefined} [sourceRoot]
- * @property {Array<string>|undefined} [sourcesContent]
+ *   An array of identifiers which can be referenced by individual mappings.
+ * @property {string | undefined} [sourceRoot]
+ *   The URL root from which all sources are relative.
+ * @property {Array<string> | undefined} [sourcesContent]
+ *   An array of contents of the original source files.
  * @property {string} mappings
+ *   A string of base64 VLQs which contain the actual mappings.
  * @property {string} file
+ *   The generated file this source map is associated with.
  *
  * @typedef {{[key: string]: unknown} & VFileCoreOptions} Options
- *   Configuration: a bunch of keys that will be shallow copied over to the new
- *   file.
+ *   Configuration.
  *
+ *   A bunch of keys that will be shallow copied over to the new file.
+ *
  * @typedef {Record<string, unknown>} ReporterSettings
- * @typedef {<T = ReporterSettings>(files: Array<VFile>, options: T) => string} Reporter
+ *   Configuration for reporters.
  */
 
-import buffer from 'is-buffer'
+/**
+ * @template {ReporterSettings} Settings
+ *   Options type.
+ * @callback Reporter
+ *   Type for a reporter.
+ * @param {Array<VFile>} files
+ *   Files to report.
+ * @param {Settings} options
+ *   Configuration.
+ * @returns {string}
+ *   Report.
+ */
+
+import bufferLike from 'is-buffer'
 import {VFileMessage} from 'vfile-message'
@@ -56,5 +93,9 @@ import {path} from './minpath.js'
 
-// Order of setting (least specific to most), we need this because otherwise
-// `{stem: 'a', path: '~/b.js'}` would throw, as a path is needed before a
-// stem can be set.
+/**
+ * Order of setting (least specific to most), we need this because otherwise
+ * `{stem: 'a', path: '~/b.js'}` would throw, as a path is needed before a
+ * stem can be set.
+ *
+ * @type {Array<'basename' | 'dirname' | 'extname' | 'history' | 'path' | 'stem'>}
+ */
 const order = ['history', 'path', 'basename', 'stem', 'extname', 'dirname']
@@ -66,7 +107,9 @@
    *
-   * If `options` is `string` or `Buffer`, it’s treated as `{value: options}`.
-   * If `options` is a `URL`, it’s treated as `{path: options}`.
-   * If `options` is a `VFile`, shallow copies its data over to the new file.
-   * All fields in `options` are set on the newly created `VFile`.
+   * `options` is treated as:
    *
+   * *   `string` or `Buffer` — `{value: options}`
+   * *   `URL` — `{path: options}`
+   * *   `VFile` — shallow copies its data over to the new file
+   * *   `object` — all fields are shallow copied over to the new file
+   *
    * Path related fields are set in the following order (least specific to
@@ -76,9 +119,12 @@ * most specific): `history`, `path`, `basename`, `stem`, `extname`,
    *
-   * It’s not possible to set either `dirname` or `extname` without setting
-   * either `history`, `path`, `basename`, or `stem` as well.
+   * You cannot set `dirname` or `extname` without setting either `history`,
+   * `path`, `basename`, or `stem` too.
    *
-   * @param {Compatible} [value]
+   * @param {Compatible | null | undefined} [value]
+   *   File value.
+   * @returns
+   *   New instance.
    */
   constructor(value) {
-    /** @type {Options} */
+    /** @type {Options | VFile} */
     let options
@@ -89,3 +135,2 @@
     } else if (typeof value === 'string' || buffer(value)) {
-      // @ts-expect-error Looks like a buffer.
       options = {value}
@@ -95,3 +140,2 @@ } else if (isUrl(value)) {
     } else {
-      // @ts-expect-error Looks like file or options.
       options = value
@@ -102,4 +146,6 @@ }
      * Place to store custom information (default: `{}`).
+     *
      * It’s OK to store custom data directly on the file but moving it to
      * `data` is recommended.
+     *
      * @type {Data}
@@ -111,2 +157,3 @@ */
      * List of messages associated with the file.
+     *
      * @type {Array<VFileMessage>}
@@ -118,3 +165,5 @@ */
      * List of filepaths the file moved between.
+     *
      * The first is the original path and the last is the current path.
+     *
      * @type {Array<string>}
@@ -126,2 +175,3 @@ */
      * Base of `path` (default: `process.cwd()` or `'/'` in browsers).
+     *
      * @type {string}
@@ -134,2 +184,3 @@ */
      * Raw value.
+     *
      * @type {Value}
@@ -144,3 +195,5 @@ */
      * Whether a file was saved to disk.
+     *
      * This is used by vfile reporters.
+     *
      * @type {boolean}
@@ -151,6 +204,7 @@ */
     /**
-     * Sometimes files have a non-string, compiled, representation.
-     * This can be stored in the `result` field.
+     * Custom, non-string, compiled, representation.
+     *
+     * This is used by unified to store non-string results.
      * One example is when turning markdown into React nodes.
-     * This is used by unified to store non-string results.
+     *
      * @type {unknown}
@@ -161,7 +215,8 @@ */
     /**
-     * Sometimes files have a source map associated with them.
-     * This can be stored in the `map` field.
-     * This should be a `Map` type, which is equivalent to the `RawSourceMap`
-     * type from the `source-map` module.
-     * @type {Map|undefined}
+     * Source map.
+     *
+     * This type is equivalent to the `RawSourceMap` type from the `source-map`
+     * module.
+     *
+     * @type {Map | null | undefined}
      */
@@ -179,4 +234,8 @@ this.map
       // `vfile`s too.
-      if (prop in options && options[prop] !== undefined) {
-        // @ts-expect-error: TS is confused by the different types for `history`.
+      if (
+        prop in options &&
+        options[prop] !== undefined &&
+        options[prop] !== null
+      ) {
+        // @ts-expect-error: TS doesn’t understand basic reality.
         this[prop] = prop === 'history' ? [...options[prop]] : options[prop]
@@ -192,3 +251,6 @@ }
       // @ts-expect-error: fine to set other things.
-      if (!order.includes(prop)) this[prop] = options[prop]
+      if (!order.includes(prop)) {
+        // @ts-expect-error: fine to set other things.
+        this[prop] = options[prop]
+      }
     }
@@ -199,2 +261,3 @@ }
    * Get the full path (example: `'~/index.min.js'`).
+   *
    * @returns {string}
@@ -208,6 +271,8 @@ */
    * Set the full path (example: `'~/index.min.js'`).
+   *
    * Cannot be nullified.
    * You can set a file URL (a `URL` object with a `file:` protocol) which will
    * be turned into a path with `url.fileURLToPath`.
-   * @param {string|URL} path
+   *
+   * @param {string | URL} path
    */
@@ -235,2 +300,3 @@ set path(path) {
    * Set the parent path (example: `'~'`).
+   *
    * Cannot be set if there’s no `path` yet.
@@ -252,2 +318,3 @@ */
    * Set basename (including extname) (`'index.min.js'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -272,2 +339,3 @@ * on windows).
    * Set the extname (including dot) (example: `'.js'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -305,2 +373,3 @@ * on windows).
    * Set the stem (basename w/o extname) (example: `'index.min'`).
+   *
    * Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
@@ -319,5 +388,5 @@ * on windows).
    *
-   * @param {BufferEncoding} [encoding='utf8']
-   *   When `value` is a `Buffer`, `encoding` is a character encoding to
-   *   understand it as (default: `'utf8'`).
+   * @param {BufferEncoding | null | undefined} [encoding='utf8']
+   *   Character encoding to understand `value` as when it’s a `Buffer`
+   *   (default: `'utf8'`).
    * @returns {string}
@@ -327,16 +396,18 @@ *   Serialized file.
   toString(encoding) {
-    return (this.value || '').toString(encoding)
+    return (this.value || '').toString(encoding || undefined)
   }
 
   /**
-   * Constructs a new `VFileMessage`, where `fatal` is set to `false`, and
-   * associates it with the file by adding it to `vfile.messages` and setting
-   * `message.file` to the current filepath.
+   * Create a warning message associated with the file.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * Its `fatal` is set to `false` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {VFileMessage}
@@ -361,11 +432,14 @@ *   Message.
   /**
-   * Like `VFile#message()`, but associates an informational message where
-   * `fatal` is set to `null`.
+   * Create an info message associated with the file.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * Its `fatal` is set to `null` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {VFileMessage}
@@ -383,15 +457,20 @@ *   Message.
   /**
-   * Like `VFile#message()`, but associates a fatal message where `fatal` is
-   * set to `true`, and then immediately throws it.
+   * Create a fatal error associated with the file.
    *
+   * Its `fatal` is set to `true` and `file` is set to the current file path.
+   * Its added to `file.messages`.
+   *
    * > 👉 **Note**: a fatal error means that a file is no longer processable.
    *
-   * @param {string|Error|VFileMessage} reason
-   *   Human readable reason for the message, uses the stack and message of the error if given.
-   * @param {Node|NodeLike|Position|Point} [place]
-   *   Place where the message occurred in the file.
-   * @param {string} [origin]
-   *   Computer readable reason for the message
+   * @param {string | Error | VFileMessage} reason
+   *   Reason for message, uses the stack and message of the error if given.
+   * @param {Node | NodeLike | Position | Point | null | undefined} [place]
+   *   Place in file where the message occurred.
+   * @param {string | null | undefined} [origin]
+   *   Place in code where the message originates (example:
+   *   `'my-package:my-rule'` or `'my-rule'`).
    * @returns {never}
    *   Message.
+   * @throws {VFileMessage}
+   *   Message.
    */
@@ -410,5 +489,8 @@ fail(reason, place, origin) {
  *
- * @param {string|undefined} part
+ * @param {string | null | undefined} part
+ *   File path part.
  * @param {string} name
+ *   Part name.
  * @returns {void}
+ *   Nothing.
  */
@@ -426,5 +508,8 @@ function assertPart(part, name) {
  *
- * @param {string|undefined} part
+ * @param {string | undefined} part
+ *   Thing.
  * @param {string} name
+ *   Part name.
  * @returns {asserts part is string}
+ *   Nothing.
  */
@@ -440,5 +525,8 @@ function assertNonEmpty(part, name) {
  *
- * @param {string|undefined} path
+ * @param {string | undefined} path
+ *   Path.
  * @param {string} name
+ *   Dependency name.
  * @returns {asserts path is string}
+ *   Nothing.
  */
@@ -450,1 +538,13 @@ function assertPath(path, name) {
 }
+
+/**
+ * Assert `value` is a buffer.
+ *
+ * @param {unknown} value
+ *   thing.
+ * @returns {value is Buffer}
+ *   Whether `value` is a Node.js buffer.
+ */
+function buffer(value) {
+  return bufferLike(value)
+}

lib/minpath.browser.d.ts

@@ -9,22 +9,39 @@ export namespace path {
 /**
+ * Get the basename from a path.
+ *
  * @param {string} path
- * @param {string} [ext]
+ *   File path.
+ * @param {string | undefined} [ext]
+ *   Extension to strip.
  * @returns {string}
+ *   Stem or basename.
  */
 declare function basename(path: string, ext?: string | undefined): string
 /**
+ * Get the dirname from a path.
+ *
  * @param {string} path
+ *   File path.
  * @returns {string}
+ *   File path.
  */
 declare function dirname(path: string): string
 /**
+ * Get an extname from a path.
+ *
  * @param {string} path
+ *   File path.
  * @returns {string}
+ *   Extname.
  */
 declare function extname(path: string): string
 /**
+ * Join segments from a path.
+ *
  * @param {Array<string>} segments
+ *   Path segments.
  * @returns {string}
+ *   File path.
  */
 declare function join(...segments: Array<string>): string
 export {}

lib/minpath.browser.js

@@ -57,5 +57,10 @@ // A derivative work based on:
 /**
+ * Get the basename from a path.
+ *
  * @param {string} path
- * @param {string} [ext]
+ *   File path.
+ * @param {string | undefined} [ext]
+ *   Extension to strip.
  * @returns {string}
+ *   Stem or basename.
  */
@@ -71,3 +76,3 @@ function basename(path, ext) {
   let index = path.length
-  /** @type {boolean|undefined} */
+  /** @type {boolean | undefined} */
   let seenNonSlash
@@ -146,4 +151,8 @@
 /**
+ * Get the dirname from a path.
+ *
  * @param {string} path
+ *   File path.
  * @returns {string}
+ *   File path.
  */
@@ -159,3 +168,3 @@ function dirname(path) {
   let index = path.length
-  /** @type {boolean|undefined} */
+  /** @type {boolean | undefined} */
   let unmatchedSlash
@@ -186,4 +195,8 @@
 /**
+ * Get an extname from a path.
+ *
  * @param {string} path
+ *   File path.
  * @returns {string}
+ *   Extname.
  */
@@ -201,3 +214,3 @@ function extname(path) {
   let preDotState = 0
-  /** @type {boolean|undefined} */
+  /** @type {boolean | undefined} */
   let unmatchedSlash
@@ -255,8 +268,12 @@
 /**
+ * Join segments from a path.
+ *
  * @param {Array<string>} segments
+ *   Path segments.
  * @returns {string}
+ *   File path.
  */
 function join(...segments) {
   let index = -1
-  /** @type {string|undefined} */
+  /** @type {string | undefined} */
   let joined
@@ -277,8 +294,11 @@
 /**
- * Note: `normalize` is not exposed as `path.normalize`, so some code is
- * manually removed from it.
+ * Normalize a basic file path.
  *
  * @param {string} path
+ *   File path.
  * @returns {string}
+ *   File path.
  */
+// Note: `normalize` is not exposed as `path.normalize`, so some code is
+// manually removed from it.
 function normalize(path) {
@@ -307,4 +327,7 @@ assertPath(path)
  * @param {string} path
+ *   File path.
  * @param {boolean} allowAboveRoot
+ *   Whether `..` can move above root.
  * @returns {string}
+ *   File path.
  */
@@ -317,3 +340,3 @@ function normalizeString(path, allowAboveRoot) {
   let index = -1
-  /** @type {number|undefined} */
+  /** @type {number | undefined} */
   let code
@@ -394,3 +417,8 @@ /** @type {number} */
 /**
+ * Make sure `path` is a string.
+ *
  * @param {string} path
+ *   File path.
+ * @returns {asserts path is string}
+ *   Nothing.
  */
@@ -397,0 +425,0 @@ function assertPath(path) {

lib/minurl.browser.d.ts

 /// <reference lib="dom" />
 /**
- * @param {string|URL} path
+ * @param {string | URL} path
+ *   File URL.
+ * @returns {string}
+ *   File URL.
  */
 export function urlToPath(path: string | URL): string
 export {isUrl} from './minurl.shared.js'

lib/minurl.browser.js

@@ -8,3 +8,6 @@ /// <reference lib="dom" />
 /**
- * @param {string|URL} path
+ * @param {string | URL} path
+ *   File URL.
+ * @returns {string}
+ *   File URL.
  */
@@ -36,3 +39,8 @@ export function urlToPath(path) {
 /**
+ * Get a path from a POSIX URL.
+ *
  * @param {URL} url
+ *   URL.
+ * @returns {string}
+ *   File path.
  */
@@ -39,0 +47,0 @@ function getPathFromURLPosix(url) {

lib/minurl.shared.d.ts

@@ -19,6 +19,10 @@ /**
 /**
- * @param {unknown} fileURLOrPath
- * @returns {fileURLOrPath is URL}
+ * Check if `fileUrlOrPath` looks like a URL.
+ *
+ * @param {unknown} fileUrlOrPath
+ *   File path or URL.
+ * @returns {fileUrlOrPath is URL}
+ *   Whether it’s a URL.
  */
-export function isUrl(fileURLOrPath: unknown): fileURLOrPath is URL
+export function isUrl(fileUrlOrPath: unknown): fileUrlOrPath is URL
 export type URL = {
@@ -25,0 +29,0 @@ hash: string

lib/minurl.shared.js

@@ -20,15 +20,19 @@ /**
 /**
- * @param {unknown} fileURLOrPath
- * @returns {fileURLOrPath is URL}
+ * Check if `fileUrlOrPath` looks like a URL.
+ *
+ * @param {unknown} fileUrlOrPath
+ *   File path or URL.
+ * @returns {fileUrlOrPath is URL}
+ *   Whether it’s a URL.
  */
 // From: <https://github.com/nodejs/node/blob/fcf8ba4/lib/internal/url.js#L1501>
-export function isUrl(fileURLOrPath) {
+export function isUrl(fileUrlOrPath) {
   return (
-    fileURLOrPath !== null &&
-    typeof fileURLOrPath === 'object' &&
+    fileUrlOrPath !== null &&
+    typeof fileUrlOrPath === 'object' &&
     // @ts-expect-error: indexable.
-    fileURLOrPath.href &&
+    fileUrlOrPath.href &&
     // @ts-expect-error: indexable.
-    fileURLOrPath.origin
+    fileUrlOrPath.origin
   )
 }

package.json

 {
   "name": "vfile",
-  "version": "5.3.6",
+  "version": "5.3.7",
   "description": "Virtual file format for text processing",
@@ -5,0 +5,0 @@ "license": "MIT",

readme.md

@@ -39,3 +39,12 @@ <h1>
     *   [`VFile#fail(reason[, position][, origin])`](#vfilefailreason-position-origin)
-    *   [Well-known fields](#well-known-fields)
+    *   [`BufferEncoding`](#bufferencoding)
+    *   [`Compatible`](#compatible)
+    *   [`Data`](#data)
+    *   [`DataMap`](#datamap)
+    *   [`Map`](#map)
+    *   [`Options`](#options)
+    *   [`Reporter`](#reporter)
+    *   [`ReporterSettings`](#reportersettings)
+    *   [`Value`](#value)
+    *   [Well-known](#well-known)
 *   [List of utilities](#list-of-utilities)
@@ -83,3 +92,3 @@ *   [Reporters](#reporters)
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14, 16.0+), install with [npm][]:
+In Node.js (version 14.14 and 16.0+), install with [npm][]:
 
@@ -152,3 +161,3 @@ ```sh
 
-This package exports the identifier `VFile`.
+This package exports the identifier [`VFile`][api-vfile].
 There is no default export.
@@ -160,14 +169,25 @@
 
-*   if `options` is `string` or `Buffer`, it’s treated as `{value: options}`
-*   if `options` is a `URL`, it’s treated as `{path: options}`
-*   if `options` is a `VFile`, shallow copies its data over to the new file
+`options` is treated as:
 
-All fields in `options` are set on the newly created `VFile`.
+*   `string` or [`Buffer`][buffer] — `{value: options}`
+*   `URL` — `{path: options}`
+*   `VFile` — shallow copies its data over to the new file
+*   `object` — all fields are shallow copied over to the new file
 
-Path related fields are set in the following order (least specific to most
-specific): `history`, `path`, `basename`, `stem`, `extname`, `dirname`.
+Path related fields 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.
+You cannot set `dirname` or `extname` without setting either `history`,
+`path`, `basename`, or `stem` too.
 
+###### Parameters
+
+*   `options` ([`Compatible`][api-compatible], optional)
+    — file value
+
+###### Returns
+
+New instance (`VFile`).
+
 ###### Example
@@ -186,3 +206,3 @@
 
-Raw value (`Buffer`, `string`, `null`).
+Raw value ([`Buffer`][buffer], `string`, `null`).
 
@@ -196,2 +216,3 @@ ### `file.cwd`
 Get or set the full path (`string?`, example: `'~/index.min.js'`).
+
 Cannot be nullified.
@@ -204,2 +225,3 @@ You can set a file URL (a `URL` object with a `file:` protocol) which will be
 Get or set the parent path (`string?`, example: `'~'`).
+
 Cannot be set if there’s no `path` yet.
@@ -210,2 +232,3 @@
 Get or set the basename (including extname) (`string?`, example: `'index.min.js'`).
+
 Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
@@ -218,2 +241,3 @@ windows).
 Get or set the extname (including dot) (`string?`, example: `'.js'`).
+
 Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
@@ -226,2 +250,3 @@ windows).
 Get or set the stem (basename w/o extname) (`string?`, example: `'index.min'`).
+
 Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'` on
@@ -234,2 +259,3 @@ windows).
 List of filepaths the file moved between (`Array<string>`).
+
 The first is the original path and the last is the current path.
@@ -244,2 +270,3 @@
 Place to store custom information (`Record<string, unknown>`, default: `{}`).
+
 It’s OK to store custom data directly on the file but moving it to `data` is
@@ -251,6 +278,9 @@ recommended.
 Serialize the file.
-When `value` is a [`Buffer`][buffer], `encoding` is a
-[character encoding][encoding] to understand it as (`string`, default:
-`'utf8'`).
 
+###### Parameters
+
+*   `encoding` ([`BufferEncoding`][api-buffer-encoding], default: `'utf8'`)
+    — character encoding to understand `value` as when it’s a
+    [`Buffer`][buffer]
+
 ###### Returns
@@ -262,15 +292,15 @@
 
-Constructs a new [`VFileMessage`][vmessage], where `fatal` is set to `false`,
-and associates it with the file by adding it to [`file.messages`][messages]
-and setting `message.file` to the current filepath.
+Create a warning message associated with the file.
 
+Its `fatal` is set to `false` and `file` is set to the current file path.
+Its added to `file.messages`.
+
 ###### Parameters
 
 *   `reason` (`string` or `Error`)
-    — human readable reason for the message, uses the stack and message of the
-    error if given
+    — reason for message, uses the stack and message of the error if given
 *   `place` (`Node`, `Position`, or `Point`, optional)
-    — place where the message occurred in the file
-*   `origin` (`string?`, optional, example: `'my-npm-package:my-rule-name'`)
-    — computer readable reason for the message
+    — place in file where the message occurred
+*   `origin` (`string?`, optional, example: `'my-package:my-rule'` or `'my-rule'`)
+    — place in code where the message originates
 
@@ -283,5 +313,16 @@ ###### Returns
 
-Like [`VFile#message()`][message], but associates an informational message
-where `fatal` is set to `null`.
+Create an info message associated with the file.
 
+Its `fatal` is set to `null` and `file` is set to the current file path.
+Its added to `file.messages`.
+
+###### Parameters
+
+*   `reason` (`string` or `Error`)
+    — reason for message, uses the stack and message of the error if given
+*   `place` (`Node`, `Position`, or `Point`, optional)
+    — place in file where the message occurred
+*   `origin` (`string?`, optional, example: `'my-package:my-rule'` or `'my-rule'`)
+    — place in code where the message originates
+
 ###### Returns
@@ -293,7 +334,22 @@
 
-Like [`VFile#message()`][message], but associates a fatal message where `fatal`
-is set to `true`, and then immediately throws it.
+Create a fatal error associated with the file.
 
+Its `fatal` is set to `true` and `file` is set to the current file path.
+Its added to `file.messages`.
+
 > 👉 **Note**: a fatal error means that a file is no longer processable.
 
+###### Parameters
+
+*   `reason` (`string` or `Error`)
+    — reason for message, uses the stack and message of the error if given
+*   `place` (`Node`, `Position`, or `Point`, optional)
+    — place in file where the message occurred
+*   `origin` (`string?`, optional, example: `'my-package:my-rule'` or `'my-rule'`)
+    — place in code where the message originates
+
+###### Returns
+
+Nothing (`never`).
+
 ###### Throws
@@ -303,4 +359,156 @@
 
-### Well-known fields
+### `BufferEncoding`
 
+[Encodings][encoding] supported by the [buffer][] class (TypeScript type).
+
+This is a copy of the types from Node.
+
+###### Type
+
+```ts
+type BufferEncoding =
+  | 'ascii'
+  | 'utf8'
+  | 'utf-8'
+  | 'utf16le'
+  | 'ucs2'
+  | 'ucs-2'
+  | 'base64'
+  | 'base64url'
+  | 'latin1'
+  | 'binary'
+  | 'hex'
+```
+
+### `Compatible`
+
+Things that can be passed to the constructor (TypeScript type).
+
+###### Type
+
+```ts
+type Compatible = Options | URL | Value | VFile
+```
+
+### `Data`
+
+Custom information (TypeScript type).
+
+Known attributes can be added to [`DataMap`][api-data-map].
+
+###### Type
+
+```ts
+type Data = Record<string, unknown> & Partial<DataMap>
+```
+
+### `DataMap`
+
+This map registers the type of the `data` key of a `VFile` (TypeScript type).
+
+This type can be augmented to register custom `data` types.
+
+###### Type
+
+```ts
+interface DataMap {}
+```
+
+###### Example
+
+```ts
+declare module 'vfile' {
+  interface DataMap {
+    // `file.data.name` is typed as `string`
+    name: string
+  }
+}
+```
+
+### `Map`
+
+Raw source map (TypeScript type).
+
+See [`source-map`][source-map].
+
+###### Fields
+
+*   `version` (`number`)
+    — which version of the source map spec this map is following
+*   `sources` (`Array<string>`)
+    — an array of URLs to the original source files
+*   `names` (`Array<string>`)
+    — an array of identifiers which can be referenced by individual mappings
+*   `sourceRoot` (`string`, optional)
+    — the URL root from which all sources are relative
+*   `sourcesContent` (`Array<string>`, optional)
+    — an array of contents of the original source files
+*   `mappings` (`string`)
+    — a string of base64 VLQs which contain the actual mappings
+*   `file` (`string`)
+    — the generated file this source map is associated with
+
+### `Options`
+
+An object with arbitrary fields and the following known fields (TypeScript
+type).
+
+###### Fields
+
+*   `value` ([`Value`][api-value], optional)
+    — set `value`
+*   `cwd` (`string`, optional)
+    — set `cwd`
+*   `history` (`Array<string>`, optional)
+    — set `history`
+*   `path` (`URL | string`, optional)
+    — set `path`
+*   `basename` (`string`, optional)
+    — set `basename`
+*   `stem` (`string`, optional)
+    — set `stem`
+*   `extname` (`string`, optional)
+    — set `extname`
+*   `dirname` (`string`, optional)
+    — set `dirname`
+*   `data` ([`Data`][api-data], optional)
+    — set `data`
+
+### `Reporter`
+
+Type for a reporter (TypeScript type).
+
+###### Type
+
+```ts
+type Reporter<Settings extends ReporterSettings> = (
+  files: Array<VFile>,
+  options: Settings
+) => string
+```
+
+### `ReporterSettings`
+
+Configuration for reporters (TypeScript type).
+
+###### Type
+
+```ts
+type ReporterSettings = Record<string, unknown>
+```
+
+### `Value`
+
+Contents of the file (TypeScript type).
+
+Can either be text or a `Buffer` structure.
+
+###### Type
+
+```ts
+type Value = string | Buffer
+```
+
+### Well-known
+
 The following fields are considered “non-standard”, but they are allowed, and
@@ -310,11 +518,9 @@ some utilities use them:
 *   `stored` (`boolean`)
-    — whether a file was saved to disk, used by reporters
+    — whether a file was saved to disk; this is used by vfile reporters
 *   `result` (`unknown`)
-    — sometimes files have a non-string, compiled, representation, which can be
-    stored in the `result` field.
-    One example is when turning markdown into React nodes.
-    unified uses this field to store non-string results
-*   `map` (`Map`)
-    — sometimes files have a source map associated with them, this should be a
-    `Map` type, which is equivalent to the `RawSourceMap` type from the
+    — custom, non-string, compiled, representation; this is used by unified to
+    store non-string results; one example is when turning markdown into React
+    nodes
+*   `map` ([`Map`][api-map])
+    — source map; this type is equivalent to the `RawSourceMap` type from the
     `source-map` module
@@ -324,3 +530,3 @@
 [them in a similar section of
-`vfile-message`](https://github.com/vfile/vfile-message#well-known-fields).
+`vfile-message`](https://github.com/vfile/vfile-message#well-known).
 
@@ -388,36 +594,13 @@ <a name="utilities"></a>
 This package is fully typed with [TypeScript][].
-It exports the following additional types:
+It exports the additional types
+[`BufferEncoding`][api-buffer-encoding],
+[`Compatible`][api-compatible],
+[`Data`][api-data],
+[`DataMap`][api-data-map],
+[`Map`][api-map],
+[`Options`][api-options],
+[`Reporter`][api-reporter],
+[`ReporterSettings`][api-reporter-settings], and
+[`Value`][api-value].
 
-*   `BufferEncoding`
-    — thing that can be given as `x` in `file.toString(x)`
-*   `Compatible`
-    — everything that can be passed as `x` in `new VFile(x)`
-*   `Data`
-    — thing at `file.data`
-*   `DataMap`
-    — interface you can add things to, to type your extensions of `file.data`
-*   `Map`
-    — source map interface as supported at `file.map`
-*   `Options`
-    — the fields that can be passed as options to `new VFile(x)`
-*   `Reporter`
-    — a reporter
-*   `ReporterSettings`
-    — the fields that can be passed to a reporter
-*   `Value`
-    — valid value
-*   `VFile`
-    — class of `file` itself
-
-`DataMap` can be augmented to include your extensions to it:
-
-```ts
-declare module 'vfile' {
-  interface DataMap {
-    // `file.data.name` is typed as `string`.
-    name: string
-  }
-}
-```
-
 ## Compatibility
@@ -427,3 +610,3 @@
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+As of now, that is Node.js 14.14+ and 16.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
@@ -600,4 +783,26 @@
 
+[source-map]: https://github.com/mozilla/source-map/blob/58819f0/source-map.d.ts#L15-L23
+
 [file-url-to-path]: https://nodejs.org/api/url.html#url_url_fileurltopath_url
 
 [governance]: https://github.com/unifiedjs/collective
+
+[api-vfile]: #vfileoptions
+
+[api-buffer-encoding]: #bufferencoding
+
+[api-compatible]: #compatible
+
+[api-data]: #data
+
+[api-data-map]: #datamap
+
+[api-map]: #map
+
+[api-options]: #options
+
+[api-reporter]: #reporter
+
+[api-reporter-settings]: #reportersettings
+
+[api-value]: #value

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

69047

increased by12.97%

Lines of code

1476

increased by19.51%

Number of lines in readme file

787

increased by35.22%

No dependency changes