unified - npm Package Compare versions

Comparing version 8.1.0 to 8.2.0

index.js

@@ -406,2 +406,3 @@ 'use strict'
     typeof value === 'function' &&
+    value.prototype &&
     // A function with keys in its prototype is probably a constructor.
@@ -408,0 +409,0 @@ // Classes’ prototype methods are not enumerable, so we check if some value

package.json

 {
   "name": "unified",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Interface for processing text using syntax trees",
@@ -5,0 +5,0 @@ "license": "MIT",

types/index.d.ts

@@ -8,7 +8,14 @@ // TypeScript Version: 3.0
 declare namespace unified {
-  interface Processor {
+  /**
+   * Processor allows plugins, parsers, and compilers to be chained together to transform content.
+   *
+   * @typeParam P Processor settings. Useful when packaging unified with a preset parser and compiler.
+   */
+  interface Processor<P = Settings> {
     /**
+     * Clone current processor
+     *
      * @returns New unfrozen processor which is configured to function the same as its ancestor. But when the descendant processor is configured in the future it does not affect the ancestral processor.
      */
-    (): Processor
+    (): Processor<P>
 
@@ -19,33 +26,45 @@ /**
      * @param plugin unified plugin
-     * @param options Configuration for plugin
-     * @param extraOptions Additional configuration for plugin
+     * @param settings Configuration for plugin
+     * @param extraSettings Additional configuration for plugin
+     * @typeParam S Plugin settings
+     * @typeParam S2 Extra plugin settings
      * @returns The processor on which use is invoked
      */
-    use<T = Settings, S = undefined>(
-      plugin: Plugin<T, S>,
-      options?: T,
-      extraOptions?: S
-    ): Processor
+    use<S = Settings, S2 = undefined>(
+      plugin: Plugin<S, S2, P>,
+      settings?: S,
+      extraSettings?: S2
+    ): Processor<P>
 
     /**
-     * @param preset `Object` with an optional plugins (set to list), and/or an optional settings object
+     * Configure the processor with a preset to use
+     *
+     * @param preset `Object` with an plugins (set to list), and/or an optional settings object
      */
-    use(preset: Preset): Processor
+    use(preset: Preset<P>): Processor<P>
 
     /**
-     * @param pluginTuple pairs, plugin and options in an array
+     * Configure using a tuple of plugin and setting(s)
+     *
+     * @param pluginTuple pairs, plugin and settings in an array
+     * @typeParam S Plugin settings
+     * @typeParam S2 Extra plugin settings
      */
-    use<T = Settings>(pluginTuple: PluginTuple<T>): Processor
+    use<S = Settings, S2 = Settings>(
+      pluginTuple: PluginTuple<S, S2, P>
+    ): Processor<P>
 
     /**
-     * @param pluginTriple plugin, options, and extraOptions in an array
+     * A list of plugins and presets to be applied to processor
+     *
+     * @param list List of plugins, presets, and pairs
      */
-    use<T = Settings, S = undefined>(
-      pluginTriple: PluginTriple<T, S>
-    ): Processor
+    use(list: PluggableList<P>): Processor<P>
 
     /**
-     * @param list List of plugins, presets, and pairs
+     * Configuration passed to a frozen processor
+     *
+     * @param processorSettings Settings passed to processor
      */
-    use(list: PluggableList): Processor
+    use(processorSettings: ProcessorSettings<P>): Processor<P>
 
@@ -93,11 +112,31 @@ /**
      *
-     * @param node
+     * @param node Node to transform
+     * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree.
+     */
+    run(node: Node): Promise<Node>
+
+    /**
+     * Transform a syntax tree by applying plugins to it.
+     *
+     * @param node Node to transform
      * @param file `VFile` or anything which can be given to `vfile()`
-     * @param done Invoked when transformation is complete.
-     * Either invoked with an error or a syntax tree and a file.
      * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree.
      */
-    run(node: Node): Promise<Node>
     run(node: Node, file: VFileCompatible): Promise<Node>
+
+    /**
+     * Transform a syntax tree by applying plugins to it.
+     *
+     * @param node Node to transform
+     * @param done Invoked when transformation is complete.
+     */
     run(node: Node, done: RunCallback): void
+
+    /**
+     * Transform a syntax tree by applying plugins to it.
+     *
+     * @param node Node to transform
+     * @param file `VFile` or anything which can be given to `vfile()`
+     * @param done Invoked when transformation is complete.
+     */
     run(node: Node, file: VFileCompatible, done: RunCallback): void
@@ -110,3 +149,3 @@
      *
-     * @param node
+     * @param node Node to transform
      * @param file `VFile` or anything which can be given to `vfile()`
@@ -119,4 +158,3 @@ * @returns The given syntax tree.
      * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally.
-     * @param file
-     * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile.
+     * @param file `VFile` or anything which can be given to `vfile()`
      * @returns `Promise` if `done` is not given.
@@ -126,2 +164,8 @@ * Rejected with an error or resolved with the resulting file.
     process(file: VFileCompatible): Promise<VFile>
+
+    /**
+     * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally.
+     * @param file `VFile` or anything which can be given to `vfile()`
+     * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile.
+     */
     process(file: VFileCompatible, done: ProcessCallback): void
@@ -134,3 +178,3 @@
      *
-     * @param file
+     * @param file `VFile` or anything which can be given to `vfile()`
      * @returns Virtual file with modified contents.
@@ -147,2 +191,3 @@ */
     data(): {[key: string]: unknown}
+
     /**
@@ -153,2 +198,3 @@ * @param key Identifier
     data(key: string): unknown
+
     /**
@@ -158,3 +204,3 @@ * @param value Value to set. Omit if getting key
      */
-    data(key: string, value: any): Processor
+    data(key: string, value: any): Processor<P>
 
@@ -170,27 +216,79 @@ /**
      */
-    freeze(): Processor
+    freeze(): Processor<P>
   }
 
-  type Plugin<T = Settings, S = undefined> = Attacher<T, S>
+  /**
+   * A Plugin (Attacher) is the thing passed to `use`.
+   * It configures the processor and in turn can receive options.
+   *
+   * Attachers can configure processors, such as by interacting with parsers and compilers, linking them to other processors, or by specifying how the syntax tree is handled.
+   *
+   * @this Processor context object is set to the invoked on processor.
+   * @param settings Configuration
+   * @param extraSettings Secondary configuration
+   * @typeParam S Plugin settings
+   * @typeParam S2 Extra plugin settings
+   * @typeParam P Processor settings
+   * @returns Optional Transformer.
+   */
+  type Plugin<S = Settings, S2 = undefined, P = Settings> = Attacher<S, S2, P>
+
+  /**
+   * Configuration passed to a Plugin or Processor
+   */
   type Settings = {
     [key: string]: unknown
   }
+
   /**
    * Presets provide a potentially sharable way to configure processors.
    * They can contain multiple plugins and optionally settings as well.
+   *
+   * @typeParam P Processor settings
    */
-  interface Preset {
-    plugins?: PluggableList
+  interface Preset<P = Settings> {
+    plugins: PluggableList<P>
     settings?: Settings
   }
-  type PluginTuple<T = Settings> = [Plugin<T>, T]
-  type PluginTriple<T = Settings, S = undefined> = [Plugin<T, S>, T, S]
-  type Pluggable<T = Settings, S = undefined> =
-    | Plugin<T>
-    | Preset
-    | PluginTuple<T>
-    | PluginTriple<T, S>
-  type PluggableList = Array<Pluggable<any, any>>
 
   /**
+   * Settings can be passed directly to the processor
+   *
+   * @typeParam P Settings applied to a processor. Useful when packaging unified with a preset parser and compiler.
+   */
+  interface ProcessorSettings<P = Settings> {
+    settings: P
+  }
+
+  /**
+   * A pairing of a plugin with its settings
+   *
+   * @typeParam S Plugin settings
+   * @typeParam S2 Extra plugin settings
+   * @typeParam P Processor settings
+   */
+  type PluginTuple<S = Settings, S2 = undefined, P = Settings> =
+    | [Plugin<S, undefined, P>, S]
+    | [Plugin<S, S2, P>, S, S2]
+
+  /**
+   * A union of the different ways to add plugins to unified
+   *
+   * @typeParam S Plugin settings
+   * @typeParam S2 Extra plugin settings
+   * @typeParam P Processor settings
+   */
+  type Pluggable<S = Settings, S2 = undefined, P = Settings> =
+    | Plugin<S, S2, P>
+    | Preset<P>
+    | PluginTuple<S, S2, P>
+
+  /**
+   * A list of plugins and presets
+   *
+   * @typeParam P Processor settings
+   */
+  type PluggableList<P = Settings> = Array<Pluggable<any, any, P>>
+
+  /**
    * An attacher is the thing passed to `use`.
@@ -202,8 +300,11 @@ * It configures the processor and in turn can receive options.
    * @this Processor context object is set to the invoked on processor.
-   * @param options Configuration
-   * @param extraOptions Secondary configuration
-   * @returns Optional.
+   * @param settings Configuration
+   * @param extraSettings Secondary configuration
+   * @typeParam S Plugin settings
+   * @typeParam S2 Extra plugin settings
+   * @typeParam P Processor settings
+   * @returns Optional Transformer.
    */
-  interface Attacher<T = Settings, S = undefined> {
-    (this: Processor, options?: T, extraOptions?: S): Transformer | void
+  interface Attacher<S = Settings, S2 = undefined, P = Settings> {
+    (this: Processor<P>, settings?: S, extraSettings?: S2): Transformer | void
   }
@@ -217,4 +318,4 @@
    *
-   * @param node
-   * @param file
+   * @param node Node or tree to be transformed
+   * @param file File associated with node or tree
    * @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`.
@@ -234,17 +335,63 @@ * @returns
 
+  /**
+   * Transform file contents into an AST
+   */
   class Parser {
+    /**
+     * Transform file contents into an AST
+     *
+     * @param file File to transform into AST node(s)
+     */
     parse(file: VFileCompatible): Node
   }
 
+  /**
+   * Transform file contents into an AST
+   * @param file File to transform into AST node(s)
+   */
   type ParserFunction = (file: VFileCompatible) => Node
 
+  /**
+   * Transform an AST node/tree into text
+   */
   class Compiler {
+    /**
+     * Transform an AST node/tree into text
+     *
+     * @param node Node to be stringified
+     * @param file File associated with node
+     * @returns transformed text
+     */
     compile(node: Node, file?: VFileCompatible): string
   }
+
+  /**
+   * Transform an AST node/tree into text
+   *
+   * @param node Node to be stringified
+   * @param file File associated with node
+   * @returns transformed text
+   */
   type CompilerFunction = (node: Node, file?: VFileCompatible) => string
 
+  /**
+   * Access results from transforms
+   *
+   * @param error Error if any occurred
+   * @param node Transformed AST tree/node
+   * @param vfile File associated with node
+   */
   type RunCallback = (error: Error | null, node: Node, file: VFile) => void
 
+  /**
+   * Access results from transforms
+   *
+   * @param error Error if any occurred
+   * @param vfile File with updated content
+   */
   type ProcessCallback = (error: Error | null, file: VFile) => void
 
+  /**
+   * A union of the VFile types unified supports
+   */
   type VFileCompatible = VFile | VFileOptions | VFileContents
@@ -254,5 +401,7 @@ }
 /**
- * Object describing how to process text.
+ * Unified processor allows plugins, parsers, and compilers to be chained together to transform content.
+ *
+ * @typeParam P Processor settings. Useful when packaging unified with a preset parser and compiler.
  */
-declare function unified(): unified.Processor
+declare function unified<P = unified.Settings>(): unified.Processor<P>
 export = unified

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

64917

increased by7.67%

Lines of code

726

increased by23.26%

No dependency changes