1024 lines
41 KiB
TypeScript
1024 lines
41 KiB
TypeScript
import {CallableInstance} from './callable-instance.js'
|
||
/**
|
||
* @template {Node | undefined} [ParseTree=undefined]
|
||
* Output of `parse` (optional).
|
||
* @template {Node | undefined} [HeadTree=undefined]
|
||
* Input for `run` (optional).
|
||
* @template {Node | undefined} [TailTree=undefined]
|
||
* Output for `run` (optional).
|
||
* @template {Node | undefined} [CompileTree=undefined]
|
||
* Input of `stringify` (optional).
|
||
* @template {CompileResults | undefined} [CompileResult=undefined]
|
||
* Output of `stringify` (optional).
|
||
* @extends {CallableInstance<[], Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>>}
|
||
*/
|
||
export class Processor<ParseTree extends import("unist").Node | undefined = undefined, HeadTree extends import("unist").Node | undefined = undefined, TailTree extends import("unist").Node | undefined = undefined, CompileTree extends import("unist").Node | undefined = undefined, CompileResult extends CompileResults | undefined = undefined> extends CallableInstance<[], Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>> {
|
||
/**
|
||
* Create a processor.
|
||
*/
|
||
constructor();
|
||
/**
|
||
* Compiler to use (deprecated).
|
||
*
|
||
* @deprecated
|
||
* Use `compiler` instead.
|
||
* @type {(
|
||
* Compiler<
|
||
* CompileTree extends undefined ? Node : CompileTree,
|
||
* CompileResult extends undefined ? CompileResults : CompileResult
|
||
* > |
|
||
* undefined
|
||
* )}
|
||
*/
|
||
Compiler: (Compiler<CompileTree extends undefined ? Node : CompileTree, CompileResult extends undefined ? CompileResults : CompileResult> | undefined);
|
||
/**
|
||
* Parser to use (deprecated).
|
||
*
|
||
* @deprecated
|
||
* Use `parser` instead.
|
||
* @type {(
|
||
* Parser<ParseTree extends undefined ? Node : ParseTree> |
|
||
* undefined
|
||
* )}
|
||
*/
|
||
Parser: (Parser<ParseTree extends undefined ? Node : ParseTree> | undefined);
|
||
/**
|
||
* Internal list of configured plugins.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal property and should not be used.
|
||
* @type {Array<PluginTuple<Array<unknown>>>}
|
||
*/
|
||
attachers: Array<[plugin: Plugin<unknown[], undefined, undefined>, ...parameters: unknown[]]>;
|
||
/**
|
||
* Compiler to use.
|
||
*
|
||
* @type {(
|
||
* Compiler<
|
||
* CompileTree extends undefined ? Node : CompileTree,
|
||
* CompileResult extends undefined ? CompileResults : CompileResult
|
||
* > |
|
||
* undefined
|
||
* )}
|
||
*/
|
||
compiler: (Compiler<CompileTree extends undefined ? Node : CompileTree, CompileResult extends undefined ? CompileResults : CompileResult> | undefined);
|
||
/**
|
||
* Internal state to track where we are while freezing.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal property and should not be used.
|
||
* @type {number}
|
||
*/
|
||
freezeIndex: number;
|
||
/**
|
||
* Internal state to track whether we’re frozen.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal property and should not be used.
|
||
* @type {boolean | undefined}
|
||
*/
|
||
frozen: boolean | undefined;
|
||
/**
|
||
* Internal state.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal property and should not be used.
|
||
* @type {Data}
|
||
*/
|
||
namespace: Data;
|
||
/**
|
||
* Parser to use.
|
||
*
|
||
* @type {(
|
||
* Parser<ParseTree extends undefined ? Node : ParseTree> |
|
||
* undefined
|
||
* )}
|
||
*/
|
||
parser: (Parser<ParseTree extends undefined ? Node : ParseTree> | undefined);
|
||
/**
|
||
* Internal list of configured transformers.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal property and should not be used.
|
||
* @type {Pipeline}
|
||
*/
|
||
transformers: Pipeline;
|
||
/**
|
||
* Copy a processor.
|
||
*
|
||
* @deprecated
|
||
* This is a private internal method and should not be used.
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
* New *unfrozen* processor ({@link Processor `Processor`}) that is
|
||
* configured to work the same as its ancestor.
|
||
* When the descendant processor is configured in the future it does not
|
||
* affect the ancestral processor.
|
||
*/
|
||
copy(): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Configure the processor with info available to all plugins.
|
||
* Information is stored in an object.
|
||
*
|
||
* Typically, options can be given to a specific plugin, but sometimes it
|
||
* makes sense to have information shared with several plugins.
|
||
* For example, a list of HTML elements that are self-closing, which is
|
||
* needed during all phases.
|
||
*
|
||
* > 👉 **Note**: setting information cannot occur on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* > 👉 **Note**: to register custom data in TypeScript, augment the
|
||
* > {@link Data `Data`} interface.
|
||
*
|
||
* @example
|
||
* This example show how to get and set info:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* const processor = unified().data('alpha', 'bravo')
|
||
*
|
||
* processor.data('alpha') // => 'bravo'
|
||
*
|
||
* processor.data() // => {alpha: 'bravo'}
|
||
*
|
||
* processor.data({charlie: 'delta'})
|
||
*
|
||
* processor.data() // => {charlie: 'delta'}
|
||
* ```
|
||
*
|
||
* @template {keyof Data} Key
|
||
*
|
||
* @overload
|
||
* @returns {Data}
|
||
*
|
||
* @overload
|
||
* @param {Data} dataset
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @returns {Data[Key]}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @param {Data[Key]} value
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @param {Data | Key} [key]
|
||
* Key to get or set, or entire dataset to set, or nothing to get the
|
||
* entire dataset (optional).
|
||
* @param {Data[Key]} [value]
|
||
* Value to set (optional).
|
||
* @returns {unknown}
|
||
* The current processor when setting, the value at `key` when getting, or
|
||
* the entire dataset when getting without key.
|
||
*/
|
||
data<Key extends keyof import("unified").Data>(): Data;
|
||
/**
|
||
* Configure the processor with info available to all plugins.
|
||
* Information is stored in an object.
|
||
*
|
||
* Typically, options can be given to a specific plugin, but sometimes it
|
||
* makes sense to have information shared with several plugins.
|
||
* For example, a list of HTML elements that are self-closing, which is
|
||
* needed during all phases.
|
||
*
|
||
* > 👉 **Note**: setting information cannot occur on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* > 👉 **Note**: to register custom data in TypeScript, augment the
|
||
* > {@link Data `Data`} interface.
|
||
*
|
||
* @example
|
||
* This example show how to get and set info:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* const processor = unified().data('alpha', 'bravo')
|
||
*
|
||
* processor.data('alpha') // => 'bravo'
|
||
*
|
||
* processor.data() // => {alpha: 'bravo'}
|
||
*
|
||
* processor.data({charlie: 'delta'})
|
||
*
|
||
* processor.data() // => {charlie: 'delta'}
|
||
* ```
|
||
*
|
||
* @template {keyof Data} Key
|
||
*
|
||
* @overload
|
||
* @returns {Data}
|
||
*
|
||
* @overload
|
||
* @param {Data} dataset
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @returns {Data[Key]}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @param {Data[Key]} value
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @param {Data | Key} [key]
|
||
* Key to get or set, or entire dataset to set, or nothing to get the
|
||
* entire dataset (optional).
|
||
* @param {Data[Key]} [value]
|
||
* Value to set (optional).
|
||
* @returns {unknown}
|
||
* The current processor when setting, the value at `key` when getting, or
|
||
* the entire dataset when getting without key.
|
||
*/
|
||
data<Key extends keyof import("unified").Data>(dataset: Data): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Configure the processor with info available to all plugins.
|
||
* Information is stored in an object.
|
||
*
|
||
* Typically, options can be given to a specific plugin, but sometimes it
|
||
* makes sense to have information shared with several plugins.
|
||
* For example, a list of HTML elements that are self-closing, which is
|
||
* needed during all phases.
|
||
*
|
||
* > 👉 **Note**: setting information cannot occur on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* > 👉 **Note**: to register custom data in TypeScript, augment the
|
||
* > {@link Data `Data`} interface.
|
||
*
|
||
* @example
|
||
* This example show how to get and set info:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* const processor = unified().data('alpha', 'bravo')
|
||
*
|
||
* processor.data('alpha') // => 'bravo'
|
||
*
|
||
* processor.data() // => {alpha: 'bravo'}
|
||
*
|
||
* processor.data({charlie: 'delta'})
|
||
*
|
||
* processor.data() // => {charlie: 'delta'}
|
||
* ```
|
||
*
|
||
* @template {keyof Data} Key
|
||
*
|
||
* @overload
|
||
* @returns {Data}
|
||
*
|
||
* @overload
|
||
* @param {Data} dataset
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @returns {Data[Key]}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @param {Data[Key]} value
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @param {Data | Key} [key]
|
||
* Key to get or set, or entire dataset to set, or nothing to get the
|
||
* entire dataset (optional).
|
||
* @param {Data[Key]} [value]
|
||
* Value to set (optional).
|
||
* @returns {unknown}
|
||
* The current processor when setting, the value at `key` when getting, or
|
||
* the entire dataset when getting without key.
|
||
*/
|
||
data<Key extends keyof import("unified").Data>(key: Key): import("unified").Data[Key];
|
||
/**
|
||
* Configure the processor with info available to all plugins.
|
||
* Information is stored in an object.
|
||
*
|
||
* Typically, options can be given to a specific plugin, but sometimes it
|
||
* makes sense to have information shared with several plugins.
|
||
* For example, a list of HTML elements that are self-closing, which is
|
||
* needed during all phases.
|
||
*
|
||
* > 👉 **Note**: setting information cannot occur on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* > 👉 **Note**: to register custom data in TypeScript, augment the
|
||
* > {@link Data `Data`} interface.
|
||
*
|
||
* @example
|
||
* This example show how to get and set info:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* const processor = unified().data('alpha', 'bravo')
|
||
*
|
||
* processor.data('alpha') // => 'bravo'
|
||
*
|
||
* processor.data() // => {alpha: 'bravo'}
|
||
*
|
||
* processor.data({charlie: 'delta'})
|
||
*
|
||
* processor.data() // => {charlie: 'delta'}
|
||
* ```
|
||
*
|
||
* @template {keyof Data} Key
|
||
*
|
||
* @overload
|
||
* @returns {Data}
|
||
*
|
||
* @overload
|
||
* @param {Data} dataset
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @returns {Data[Key]}
|
||
*
|
||
* @overload
|
||
* @param {Key} key
|
||
* @param {Data[Key]} value
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @param {Data | Key} [key]
|
||
* Key to get or set, or entire dataset to set, or nothing to get the
|
||
* entire dataset (optional).
|
||
* @param {Data[Key]} [value]
|
||
* Value to set (optional).
|
||
* @returns {unknown}
|
||
* The current processor when setting, the value at `key` when getting, or
|
||
* the entire dataset when getting without key.
|
||
*/
|
||
data<Key extends keyof import("unified").Data>(key: Key, value: import("unified").Data[Key]): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Freeze a processor.
|
||
*
|
||
* Frozen processors are meant to be extended and not to be configured
|
||
* directly.
|
||
*
|
||
* When a processor is frozen it cannot be unfrozen.
|
||
* New processors working the same way can be created by calling the
|
||
* processor.
|
||
*
|
||
* It’s possible to freeze processors explicitly by calling `.freeze()`.
|
||
* Processors freeze automatically when `.parse()`, `.run()`, `.runSync()`,
|
||
* `.stringify()`, `.process()`, or `.processSync()` are called.
|
||
*
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
* The current processor.
|
||
*/
|
||
freeze(): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Parse text to a syntax tree.
|
||
*
|
||
* > 👉 **Note**: `parse` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `parse` performs the parse phase, not the run phase or other
|
||
* > phases.
|
||
*
|
||
* @param {Compatible | undefined} [file]
|
||
* file to parse (optional); typically `string` or `VFile`; any value
|
||
* accepted as `x` in `new VFile(x)`.
|
||
* @returns {ParseTree extends undefined ? Node : ParseTree}
|
||
* Syntax tree representing `file`.
|
||
*/
|
||
parse(file?: Compatible | undefined): ParseTree extends undefined ? Node : ParseTree;
|
||
/**
|
||
* Process the given file as configured on the processor.
|
||
*
|
||
* > 👉 **Note**: `process` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `process` performs the parse, run, and stringify phases.
|
||
*
|
||
* @overload
|
||
* @param {Compatible | undefined} file
|
||
* @param {ProcessCallback<VFileWithOutput<CompileResult>>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {Compatible | undefined} [file]
|
||
* @returns {Promise<VFileWithOutput<CompileResult>>}
|
||
*
|
||
* @param {Compatible | undefined} [file]
|
||
* File (optional); typically `string` or `VFile`]; any value accepted as
|
||
* `x` in `new VFile(x)`.
|
||
* @param {ProcessCallback<VFileWithOutput<CompileResult>> | undefined} [done]
|
||
* Callback (optional).
|
||
* @returns {Promise<VFile> | undefined}
|
||
* Nothing if `done` is given.
|
||
* Otherwise a promise, rejected with a fatal error or resolved with the
|
||
* processed file.
|
||
*
|
||
* The parsed, transformed, and compiled value is available at
|
||
* `file.value` (see note).
|
||
*
|
||
* > 👉 **Note**: unified typically compiles by serializing: most
|
||
* > compilers return `string` (or `Uint8Array`).
|
||
* > Some compilers, such as the one configured with
|
||
* > [`rehype-react`][rehype-react], return other values (in this case, a
|
||
* > React tree).
|
||
* > If you’re using a compiler that doesn’t serialize, expect different
|
||
* > result values.
|
||
* >
|
||
* > To register custom results in TypeScript, add them to
|
||
* > {@link CompileResultMap `CompileResultMap`}.
|
||
*
|
||
* [rehype-react]: https://github.com/rehypejs/rehype-react
|
||
*/
|
||
process(file: Compatible | undefined, done: ProcessCallback<VFileWithOutput<CompileResult>>): undefined;
|
||
/**
|
||
* Process the given file as configured on the processor.
|
||
*
|
||
* > 👉 **Note**: `process` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `process` performs the parse, run, and stringify phases.
|
||
*
|
||
* @overload
|
||
* @param {Compatible | undefined} file
|
||
* @param {ProcessCallback<VFileWithOutput<CompileResult>>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {Compatible | undefined} [file]
|
||
* @returns {Promise<VFileWithOutput<CompileResult>>}
|
||
*
|
||
* @param {Compatible | undefined} [file]
|
||
* File (optional); typically `string` or `VFile`]; any value accepted as
|
||
* `x` in `new VFile(x)`.
|
||
* @param {ProcessCallback<VFileWithOutput<CompileResult>> | undefined} [done]
|
||
* Callback (optional).
|
||
* @returns {Promise<VFile> | undefined}
|
||
* Nothing if `done` is given.
|
||
* Otherwise a promise, rejected with a fatal error or resolved with the
|
||
* processed file.
|
||
*
|
||
* The parsed, transformed, and compiled value is available at
|
||
* `file.value` (see note).
|
||
*
|
||
* > 👉 **Note**: unified typically compiles by serializing: most
|
||
* > compilers return `string` (or `Uint8Array`).
|
||
* > Some compilers, such as the one configured with
|
||
* > [`rehype-react`][rehype-react], return other values (in this case, a
|
||
* > React tree).
|
||
* > If you’re using a compiler that doesn’t serialize, expect different
|
||
* > result values.
|
||
* >
|
||
* > To register custom results in TypeScript, add them to
|
||
* > {@link CompileResultMap `CompileResultMap`}.
|
||
*
|
||
* [rehype-react]: https://github.com/rehypejs/rehype-react
|
||
*/
|
||
process(file?: Compatible | undefined): Promise<VFileWithOutput<CompileResult>>;
|
||
/**
|
||
* Process the given file as configured on the processor.
|
||
*
|
||
* An error is thrown if asynchronous transforms are configured.
|
||
*
|
||
* > 👉 **Note**: `processSync` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `processSync` performs the parse, run, and stringify phases.
|
||
*
|
||
* @param {Compatible | undefined} [file]
|
||
* File (optional); typically `string` or `VFile`; any value accepted as
|
||
* `x` in `new VFile(x)`.
|
||
* @returns {VFileWithOutput<CompileResult>}
|
||
* The processed file.
|
||
*
|
||
* The parsed, transformed, and compiled value is available at
|
||
* `file.value` (see note).
|
||
*
|
||
* > 👉 **Note**: unified typically compiles by serializing: most
|
||
* > compilers return `string` (or `Uint8Array`).
|
||
* > Some compilers, such as the one configured with
|
||
* > [`rehype-react`][rehype-react], return other values (in this case, a
|
||
* > React tree).
|
||
* > If you’re using a compiler that doesn’t serialize, expect different
|
||
* > result values.
|
||
* >
|
||
* > To register custom results in TypeScript, add them to
|
||
* > {@link CompileResultMap `CompileResultMap`}.
|
||
*
|
||
* [rehype-react]: https://github.com/rehypejs/rehype-react
|
||
*/
|
||
processSync(file?: Compatible | undefined): VFileWithOutput<CompileResult>;
|
||
/**
|
||
* Run *transformers* on a syntax tree.
|
||
*
|
||
* > 👉 **Note**: `run` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `run` performs the run phase, not other phases.
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} file
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} [file]
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree>}
|
||
*
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* Tree to transform and inspect.
|
||
* @param {(
|
||
* RunCallback<TailTree extends undefined ? Node : TailTree> |
|
||
* Compatible
|
||
* )} [file]
|
||
* File associated with `node` (optional); any value accepted as `x` in
|
||
* `new VFile(x)`.
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} [done]
|
||
* Callback (optional).
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree> | undefined}
|
||
* Nothing if `done` is given.
|
||
* Otherwise, a promise rejected with a fatal error or resolved with the
|
||
* transformed tree.
|
||
*/
|
||
run(tree: HeadTree extends undefined ? Node : HeadTree, done: RunCallback<TailTree extends undefined ? Node : TailTree>): undefined;
|
||
/**
|
||
* Run *transformers* on a syntax tree.
|
||
*
|
||
* > 👉 **Note**: `run` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `run` performs the run phase, not other phases.
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} file
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} [file]
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree>}
|
||
*
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* Tree to transform and inspect.
|
||
* @param {(
|
||
* RunCallback<TailTree extends undefined ? Node : TailTree> |
|
||
* Compatible
|
||
* )} [file]
|
||
* File associated with `node` (optional); any value accepted as `x` in
|
||
* `new VFile(x)`.
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} [done]
|
||
* Callback (optional).
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree> | undefined}
|
||
* Nothing if `done` is given.
|
||
* Otherwise, a promise rejected with a fatal error or resolved with the
|
||
* transformed tree.
|
||
*/
|
||
run(tree: HeadTree extends undefined ? Node : HeadTree, file: Compatible | undefined, done: RunCallback<TailTree extends undefined ? Node : TailTree>): undefined;
|
||
/**
|
||
* Run *transformers* on a syntax tree.
|
||
*
|
||
* > 👉 **Note**: `run` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `run` performs the run phase, not other phases.
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} file
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* @param {Compatible | undefined} [file]
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree>}
|
||
*
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* Tree to transform and inspect.
|
||
* @param {(
|
||
* RunCallback<TailTree extends undefined ? Node : TailTree> |
|
||
* Compatible
|
||
* )} [file]
|
||
* File associated with `node` (optional); any value accepted as `x` in
|
||
* `new VFile(x)`.
|
||
* @param {RunCallback<TailTree extends undefined ? Node : TailTree>} [done]
|
||
* Callback (optional).
|
||
* @returns {Promise<TailTree extends undefined ? Node : TailTree> | undefined}
|
||
* Nothing if `done` is given.
|
||
* Otherwise, a promise rejected with a fatal error or resolved with the
|
||
* transformed tree.
|
||
*/
|
||
run(tree: HeadTree extends undefined ? Node : HeadTree, file?: Compatible | undefined): Promise<TailTree extends undefined ? Node : TailTree>;
|
||
/**
|
||
* Run *transformers* on a syntax tree.
|
||
*
|
||
* An error is thrown if asynchronous transforms are configured.
|
||
*
|
||
* > 👉 **Note**: `runSync` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `runSync` performs the run phase, not other phases.
|
||
*
|
||
* @param {HeadTree extends undefined ? Node : HeadTree} tree
|
||
* Tree to transform and inspect.
|
||
* @param {Compatible | undefined} [file]
|
||
* File associated with `node` (optional); any value accepted as `x` in
|
||
* `new VFile(x)`.
|
||
* @returns {TailTree extends undefined ? Node : TailTree}
|
||
* Transformed tree.
|
||
*/
|
||
runSync(tree: HeadTree extends undefined ? Node : HeadTree, file?: Compatible | undefined): TailTree extends undefined ? Node : TailTree;
|
||
/**
|
||
* Compile a syntax tree.
|
||
*
|
||
* > 👉 **Note**: `stringify` freezes the processor if not already *frozen*.
|
||
*
|
||
* > 👉 **Note**: `stringify` performs the stringify phase, not the run phase
|
||
* > or other phases.
|
||
*
|
||
* @param {CompileTree extends undefined ? Node : CompileTree} tree
|
||
* Tree to compile.
|
||
* @param {Compatible | undefined} [file]
|
||
* File associated with `node` (optional); any value accepted as `x` in
|
||
* `new VFile(x)`.
|
||
* @returns {CompileResult extends undefined ? Value : CompileResult}
|
||
* Textual representation of the tree (see note).
|
||
*
|
||
* > 👉 **Note**: unified typically compiles by serializing: most compilers
|
||
* > return `string` (or `Uint8Array`).
|
||
* > Some compilers, such as the one configured with
|
||
* > [`rehype-react`][rehype-react], return other values (in this case, a
|
||
* > React tree).
|
||
* > If you’re using a compiler that doesn’t serialize, expect different
|
||
* > result values.
|
||
* >
|
||
* > To register custom results in TypeScript, add them to
|
||
* > {@link CompileResultMap `CompileResultMap`}.
|
||
*
|
||
* [rehype-react]: https://github.com/rehypejs/rehype-react
|
||
*/
|
||
stringify(tree: CompileTree extends undefined ? Node : CompileTree, file?: Compatible | undefined): CompileResult extends undefined ? Value : CompileResult;
|
||
/**
|
||
* Configure the processor to use a plugin, a list of usable values, or a
|
||
* preset.
|
||
*
|
||
* If the processor is already using a plugin, the previous plugin
|
||
* configuration is changed based on the options that are passed in.
|
||
* In other words, the plugin is not added a second time.
|
||
*
|
||
* > 👉 **Note**: `use` cannot be called on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* @example
|
||
* There are many ways to pass plugins to `.use()`.
|
||
* This example gives an overview:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* unified()
|
||
* // Plugin with options:
|
||
* .use(pluginA, {x: true, y: true})
|
||
* // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):
|
||
* .use(pluginA, {y: false, z: true})
|
||
* // Plugins:
|
||
* .use([pluginB, pluginC])
|
||
* // Two plugins, the second with options:
|
||
* .use([pluginD, [pluginE, {}]])
|
||
* // Preset with plugins and settings:
|
||
* .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})
|
||
* // Settings only:
|
||
* .use({settings: {position: false}})
|
||
* ```
|
||
*
|
||
* @template {Array<unknown>} [Parameters=[]]
|
||
* @template {Node | string | undefined} [Input=undefined]
|
||
* @template [Output=Input]
|
||
*
|
||
* @overload
|
||
* @param {Preset | null | undefined} [preset]
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {PluggableList} list
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Plugin<Parameters, Input, Output>} plugin
|
||
* @param {...(Parameters | [boolean])} parameters
|
||
* @returns {UsePlugin<ParseTree, HeadTree, TailTree, CompileTree, CompileResult, Input, Output>}
|
||
*
|
||
* @param {PluggableList | Plugin | Preset | null | undefined} value
|
||
* Usable value.
|
||
* @param {...unknown} parameters
|
||
* Parameters, when a plugin is given as a usable value.
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
* Current processor.
|
||
*/
|
||
use<Parameters_2 extends unknown[] = [], Input extends string | import("unist").Node | undefined = undefined, Output = Input>(preset?: Preset | null | undefined): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Configure the processor to use a plugin, a list of usable values, or a
|
||
* preset.
|
||
*
|
||
* If the processor is already using a plugin, the previous plugin
|
||
* configuration is changed based on the options that are passed in.
|
||
* In other words, the plugin is not added a second time.
|
||
*
|
||
* > 👉 **Note**: `use` cannot be called on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* @example
|
||
* There are many ways to pass plugins to `.use()`.
|
||
* This example gives an overview:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* unified()
|
||
* // Plugin with options:
|
||
* .use(pluginA, {x: true, y: true})
|
||
* // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):
|
||
* .use(pluginA, {y: false, z: true})
|
||
* // Plugins:
|
||
* .use([pluginB, pluginC])
|
||
* // Two plugins, the second with options:
|
||
* .use([pluginD, [pluginE, {}]])
|
||
* // Preset with plugins and settings:
|
||
* .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})
|
||
* // Settings only:
|
||
* .use({settings: {position: false}})
|
||
* ```
|
||
*
|
||
* @template {Array<unknown>} [Parameters=[]]
|
||
* @template {Node | string | undefined} [Input=undefined]
|
||
* @template [Output=Input]
|
||
*
|
||
* @overload
|
||
* @param {Preset | null | undefined} [preset]
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {PluggableList} list
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Plugin<Parameters, Input, Output>} plugin
|
||
* @param {...(Parameters | [boolean])} parameters
|
||
* @returns {UsePlugin<ParseTree, HeadTree, TailTree, CompileTree, CompileResult, Input, Output>}
|
||
*
|
||
* @param {PluggableList | Plugin | Preset | null | undefined} value
|
||
* Usable value.
|
||
* @param {...unknown} parameters
|
||
* Parameters, when a plugin is given as a usable value.
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
* Current processor.
|
||
*/
|
||
use<Parameters_2 extends unknown[] = [], Input extends string | import("unist").Node | undefined = undefined, Output = Input>(list: PluggableList): Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>;
|
||
/**
|
||
* Configure the processor to use a plugin, a list of usable values, or a
|
||
* preset.
|
||
*
|
||
* If the processor is already using a plugin, the previous plugin
|
||
* configuration is changed based on the options that are passed in.
|
||
* In other words, the plugin is not added a second time.
|
||
*
|
||
* > 👉 **Note**: `use` cannot be called on *frozen* processors.
|
||
* > Call the processor first to create a new unfrozen processor.
|
||
*
|
||
* @example
|
||
* There are many ways to pass plugins to `.use()`.
|
||
* This example gives an overview:
|
||
*
|
||
* ```js
|
||
* import {unified} from 'unified'
|
||
*
|
||
* unified()
|
||
* // Plugin with options:
|
||
* .use(pluginA, {x: true, y: true})
|
||
* // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):
|
||
* .use(pluginA, {y: false, z: true})
|
||
* // Plugins:
|
||
* .use([pluginB, pluginC])
|
||
* // Two plugins, the second with options:
|
||
* .use([pluginD, [pluginE, {}]])
|
||
* // Preset with plugins and settings:
|
||
* .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})
|
||
* // Settings only:
|
||
* .use({settings: {position: false}})
|
||
* ```
|
||
*
|
||
* @template {Array<unknown>} [Parameters=[]]
|
||
* @template {Node | string | undefined} [Input=undefined]
|
||
* @template [Output=Input]
|
||
*
|
||
* @overload
|
||
* @param {Preset | null | undefined} [preset]
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {PluggableList} list
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
*
|
||
* @overload
|
||
* @param {Plugin<Parameters, Input, Output>} plugin
|
||
* @param {...(Parameters | [boolean])} parameters
|
||
* @returns {UsePlugin<ParseTree, HeadTree, TailTree, CompileTree, CompileResult, Input, Output>}
|
||
*
|
||
* @param {PluggableList | Plugin | Preset | null | undefined} value
|
||
* Usable value.
|
||
* @param {...unknown} parameters
|
||
* Parameters, when a plugin is given as a usable value.
|
||
* @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}
|
||
* Current processor.
|
||
*/
|
||
use<Parameters_2 extends unknown[] = [], Input extends string | import("unist").Node | undefined = undefined, Output = Input>(plugin: Plugin<Parameters_2, Input, Output>, ...parameters: Parameters_2 | [boolean]): UsePlugin<ParseTree, HeadTree, TailTree, CompileTree, CompileResult, Input, Output>;
|
||
}
|
||
/**
|
||
* Create a new processor.
|
||
*
|
||
* @example
|
||
* This example shows how a new processor can be created (from `remark`) and linked
|
||
* to **stdin**(4) and **stdout**(4).
|
||
*
|
||
* ```js
|
||
* import process from 'node:process'
|
||
* import concatStream from 'concat-stream'
|
||
* import {remark} from 'remark'
|
||
*
|
||
* process.stdin.pipe(
|
||
* concatStream(function (buf) {
|
||
* process.stdout.write(String(remark().processSync(buf)))
|
||
* })
|
||
* )
|
||
* ```
|
||
*
|
||
* @returns
|
||
* New *unfrozen* processor (`processor`).
|
||
*
|
||
* This processor is configured to work the same as its ancestor.
|
||
* When the descendant processor is configured in the future it does not
|
||
* affect the ancestral processor.
|
||
*/
|
||
export const unified: Processor<undefined, undefined, undefined, undefined, undefined>;
|
||
export type Pipeline = import('trough').Pipeline;
|
||
export type Node = import('unist').Node;
|
||
export type Compatible = import('vfile').Compatible;
|
||
export type Value = import('vfile').Value;
|
||
export type CompileResultMap = import('../index.js').CompileResultMap;
|
||
export type Data = import('../index.js').Data;
|
||
export type Settings = import('../index.js').Settings;
|
||
/**
|
||
* Acceptable results from compilers.
|
||
*
|
||
* To register custom results, add them to
|
||
* {@link CompileResultMap `CompileResultMap`}.
|
||
*/
|
||
export type CompileResults = CompileResultMap[keyof CompileResultMap];
|
||
/**
|
||
* A **compiler** handles the compiling of a syntax tree to something else
|
||
* (in most cases, text) (TypeScript type).
|
||
*
|
||
* It is used in the stringify phase and called with a {@link Node `Node`}
|
||
* and {@link VFile `VFile`} representation of the document to compile.
|
||
* It should return the textual representation of the given tree (typically
|
||
* `string`).
|
||
*
|
||
* > 👉 **Note**: unified typically compiles by serializing: most compilers
|
||
* > return `string` (or `Uint8Array`).
|
||
* > Some compilers, such as the one configured with
|
||
* > [`rehype-react`][rehype-react], return other values (in this case, a
|
||
* > React tree).
|
||
* > If you’re using a compiler that doesn’t serialize, expect different
|
||
* > result values.
|
||
* >
|
||
* > To register custom results in TypeScript, add them to
|
||
* > {@link CompileResultMap `CompileResultMap`}.
|
||
*
|
||
* [rehype-react]: https://github.com/rehypejs/rehype-react
|
||
*/
|
||
export type Compiler<Tree extends import("unist").Node = import("unist").Node, Result extends CompileResults = CompileResults> = (tree: Tree, file: VFile) => Result;
|
||
/**
|
||
* A **parser** handles the parsing of text to a syntax tree.
|
||
*
|
||
* It is used in the parse phase and is called with a `string` and
|
||
* {@link VFile `VFile`} of the document to parse.
|
||
* It must return the syntax tree representation of the given file
|
||
* ({@link Node `Node`}).
|
||
*/
|
||
export type Parser<Tree extends import("unist").Node = import("unist").Node> = (document: string, file: VFile) => Tree;
|
||
/**
|
||
* Union of the different ways to add plugins and settings.
|
||
*/
|
||
export type Pluggable = (Plugin<Array<any>, any, any> | PluginTuple<Array<any>, any, any> | Preset);
|
||
/**
|
||
* List of plugins and presets.
|
||
*/
|
||
export type PluggableList = Array<Pluggable>;
|
||
/**
|
||
* Single plugin.
|
||
*
|
||
* Plugins configure the processors they are applied on in the following
|
||
* ways:
|
||
*
|
||
* * they change the processor, such as the parser, the compiler, or by
|
||
* configuring data
|
||
* * they specify how to handle trees and files
|
||
*
|
||
* In practice, they are functions that can receive options and configure the
|
||
* processor (`this`).
|
||
*
|
||
* > 👉 **Note**: plugins are called when the processor is *frozen*, not when
|
||
* > they are applied.
|
||
*/
|
||
export type Plugin<PluginParameters extends unknown[] = [], Input extends string | import("unist").Node | undefined = import("unist").Node, Output = Input> = (this: Processor, ...parameters: PluginParameters) => Input extends string ? Output extends Node | undefined ? undefined | void : never : Output extends CompileResults ? Input extends Node | undefined ? undefined | void : never : Transformer<Input extends Node ? Input : Node, Output extends Node ? Output : Node> | undefined | void;
|
||
/**
|
||
* Tuple of a plugin and its configuration.
|
||
*
|
||
* The first item is a plugin, the rest are its parameters.
|
||
*/
|
||
export type PluginTuple<TupleParameters extends unknown[] = [], Input extends string | import("unist").Node | undefined = undefined, Output = undefined> = ([
|
||
plugin: Plugin<TupleParameters, Input, Output>,
|
||
...parameters: TupleParameters
|
||
]);
|
||
/**
|
||
* Sharable configuration.
|
||
*
|
||
* They can contain plugins and settings.
|
||
*/
|
||
export type Preset = {
|
||
/**
|
||
* List of plugins and presets (optional).
|
||
*/
|
||
plugins?: PluggableList | undefined;
|
||
/**
|
||
* Shared settings for parsers and compilers (optional).
|
||
*/
|
||
settings?: Settings | undefined;
|
||
};
|
||
/**
|
||
* Callback called when the process is done.
|
||
*
|
||
* Called with either an error or a result.
|
||
*/
|
||
export type ProcessCallback<File extends VFile = VFile> = (error?: Error | undefined, file?: File | undefined) => undefined;
|
||
/**
|
||
* Callback called when transformers are done.
|
||
*
|
||
* Called with either an error or results.
|
||
*/
|
||
export type RunCallback<Tree extends import("unist").Node = import("unist").Node> = (error?: Error | undefined, tree?: Tree | undefined, file?: VFile | undefined) => undefined;
|
||
/**
|
||
* Callback passed to transforms.
|
||
*
|
||
* If the signature of a `transformer` accepts a third argument, the
|
||
* transformer may perform asynchronous operations, and must call it.
|
||
*/
|
||
export type TransformCallback<Output extends import("unist").Node = import("unist").Node> = (error?: Error | undefined, tree?: Output | undefined, file?: VFile | undefined) => undefined;
|
||
/**
|
||
* Transformers handle syntax trees and files.
|
||
*
|
||
* They are functions that are called each time a syntax tree and file are
|
||
* passed through the run phase.
|
||
* When an error occurs in them (either because it’s thrown, returned,
|
||
* rejected, or passed to `next`), the process stops.
|
||
*
|
||
* The run phase is handled by [`trough`][trough], see its documentation for
|
||
* the exact semantics of these functions.
|
||
*
|
||
* > 👉 **Note**: you should likely ignore `next`: don’t accept it.
|
||
* > it supports callback-style async work.
|
||
* > But promises are likely easier to reason about.
|
||
*
|
||
* [trough]: https://github.com/wooorm/trough#function-fninput-next
|
||
*/
|
||
export type Transformer<Input extends import("unist").Node = import("unist").Node, Output extends import("unist").Node = Input> = (tree: Input, file: VFile, next: TransformCallback<Output>) => (Promise<Output | undefined | void> | Promise<never> | // For some reason this is needed separately.
|
||
Output | Error | undefined | void);
|
||
/**
|
||
* Create a processor based on the input/output of a {@link Plugin plugin}.
|
||
*/
|
||
export type UsePlugin<ParseTree extends import("unist").Node | undefined, HeadTree extends import("unist").Node | undefined, TailTree extends import("unist").Node | undefined, CompileTree extends import("unist").Node | undefined, CompileResult extends CompileResults | undefined, Input extends string | import("unist").Node | undefined, Output> = (Input extends string ? Output extends Node | undefined ? Processor<Output extends undefined ? ParseTree : Output, HeadTree, TailTree, CompileTree, CompileResult> : Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult> : Output extends CompileResults ? Input extends Node | undefined ? Processor<ParseTree, HeadTree, TailTree, Input extends undefined ? CompileTree : Input, Output extends undefined ? CompileResult : Output> : Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult> : Input extends Node | undefined ? Output extends Node | undefined ? Processor<ParseTree, HeadTree extends undefined ? Input : HeadTree, Output extends undefined ? TailTree : Output, CompileTree, CompileResult> : Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult> : Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>);
|
||
/**
|
||
* Type to generate a {@link VFile `VFile`} corresponding to a compiler result.
|
||
*
|
||
* If a result that is not acceptable on a `VFile` is used, that will
|
||
* be stored on the `result` field of {@link VFile `VFile`}.
|
||
*/
|
||
export type VFileWithOutput<Result extends CompileResults | undefined> = (Result extends Value | undefined ? VFile : VFile & {
|
||
result: Result;
|
||
});
|
||
import { VFile } from 'vfile';
|
||
export {};
|
||
//# sourceMappingURL=index.d.ts.map
|