Brunobkr/llama.cpp_AlgMor24_github

1/**2 * @typedef {import('trough').Pipeline} Pipeline3 *4 * @typedef {import('unist').Node} Node5 *6 * @typedef {import('vfile').Compatible} Compatible7 * @typedef {import('vfile').Value} Value8 *9 * @typedef {import('../index.js').CompileResultMap} CompileResultMap10 * @typedef {import('../index.js').Data} Data11 * @typedef {import('../index.js').Settings} Settings12 */13 14/**15 * @typedef {CompileResultMap[keyof CompileResultMap]} CompileResults16 *   Acceptable results from compilers.17 *18 *   To register custom results, add them to19 *   {@linkcode CompileResultMap}.20 */21 22/**23 * @template {Node} [Tree=Node]24 *   The node that the compiler receives (default: `Node`).25 * @template {CompileResults} [Result=CompileResults]26 *   The thing that the compiler yields (default: `CompileResults`).27 * @callback Compiler28 *   A **compiler** handles the compiling of a syntax tree to something else29 *   (in most cases, text) (TypeScript type).30 *31 *   It is used in the stringify phase and called with a {@linkcode Node}32 *   and {@linkcode VFile} representation of the document to compile.33 *   It should return the textual representation of the given tree (typically34 *   `string`).35 *36 *   > **Note**: unified typically compiles by serializing: most compilers37 *   > return `string` (or `Uint8Array`).38 *   > Some compilers, such as the one configured with39 *   > [`rehype-react`][rehype-react], return other values (in this case, a40 *   > React tree).41 *   > If you’re using a compiler that doesn’t serialize, expect different42 *   > result values.43 *   >44 *   > To register custom results in TypeScript, add them to45 *   > {@linkcode CompileResultMap}.46 *47 *   [rehype-react]: https://github.com/rehypejs/rehype-react48 * @param {Tree} tree49 *   Tree to compile.50 * @param {VFile} file51 *   File associated with `tree`.52 * @returns {Result}53 *   New content: compiled text (`string` or `Uint8Array`, for `file.value`) or54 *   something else (for `file.result`).55 */56 57/**58 * @template {Node} [Tree=Node]59 *   The node that the parser yields (default: `Node`)60 * @callback Parser61 *   A **parser** handles the parsing of text to a syntax tree.62 *63 *   It is used in the parse phase and is called with a `string` and64 *   {@linkcode VFile} of the document to parse.65 *   It must return the syntax tree representation of the given file66 *   ({@linkcode Node}).67 * @param {string} document68 *   Document to parse.69 * @param {VFile} file70 *   File associated with `document`.71 * @returns {Tree}72 *   Node representing the given file.73 */74 75/**76 * @typedef {(77 *   Plugin<Array<any>, any, any> |78 *   PluginTuple<Array<any>, any, any> |79 *   Preset80 * )} Pluggable81 *   Union of the different ways to add plugins and settings.82 */83 84/**85 * @typedef {Array<Pluggable>} PluggableList86 *   List of plugins and presets.87 */88 89// Note: we can’t use `callback` yet as it messes up `this`:90//  <https://github.com/microsoft/TypeScript/issues/55197>.91/**92 * @template {Array<unknown>} [PluginParameters=[]]93 *   Arguments passed to the plugin (default: `[]`, the empty tuple).94 * @template {Node | string | undefined} [Input=Node]95 *   Value that is expected as input (default: `Node`).96 *97 *   *   If the plugin returns a {@linkcode Transformer}, this98 *       should be the node it expects.99 *   *   If the plugin sets a {@linkcode Parser}, this should be100 *       `string`.101 *   *   If the plugin sets a {@linkcode Compiler}, this should be the102 *       node it expects.103 * @template [Output=Input]104 *   Value that is yielded as output (default: `Input`).105 *106 *   *   If the plugin returns a {@linkcode Transformer}, this107 *       should be the node that that yields.108 *   *   If the plugin sets a {@linkcode Parser}, this should be the109 *       node that it yields.110 *   *   If the plugin sets a {@linkcode Compiler}, this should be111 *       result it yields.112 * @typedef {(113 *   (this: Processor, ...parameters: PluginParameters) =>114 *     Input extends string ? // Parser.115 *        Output extends Node | undefined ? undefined | void : never :116 *     Output extends CompileResults ? // Compiler.117 *        Input extends Node | undefined ? undefined | void : never :118 *     Transformer<119 *       Input extends Node ? Input : Node,120 *       Output extends Node ? Output : Node121 *     > | undefined | void122 * )} Plugin123 *   Single plugin.124 *125 *   Plugins configure the processors they are applied on in the following126 *   ways:127 *128 *   *   they change the processor, such as the parser, the compiler, or by129 *       configuring data130 *   *   they specify how to handle trees and files131 *132 *   In practice, they are functions that can receive options and configure the133 *   processor (`this`).134 *135 *   > **Note**: plugins are called when the processor is *frozen*, not when136 *   > they are applied.137 */138 139/**140 * Tuple of a plugin and its configuration.141 *142 * The first item is a plugin, the rest are its parameters.143 *144 * @template {Array<unknown>} [TupleParameters=[]]145 *   Arguments passed to the plugin (default: `[]`, the empty tuple).146 * @template {Node | string | undefined} [Input=undefined]147 *   Value that is expected as input (optional).148 *149 *   *   If the plugin returns a {@linkcode Transformer}, this150 *       should be the node it expects.151 *   *   If the plugin sets a {@linkcode Parser}, this should be152 *       `string`.153 *   *   If the plugin sets a {@linkcode Compiler}, this should be the154 *       node it expects.155 * @template [Output=undefined] (optional).156 *   Value that is yielded as output.157 *158 *   *   If the plugin returns a {@linkcode Transformer}, this159 *       should be the node that that yields.160 *   *   If the plugin sets a {@linkcode Parser}, this should be the161 *       node that it yields.162 *   *   If the plugin sets a {@linkcode Compiler}, this should be163 *       result it yields.164 * @typedef {(165 *   [166 *     plugin: Plugin<TupleParameters, Input, Output>,167 *     ...parameters: TupleParameters168 *   ]169 * )} PluginTuple170 */171 172/**173 * @typedef Preset174 *   Sharable configuration.175 *176 *   They can contain plugins and settings.177 * @property {PluggableList | undefined} [plugins]178 *   List of plugins and presets (optional).179 * @property {Settings | undefined} [settings]180 *   Shared settings for parsers and compilers (optional).181 */182 183/**184 * @template {VFile} [File=VFile]185 *   The file that the callback receives (default: `VFile`).186 * @callback ProcessCallback187 *   Callback called when the process is done.188 *189 *   Called with either an error or a result.190 * @param {Error | undefined} [error]191 *   Fatal error (optional).192 * @param {File | undefined} [file]193 *   Processed file (optional).194 * @returns {undefined}195 *   Nothing.196 */197 198/**199 * @template {Node} [Tree=Node]200 *   The tree that the callback receives (default: `Node`).201 * @callback RunCallback202 *   Callback called when transformers are done.203 *204 *   Called with either an error or results.205 * @param {Error | undefined} [error]206 *   Fatal error (optional).207 * @param {Tree | undefined} [tree]208 *   Transformed tree (optional).209 * @param {VFile | undefined} [file]210 *   File (optional).211 * @returns {undefined}212 *   Nothing.213 */214 215/**216 * @template {Node} [Output=Node]217 *   Node type that the transformer yields (default: `Node`).218 * @callback TransformCallback219 *   Callback passed to transforms.220 *221 *   If the signature of a `transformer` accepts a third argument, the222 *   transformer may perform asynchronous operations, and must call it.223 * @param {Error | undefined} [error]224 *   Fatal error to stop the process (optional).225 * @param {Output | undefined} [tree]226 *   New, changed, tree (optional).227 * @param {VFile | undefined} [file]228 *   New, changed, file (optional).229 * @returns {undefined}230 *   Nothing.231 */232 233/**234 * @template {Node} [Input=Node]235 *   Node type that the transformer expects (default: `Node`).236 * @template {Node} [Output=Input]237 *   Node type that the transformer yields (default: `Input`).238 * @callback Transformer239 *   Transformers handle syntax trees and files.240 *241 *   They are functions that are called each time a syntax tree and file are242 *   passed through the run phase.243 *   When an error occurs in them (either because it’s thrown, returned,244 *   rejected, or passed to `next`), the process stops.245 *246 *   The run phase is handled by [`trough`][trough], see its documentation for247 *   the exact semantics of these functions.248 *249 *   > **Note**: you should likely ignore `next`: don’t accept it.250 *   > it supports callback-style async work.251 *   > But promises are likely easier to reason about.252 *253 *   [trough]: https://github.com/wooorm/trough#function-fninput-next254 * @param {Input} tree255 *   Tree to handle.256 * @param {VFile} file257 *   File to handle.258 * @param {TransformCallback<Output>} next259 *   Callback.260 * @returns {(261 *   Promise<Output | undefined | void> |262 *   Promise<never> | // For some reason this is needed separately.263 *   Output |264 *   Error |265 *   undefined |266 *   void267 * )}268 *   If you accept `next`, nothing.269 *   Otherwise:270 *271 *   *   `Error` — fatal error to stop the process272 *   *   `Promise<undefined>` or `undefined` — the next transformer keeps using273 *       same tree274 *   *   `Promise<Node>` or `Node` — new, changed, tree275 */276 277/**278 * @template {Node | undefined} ParseTree279 *   Output of `parse`.280 * @template {Node | undefined} HeadTree281 *   Input for `run`.282 * @template {Node | undefined} TailTree283 *   Output for `run`.284 * @template {Node | undefined} CompileTree285 *   Input of `stringify`.286 * @template {CompileResults | undefined} CompileResult287 *   Output of `stringify`.288 * @template {Node | string | undefined} Input289 *   Input of plugin.290 * @template Output291 *   Output of plugin (optional).292 * @typedef {(293 *   Input extends string294 *     ? Output extends Node | undefined295 *       ? // Parser.296 *         Processor<297 *           Output extends undefined ? ParseTree : Output,298 *           HeadTree,299 *           TailTree,300 *           CompileTree,301 *           CompileResult302 *         >303 *       : // Unknown.304 *         Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>305 *     : Output extends CompileResults306 *     ? Input extends Node | undefined307 *       ? // Compiler.308 *         Processor<309 *           ParseTree,310 *           HeadTree,311 *           TailTree,312 *           Input extends undefined ? CompileTree : Input,313 *           Output extends undefined ? CompileResult : Output314 *         >315 *       : // Unknown.316 *         Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>317 *     : Input extends Node | undefined318 *     ? Output extends Node | undefined319 *       ? // Transform.320 *         Processor<321 *           ParseTree,322 *           HeadTree extends undefined ? Input : HeadTree,323 *           Output extends undefined ? TailTree : Output,324 *           CompileTree,325 *           CompileResult326 *         >327 *       : // Unknown.328 *         Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>329 *     : // Unknown.330 *       Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>331 * )} UsePlugin332 *   Create a processor based on the input/output of a {@link Plugin plugin}.333 */334 335/**336 * @template {CompileResults | undefined} Result337 *   Node type that the transformer yields.338 * @typedef {(339 *   Result extends Value | undefined ?340 *     VFile :341 *     VFile & {result: Result}342 *   )} VFileWithOutput343 *   Type to generate a {@linkcode VFile} corresponding to a compiler result.344 *345 *   If a result that is not acceptable on a `VFile` is used, that will346 *   be stored on the `result` field of {@linkcode VFile}.347 */348 349import {bail} from 'bail'350import extend from 'extend'351import {ok as assert} from 'devlop'352import isPlainObj from 'is-plain-obj'353import {trough} from 'trough'354import {VFile} from 'vfile'355import {CallableInstance} from './callable-instance.js'356 357// To do: next major: drop `Compiler`, `Parser`: prefer lowercase.358 359// To do: we could start yielding `never` in TS when a parser is missing and360// `parse` is called.361// Currently, we allow directly setting `processor.parser`, which is untyped.362 363const own = {}.hasOwnProperty364 365/**366 * @template {Node | undefined} [ParseTree=undefined]367 *   Output of `parse` (optional).368 * @template {Node | undefined} [HeadTree=undefined]369 *   Input for `run` (optional).370 * @template {Node | undefined} [TailTree=undefined]371 *   Output for `run` (optional).372 * @template {Node | undefined} [CompileTree=undefined]373 *   Input of `stringify` (optional).374 * @template {CompileResults | undefined} [CompileResult=undefined]375 *   Output of `stringify` (optional).376 * @extends {CallableInstance<[], Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>>}377 */378export class Processor extends CallableInstance {379  /**380   * Create a processor.381   */382  constructor() {383    // If `Processor()` is called (w/o new), `copy` is called instead.384    super('copy')385 386    /**387     * Compiler to use (deprecated).388     *389     * @deprecated390     *   Use `compiler` instead.391     * @type {(392     *   Compiler<393     *     CompileTree extends undefined ? Node : CompileTree,394     *     CompileResult extends undefined ? CompileResults : CompileResult395     *   > |396     *   undefined397     * )}398     */399    this.Compiler = undefined400 401    /**402     * Parser to use (deprecated).403     *404     * @deprecated405     *   Use `parser` instead.406     * @type {(407     *   Parser<ParseTree extends undefined ? Node : ParseTree> |408     *   undefined409     * )}410     */411    this.Parser = undefined412 413    // Note: the following fields are considered private.414    // However, they are needed for tests, and TSC generates an untyped415    // `private freezeIndex` field for, which trips `type-coverage` up.416    // Instead, we use `@deprecated` to visualize that they shouldn’t be used.417    /**418     * Internal list of configured plugins.419     *420     * @deprecated421     *   This is a private internal property and should not be used.422     * @type {Array<PluginTuple<Array<unknown>>>}423     */424    this.attachers = []425 426    /**427     * Compiler to use.428     *429     * @type {(430     *   Compiler<431     *     CompileTree extends undefined ? Node : CompileTree,432     *     CompileResult extends undefined ? CompileResults : CompileResult433     *   > |434     *   undefined435     * )}436     */437    this.compiler = undefined438 439    /**440     * Internal state to track where we are while freezing.441     *442     * @deprecated443     *   This is a private internal property and should not be used.444     * @type {number}445     */446    this.freezeIndex = -1447 448    /**449     * Internal state to track whether we’re frozen.450     *451     * @deprecated452     *   This is a private internal property and should not be used.453     * @type {boolean | undefined}454     */455    this.frozen = undefined456 457    /**458     * Internal state.459     *460     * @deprecated461     *   This is a private internal property and should not be used.462     * @type {Data}463     */464    this.namespace = {}465 466    /**467     * Parser to use.468     *469     * @type {(470     *   Parser<ParseTree extends undefined ? Node : ParseTree> |471     *   undefined472     * )}473     */474    this.parser = undefined475 476    /**477     * Internal list of configured transformers.478     *479     * @deprecated480     *   This is a private internal property and should not be used.481     * @type {Pipeline}482     */483    this.transformers = trough()484  }485 486  /**487   * Copy a processor.488   *489   * @deprecated490   *   This is a private internal method and should not be used.491   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}492   *   New *unfrozen* processor ({@linkcode Processor}) that is493   *   configured to work the same as its ancestor.494   *   When the descendant processor is configured in the future it does not495   *   affect the ancestral processor.496   */497  copy() {498    // Cast as the type parameters will be the same after attaching.499    const destination =500      /** @type {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>} */ (501        new Processor()502      )503    let index = -1504 505    while (++index < this.attachers.length) {506      const attacher = this.attachers[index]507      destination.use(...attacher)508    }509 510    destination.data(extend(true, {}, this.namespace))511 512    return destination513  }514 515  /**516   * Configure the processor with info available to all plugins.517   * Information is stored in an object.518   *519   * Typically, options can be given to a specific plugin, but sometimes it520   * makes sense to have information shared with several plugins.521   * For example, a list of HTML elements that are self-closing, which is522   * needed during all phases.523   *524   * > **Note**: setting information cannot occur on *frozen* processors.525   * > Call the processor first to create a new unfrozen processor.526   *527   * > **Note**: to register custom data in TypeScript, augment the528   * > {@linkcode Data} interface.529   *530   * @example531   *   This example show how to get and set info:532   *533   *   ```js534   *   import {unified} from 'unified'535   *536   *   const processor = unified().data('alpha', 'bravo')537   *538   *   processor.data('alpha') // => 'bravo'539   *540   *   processor.data() // => {alpha: 'bravo'}541   *542   *   processor.data({charlie: 'delta'})543   *544   *   processor.data() // => {charlie: 'delta'}545   *   ```546   *547   * @template {keyof Data} Key548   *549   * @overload550   * @returns {Data}551   *552   * @overload553   * @param {Data} dataset554   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}555   *556   * @overload557   * @param {Key} key558   * @returns {Data[Key]}559   *560   * @overload561   * @param {Key} key562   * @param {Data[Key]} value563   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}564   *565   * @param {Data | Key} [key]566   *   Key to get or set, or entire dataset to set, or nothing to get the567   *   entire dataset (optional).568   * @param {Data[Key]} [value]569   *   Value to set (optional).570   * @returns {unknown}571   *   The current processor when setting, the value at `key` when getting, or572   *   the entire dataset when getting without key.573   */574  data(key, value) {575    if (typeof key === 'string') {576      // Set `key`.577      if (arguments.length === 2) {578        assertUnfrozen('data', this.frozen)579        this.namespace[key] = value580        return this581      }582 583      // Get `key`.584      return (own.call(this.namespace, key) && this.namespace[key]) || undefined585    }586 587    // Set space.588    if (key) {589      assertUnfrozen('data', this.frozen)590      this.namespace = key591      return this592    }593 594    // Get space.595    return this.namespace596  }597 598  /**599   * Freeze a processor.600   *601   * Frozen processors are meant to be extended and not to be configured602   * directly.603   *604   * When a processor is frozen it cannot be unfrozen.605   * New processors working the same way can be created by calling the606   * processor.607   *608   * It’s possible to freeze processors explicitly by calling `.freeze()`.609   * Processors freeze automatically when `.parse()`, `.run()`, `.runSync()`,610   * `.stringify()`, `.process()`, or `.processSync()` are called.611   *612   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}613   *   The current processor.614   */615  freeze() {616    if (this.frozen) {617      return this618    }619 620    // Cast so that we can type plugins easier.621    // Plugins are supposed to be usable on different processors, not just on622    // this exact processor.623    const self = /** @type {Processor} */ (/** @type {unknown} */ (this))624 625    while (++this.freezeIndex < this.attachers.length) {626      const [attacher, ...options] = this.attachers[this.freezeIndex]627 628      if (options[0] === false) {629        continue630      }631 632      if (options[0] === true) {633        options[0] = undefined634      }635 636      const transformer = attacher.call(self, ...options)637 638      if (typeof transformer === 'function') {639        this.transformers.use(transformer)640      }641    }642 643    this.frozen = true644    this.freezeIndex = Number.POSITIVE_INFINITY645 646    return this647  }648 649  /**650   * Parse text to a syntax tree.651   *652   * > **Note**: `parse` freezes the processor if not already *frozen*.653   *654   * > **Note**: `parse` performs the parse phase, not the run phase or other655   * > phases.656   *657   * @param {Compatible | undefined} [file]658   *   file to parse (optional); typically `string` or `VFile`; any value659   *   accepted as `x` in `new VFile(x)`.660   * @returns {ParseTree extends undefined ? Node : ParseTree}661   *   Syntax tree representing `file`.662   */663  parse(file) {664    this.freeze()665    const realFile = vfile(file)666    const parser = this.parser || this.Parser667    assertParser('parse', parser)668    return parser(String(realFile), realFile)669  }670 671  /**672   * Process the given file as configured on the processor.673   *674   * > **Note**: `process` freezes the processor if not already *frozen*.675   *676   * > **Note**: `process` performs the parse, run, and stringify phases.677   *678   * @overload679   * @param {Compatible | undefined} file680   * @param {ProcessCallback<VFileWithOutput<CompileResult>>} done681   * @returns {undefined}682   *683   * @overload684   * @param {Compatible | undefined} [file]685   * @returns {Promise<VFileWithOutput<CompileResult>>}686   *687   * @param {Compatible | undefined} [file]688   *   File (optional); typically `string` or `VFile`]; any value accepted as689   *   `x` in `new VFile(x)`.690   * @param {ProcessCallback<VFileWithOutput<CompileResult>> | undefined} [done]691   *   Callback (optional).692   * @returns {Promise<VFile> | undefined}693   *   Nothing if `done` is given.694   *   Otherwise a promise, rejected with a fatal error or resolved with the695   *   processed file.696   *697   *   The parsed, transformed, and compiled value is available at698   *   `file.value` (see note).699   *700   *   > **Note**: unified typically compiles by serializing: most701   *   > compilers return `string` (or `Uint8Array`).702   *   > Some compilers, such as the one configured with703   *   > [`rehype-react`][rehype-react], return other values (in this case, a704   *   > React tree).705   *   > If you’re using a compiler that doesn’t serialize, expect different706   *   > result values.707   *   >708   *   > To register custom results in TypeScript, add them to709   *   > {@linkcode CompileResultMap}.710   *711   *   [rehype-react]: https://github.com/rehypejs/rehype-react712   */713  process(file, done) {714    const self = this715 716    this.freeze()717    assertParser('process', this.parser || this.Parser)718    assertCompiler('process', this.compiler || this.Compiler)719 720    return done ? executor(undefined, done) : new Promise(executor)721 722    // Note: `void`s needed for TS.723    /**724     * @param {((file: VFileWithOutput<CompileResult>) => undefined | void) | undefined} resolve725     * @param {(error: Error | undefined) => undefined | void} reject726     * @returns {undefined}727     */728    function executor(resolve, reject) {729      const realFile = vfile(file)730      // Assume `ParseTree` (the result of the parser) matches `HeadTree` (the731      // input of the first transform).732      const parseTree =733        /** @type {HeadTree extends undefined ? Node : HeadTree} */ (734          /** @type {unknown} */ (self.parse(realFile))735        )736 737      self.run(parseTree, realFile, function (error, tree, file) {738        if (error || !tree || !file) {739          return realDone(error)740        }741 742        // Assume `TailTree` (the output of the last transform) matches743        // `CompileTree` (the input of the compiler).744        const compileTree =745          /** @type {CompileTree extends undefined ? Node : CompileTree} */ (746            /** @type {unknown} */ (tree)747          )748 749        const compileResult = self.stringify(compileTree, file)750 751        if (looksLikeAValue(compileResult)) {752          file.value = compileResult753        } else {754          file.result = compileResult755        }756 757        realDone(error, /** @type {VFileWithOutput<CompileResult>} */ (file))758      })759 760      /**761       * @param {Error | undefined} error762       * @param {VFileWithOutput<CompileResult> | undefined} [file]763       * @returns {undefined}764       */765      function realDone(error, file) {766        if (error || !file) {767          reject(error)768        } else if (resolve) {769          resolve(file)770        } else {771          assert(done, '`done` is defined if `resolve` is not')772          done(undefined, file)773        }774      }775    }776  }777 778  /**779   * Process the given file as configured on the processor.780   *781   * An error is thrown if asynchronous transforms are configured.782   *783   * > **Note**: `processSync` freezes the processor if not already *frozen*.784   *785   * > **Note**: `processSync` performs the parse, run, and stringify phases.786   *787   * @param {Compatible | undefined} [file]788   *   File (optional); typically `string` or `VFile`; any value accepted as789   *   `x` in `new VFile(x)`.790   * @returns {VFileWithOutput<CompileResult>}791   *   The processed file.792   *793   *   The parsed, transformed, and compiled value is available at794   *   `file.value` (see note).795   *796   *   > **Note**: unified typically compiles by serializing: most797   *   > compilers return `string` (or `Uint8Array`).798   *   > Some compilers, such as the one configured with799   *   > [`rehype-react`][rehype-react], return other values (in this case, a800   *   > React tree).801   *   > If you’re using a compiler that doesn’t serialize, expect different802   *   > result values.803   *   >804   *   > To register custom results in TypeScript, add them to805   *   > {@linkcode CompileResultMap}.806   *807   *   [rehype-react]: https://github.com/rehypejs/rehype-react808   */809  processSync(file) {810    /** @type {boolean} */811    let complete = false812    /** @type {VFileWithOutput<CompileResult> | undefined} */813    let result814 815    this.freeze()816    assertParser('processSync', this.parser || this.Parser)817    assertCompiler('processSync', this.compiler || this.Compiler)818 819    this.process(file, realDone)820    assertDone('processSync', 'process', complete)821    assert(result, 'we either bailed on an error or have a tree')822 823    return result824 825    /**826     * @type {ProcessCallback<VFileWithOutput<CompileResult>>}827     */828    function realDone(error, file) {829      complete = true830      bail(error)831      result = file832    }833  }834 835  /**836   * Run *transformers* on a syntax tree.837   *838   * > **Note**: `run` freezes the processor if not already *frozen*.839   *840   * > **Note**: `run` performs the run phase, not other phases.841   *842   * @overload843   * @param {HeadTree extends undefined ? Node : HeadTree} tree844   * @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done845   * @returns {undefined}846   *847   * @overload848   * @param {HeadTree extends undefined ? Node : HeadTree} tree849   * @param {Compatible | undefined} file850   * @param {RunCallback<TailTree extends undefined ? Node : TailTree>} done851   * @returns {undefined}852   *853   * @overload854   * @param {HeadTree extends undefined ? Node : HeadTree} tree855   * @param {Compatible | undefined} [file]856   * @returns {Promise<TailTree extends undefined ? Node : TailTree>}857   *858   * @param {HeadTree extends undefined ? Node : HeadTree} tree859   *   Tree to transform and inspect.860   * @param {(861   *   RunCallback<TailTree extends undefined ? Node : TailTree> |862   *   Compatible863   * )} [file]864   *   File associated with `node` (optional); any value accepted as `x` in865   *   `new VFile(x)`.866   * @param {RunCallback<TailTree extends undefined ? Node : TailTree>} [done]867   *   Callback (optional).868   * @returns {Promise<TailTree extends undefined ? Node : TailTree> | undefined}869   *   Nothing if `done` is given.870   *   Otherwise, a promise rejected with a fatal error or resolved with the871   *   transformed tree.872   */873  run(tree, file, done) {874    assertNode(tree)875    this.freeze()876 877    const transformers = this.transformers878 879    if (!done && typeof file === 'function') {880      done = file881      file = undefined882    }883 884    return done ? executor(undefined, done) : new Promise(executor)885 886    // Note: `void`s needed for TS.887    /**888     * @param {(889     *   ((tree: TailTree extends undefined ? Node : TailTree) => undefined | void) |890     *   undefined891     * )} resolve892     * @param {(error: Error) => undefined | void} reject893     * @returns {undefined}894     */895    function executor(resolve, reject) {896      assert(897        typeof file !== 'function',898        '`file` can’t be a `done` anymore, we checked'899      )900      const realFile = vfile(file)901      transformers.run(tree, realFile, realDone)902 903      /**904       * @param {Error | undefined} error905       * @param {Node} outputTree906       * @param {VFile} file907       * @returns {undefined}908       */909      function realDone(error, outputTree, file) {910        const resultingTree =911          /** @type {TailTree extends undefined ? Node : TailTree} */ (912            outputTree || tree913          )914 915        if (error) {916          reject(error)917        } else if (resolve) {918          resolve(resultingTree)919        } else {920          assert(done, '`done` is defined if `resolve` is not')921          done(undefined, resultingTree, file)922        }923      }924    }925  }926 927  /**928   * Run *transformers* on a syntax tree.929   *930   * An error is thrown if asynchronous transforms are configured.931   *932   * > **Note**: `runSync` freezes the processor if not already *frozen*.933   *934   * > **Note**: `runSync` performs the run phase, not other phases.935   *936   * @param {HeadTree extends undefined ? Node : HeadTree} tree937   *   Tree to transform and inspect.938   * @param {Compatible | undefined} [file]939   *   File associated with `node` (optional); any value accepted as `x` in940   *   `new VFile(x)`.941   * @returns {TailTree extends undefined ? Node : TailTree}942   *   Transformed tree.943   */944  runSync(tree, file) {945    /** @type {boolean} */946    let complete = false947    /** @type {(TailTree extends undefined ? Node : TailTree) | undefined} */948    let result949 950    this.run(tree, file, realDone)951 952    assertDone('runSync', 'run', complete)953    assert(result, 'we either bailed on an error or have a tree')954    return result955 956    /**957     * @type {RunCallback<TailTree extends undefined ? Node : TailTree>}958     */959    function realDone(error, tree) {960      bail(error)961      result = tree962      complete = true963    }964  }965 966  /**967   * Compile a syntax tree.968   *969   * > **Note**: `stringify` freezes the processor if not already *frozen*.970   *971   * > **Note**: `stringify` performs the stringify phase, not the run phase972   * > or other phases.973   *974   * @param {CompileTree extends undefined ? Node : CompileTree} tree975   *   Tree to compile.976   * @param {Compatible | undefined} [file]977   *   File associated with `node` (optional); any value accepted as `x` in978   *   `new VFile(x)`.979   * @returns {CompileResult extends undefined ? Value : CompileResult}980   *   Textual representation of the tree (see note).981   *982   *   > **Note**: unified typically compiles by serializing: most compilers983   *   > return `string` (or `Uint8Array`).984   *   > Some compilers, such as the one configured with985   *   > [`rehype-react`][rehype-react], return other values (in this case, a986   *   > React tree).987   *   > If you’re using a compiler that doesn’t serialize, expect different988   *   > result values.989   *   >990   *   > To register custom results in TypeScript, add them to991   *   > {@linkcode CompileResultMap}.992   *993   *   [rehype-react]: https://github.com/rehypejs/rehype-react994   */995  stringify(tree, file) {996    this.freeze()997    const realFile = vfile(file)998    const compiler = this.compiler || this.Compiler999    assertCompiler('stringify', compiler)1000    assertNode(tree)1001 1002    return compiler(tree, realFile)1003  }1004 1005  /**1006   * Configure the processor to use a plugin, a list of usable values, or a1007   * preset.1008   *1009   * If the processor is already using a plugin, the previous plugin1010   * configuration is changed based on the options that are passed in.1011   * In other words, the plugin is not added a second time.1012   *1013   * > **Note**: `use` cannot be called on *frozen* processors.1014   * > Call the processor first to create a new unfrozen processor.1015   *1016   * @example1017   *   There are many ways to pass plugins to `.use()`.1018   *   This example gives an overview:1019   *1020   *   ```js1021   *   import {unified} from 'unified'1022   *1023   *   unified()1024   *     // Plugin with options:1025   *     .use(pluginA, {x: true, y: true})1026   *     // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):1027   *     .use(pluginA, {y: false, z: true})1028   *     // Plugins:1029   *     .use([pluginB, pluginC])1030   *     // Two plugins, the second with options:1031   *     .use([pluginD, [pluginE, {}]])1032   *     // Preset with plugins and settings:1033   *     .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})1034   *     // Settings only:1035   *     .use({settings: {position: false}})1036   *   ```1037   *1038   * @template {Array<unknown>} [Parameters=[]]1039   * @template {Node | string | undefined} [Input=undefined]1040   * @template [Output=Input]1041   *1042   * @overload1043   * @param {Preset | null | undefined} [preset]1044   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}1045   *1046   * @overload1047   * @param {PluggableList} list1048   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}1049   *1050   * @overload1051   * @param {Plugin<Parameters, Input, Output>} plugin1052   * @param {...(Parameters | [boolean])} parameters1053   * @returns {UsePlugin<ParseTree, HeadTree, TailTree, CompileTree, CompileResult, Input, Output>}1054   *1055   * @param {PluggableList | Plugin | Preset | null | undefined} value1056   *   Usable value.1057   * @param {...unknown} parameters1058   *   Parameters, when a plugin is given as a usable value.1059   * @returns {Processor<ParseTree, HeadTree, TailTree, CompileTree, CompileResult>}1060   *   Current processor.1061   */1062  use(value, ...parameters) {1063    const attachers = this.attachers1064    const namespace = this.namespace1065 1066    assertUnfrozen('use', this.frozen)1067 1068    if (value === null || value === undefined) {1069      // Empty.1070    } else if (typeof value === 'function') {1071      addPlugin(value, parameters)1072    } else if (typeof value === 'object') {1073      if (Array.isArray(value)) {1074        addList(value)1075      } else {1076        addPreset(value)1077      }1078    } else {1079      throw new TypeError('Expected usable value, not `' + value + '`')1080    }1081 1082    return this1083 1084    /**1085     * @param {Pluggable} value1086     * @returns {undefined}1087     */1088    function add(value) {1089      if (typeof value === 'function') {1090        addPlugin(value, [])1091      } else if (typeof value === 'object') {1092        if (Array.isArray(value)) {1093          const [plugin, ...parameters] =1094            /** @type {PluginTuple<Array<unknown>>} */ (value)1095          addPlugin(plugin, parameters)1096        } else {1097          addPreset(value)1098        }1099      } else {1100        throw new TypeError('Expected usable value, not `' + value + '`')1101      }1102    }1103 1104    /**1105     * @param {Preset} result1106     * @returns {undefined}1107     */1108    function addPreset(result) {1109      if (!('plugins' in result) && !('settings' in result)) {1110        throw new Error(1111          'Expected usable value but received an empty preset, which is probably a mistake: presets typically come with `plugins` and sometimes with `settings`, but this has neither'1112        )1113      }1114 1115      addList(result.plugins)1116 1117      if (result.settings) {1118        namespace.settings = extend(true, namespace.settings, result.settings)1119      }1120    }1121 1122    /**1123     * @param {PluggableList | null | undefined} plugins1124     * @returns {undefined}1125     */1126    function addList(plugins) {1127      let index = -11128 1129      if (plugins === null || plugins === undefined) {1130        // Empty.1131      } else if (Array.isArray(plugins)) {1132        while (++index < plugins.length) {1133          const thing = plugins[index]1134          add(thing)1135        }1136      } else {1137        throw new TypeError('Expected a list of plugins, not `' + plugins + '`')1138      }1139    }1140 1141    /**1142     * @param {Plugin} plugin1143     * @param {Array<unknown>} parameters1144     * @returns {undefined}1145     */1146    function addPlugin(plugin, parameters) {1147      let index = -11148      let entryIndex = -11149 1150      while (++index < attachers.length) {1151        if (attachers[index][0] === plugin) {1152          entryIndex = index1153          break1154        }1155      }1156 1157      if (entryIndex === -1) {1158        attachers.push([plugin, ...parameters])1159      }1160      // Only set if there was at least a `primary` value, otherwise we’d change1161      // `arguments.length`.1162      else if (parameters.length > 0) {1163        let [primary, ...rest] = parameters1164        const currentPrimary = attachers[entryIndex][1]1165        if (isPlainObj(currentPrimary) && isPlainObj(primary)) {1166          primary = extend(true, currentPrimary, primary)1167        }1168 1169        attachers[entryIndex] = [plugin, primary, ...rest]1170      }1171    }1172  }1173}1174 1175// Note: this returns a *callable* instance.1176// That’s why it’s documented as a function.1177/**1178 * Create a new processor.1179 *1180 * @example1181 *   This example shows how a new processor can be created (from `remark`) and linked1182 *   to **stdin**(4) and **stdout**(4).1183 *1184 *   ```js1185 *   import process from 'node:process'1186 *   import concatStream from 'concat-stream'1187 *   import {remark} from 'remark'1188 *1189 *   process.stdin.pipe(1190 *     concatStream(function (buf) {1191 *       process.stdout.write(String(remark().processSync(buf)))1192 *     })1193 *   )1194 *   ```1195 *1196 * @returns1197 *   New *unfrozen* processor (`processor`).1198 *1199 *   This processor is configured to work the same as its ancestor.1200 *   When the descendant processor is configured in the future it does not

Showing the first 1,200 of 1324 lines. Download the file for the rest.