/* MIT License http://www.opensource.org/licenses/mit-license.php Author Tobias Koppers @sokra */ "use strict"; const util = require("util"); // eslint-disable-next-line jsdoc/reject-function-type /** @typedef {Function} EXPECTED_FUNCTION */ // eslint-disable-next-line jsdoc/reject-any-type /** @typedef {any} EXPECTED_ANY */ /** @typedef {Record} EXPECTED_OBJECT */ /** * @template T * @typedef {T extends EXPECTED_ANY[] ? T : [T]} AsArray */ /** * @template {number} T * @typedef {T extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 ? T : never} Measure */ /** * @template {EXPECTED_ANY[]} T * @template U * @typedef {{ * 0: [U]; * 1: [T[0], U]; * 2: [T[0], T[1], U]; * 3: [T[0], T[1], T[2], U]; * 4: [T[0], T[1], T[2], T[3], U]; * 5: [T[0], T[1], T[2], T[3], T[4], U]; * 6: [T[0], T[1], T[2], T[3], T[4], T[5], U]; * 7: [T[0], T[1], T[2], T[3], T[4], T[5], T[6], U]; * 8: [T[0], T[1], T[2], T[3], T[4], T[5], T[6], T[7], U]; * }[Measure]} Append */ /* eslint-disable jsdoc/ts-no-empty-object-type */ /** * @template X * @typedef {X extends UnsetAdditionalOptions ? { } : X} IfSet */ /* eslint-enable jsdoc/ts-no-empty-object-type */ /** * @template {number} T * @template U * @typedef {T extends 0 ? void[] : ReadonlyArray & { 0: U, length: T }} FixedSizeArray */ /** * @template {EXPECTED_ANY[]} T * @typedef {FixedSizeArray} ArgumentNames */ /** * @typedef {object} TapOptions * @property {string=} before name of an earlier tap to insert this tap before * @property {number=} stage stage to schedule the tap in (lower runs earlier) */ /** * @typedef {TapOptions & { name: string }} Tap */ /** * @typedef {Tap & { type: "sync" | "async" | "promise", fn: EXPECTED_FUNCTION }} FullTap */ /** * @template E, T * @typedef {(error: E | null, result?: T) => void} Callback */ /** * @template E, T * @typedef {(error?: E | null | false, result?: T) => void} InnerCallback */ // TODO remove context in the next major release, deprecated /** * @template T * @template R * @template [AdditionalOptions=UnsetAdditionalOptions] * @typedef {object} HookInterceptor * @property {string=} name optional name of the interceptor * @property {((tap: FullTap & IfSet) => void)=} tap called for each tap before it runs * @property {((...args: EXPECTED_ANY[]) => void)=} call called when the hook is called * @property {((...args: EXPECTED_ANY[]) => void)=} loop called for each loop iteration of looping hooks * @property {((err: Error) => void)=} error called when an error occurs * @property {((result: R) => void)=} result called with the hook's result * @property {(() => void)=} done called when the hook is fully done * @property {((tap: FullTap & IfSet) => FullTap & IfSet)=} register called whenever a tap is registered * @property {boolean=} context true to pass a `_context` argument to interceptor callbacks */ /** * @typedef {object} UnsetAdditionalOptions * @property {true} _UnsetAdditionalOptions unset */ /** * @template T * @template R * @template [AdditionalOptions=UnsetAdditionalOptions] * @typedef {object} CompileOptions * @property {FullTap[]} taps the registered taps * @property {HookInterceptor[]} interceptors the registered interceptors * @property {ArgumentNames>} args names of the hook arguments (used for code generation) * @property {"sync" | "async" | "promise"} type call type */ const deprecateContext = util.deprecate( () => {}, "Hook.context is deprecated and will be removed" ); /** * @template T, R * @callback CallDelegate * @param {...AsArray} args * @returns {R} */ /** * @template T, R * @type {CallDelegate} * @this {Hook} */ function CALL_DELEGATE(...args) { // @ts-expect-error for performance reasons this.call = this._createCall("sync"); // @ts-expect-error for performance reasons return this.call(...args); } /** * @template T, R * @callback CallAsyncDelegate * @param {...Append, Callback>} args * @returns void */ /** * @template T, R * @type {CallAsyncDelegate} * @this {Hook} */ function CALL_ASYNC_DELEGATE(...args) { // @ts-expect-error for performance reasons this.callAsync = this._createCall("async"); return this.callAsync(...args); } /** * @template T, R * @callback PromiseDeledate * @param {...AsArray} args * @returns {Promise} */ /** * @template T, R * @type {PromiseDeledate} * @this {Hook} */ function PROMISE_DELEGATE(...args) { // @ts-expect-error for performance reasons this.promise = this._createCall("promise"); return this.promise(...args); } /** * @template T * @template R * @template [AdditionalOptions=UnsetAdditionalOptions] */ class Hook { /** * @param {ArgumentNames>=} args argument names of the hook (used for code generation) * @param {string=} name name of the hook */ constructor( args = /** @type {ArgumentNames>} */ ( /** @type {unknown} */ ([]) ), name = undefined ) { /** * @private * @type {ArgumentNames>} */ this._args = args; /** @type {string | undefined} */ this.name = name; /** @type {FullTap[]} */ this.taps = []; /** @type {HookInterceptor[]} */ this.interceptors = []; /** * @private * @type {CallDelegate | undefined} */ this._call = CALL_DELEGATE; /** @type {CallDelegate | undefined} */ this.call = CALL_DELEGATE; /** * @private * @type {CallAsyncDelegate} */ this._callAsync = CALL_ASYNC_DELEGATE; /** @type {CallAsyncDelegate} */ this.callAsync = CALL_ASYNC_DELEGATE; /** * @private * @type {PromiseDeledate} */ this._promise = PROMISE_DELEGATE; /** @type {PromiseDeledate} */ this.promise = PROMISE_DELEGATE; /** @type {EXPECTED_FUNCTION[] | undefined} */ this._x = undefined; // eslint-disable-next-line no-self-assign this.compile = this.compile; // eslint-disable-next-line no-self-assign this.tap = this.tap; // eslint-disable-next-line no-self-assign this.tapAsync = this.tapAsync; // eslint-disable-next-line no-self-assign this.tapPromise = this.tapPromise; } /** * @abstract * @param {CompileOptions} _options compile options * @returns {EXPECTED_FUNCTION} the compiled call function */ compile(_options) { throw new Error("Abstract: should be overridden"); } /** * @private * @param {"sync" | "async" | "promise"} type the call type * @returns {EXPECTED_FUNCTION} the compiled call function */ _createCall(type) { return this.compile({ taps: this.taps, interceptors: this.interceptors, args: this._args, type }); } /** * @private * @param {"sync" | "async" | "promise"} type the tap type * @param {string | (Tap & IfSet)} options name or full tap options * @param {EXPECTED_FUNCTION} fn callback registered with the tap * @returns {void} */ _tap(type, options, fn) { if (typeof options === "string") { // Fast path: a string options ("name") is by far the most common // case. Build the final descriptor in a single allocation instead // of creating `{ name }` and then `Object.assign`ing it. const name = options.trim(); if (name === "") { throw new Error("Missing name for tap"); } options = /** @type {FullTap & IfSet} */ ({ type, fn, name }); } else { if (typeof options !== "object" || options === null) { throw new Error("Invalid tap options"); } let { name } = options; if (typeof name === "string") { name = name.trim(); } if (typeof name !== "string" || name === "") { throw new Error("Missing name for tap"); } if ( typeof (/** @type {{ context?: unknown }} */ (options).context) !== "undefined" ) { deprecateContext(); } // Fast path: only `name` is set. Build the descriptor as a literal // so `_insert` and downstream consumers see the same hidden class // as the string-options path, avoiding a polymorphic call site. // Scan with `for...in` (cheaper than allocating `Object.keys`) // to verify no other user-provided properties exist - e.g. // webpack's `additionalAssets` - otherwise they'd be dropped. let onlyName = true; for (const key in options) { if (key !== "name") { onlyName = false; break; } } if (onlyName) { options = /** @type {FullTap & IfSet} */ ({ type, fn, name }); } else { options.name = name; // Preserve previous precedence: user-provided keys win over the internal `type`/`fn`. options = Object.assign({ type, fn }, options); } } options = this._runRegisterInterceptors( /** @type {FullTap & IfSet} */ (options) ); this._insert( /** @type {FullTap & IfSet} */ (options) ); } /** * @param {string | (Tap & IfSet)} options tap name or full tap options * @param {(...args: AsArray) => R} fn the function to register * @returns {void} */ tap(options, fn) { this._tap("sync", options, fn); } /** * @param {string | (Tap & IfSet)} options tap name or full tap options * @param {(...args: Append, InnerCallback>) => void} fn the function to register * @returns {void} */ tapAsync(options, fn) { this._tap("async", options, fn); } /** * @param {string | (Tap & IfSet)} options tap name or full tap options * @param {(...args: AsArray) => Promise} fn the function to register * @returns {void} */ tapPromise(options, fn) { this._tap("promise", options, fn); } /** * @private * @param {FullTap & IfSet} options the tap descriptor * @returns {FullTap & IfSet} possibly transformed options */ _runRegisterInterceptors(options) { const { interceptors } = this; const { length } = interceptors; // Common case: no interceptors. if (length === 0) return options; for (let i = 0; i < length; i++) { const interceptor = interceptors[i]; if (interceptor.register) { const newOptions = interceptor.register(options); if (newOptions !== undefined) { options = newOptions; } } } return options; } /** * @param {TapOptions & IfSet} options the options to merge into each tap * @returns {Omit} a wrapper that pre-applies the options */ withOptions(options) { /** * @param {string | (TapOptions & IfSet)} opt options * @returns {Tap & IfSet} merged options */ const mergeOptions = (opt) => /** @type {Tap & IfSet} */ ( Object.assign( {}, options, typeof opt === "string" ? { name: opt } : opt ) ); return /** @type {Omit} */ ({ name: this.name, tap: (opt, fn) => this.tap(mergeOptions(opt), fn), tapAsync: (opt, fn) => this.tapAsync(mergeOptions(opt), fn), tapPromise: (opt, fn) => this.tapPromise(mergeOptions(opt), fn), intercept: (interceptor) => this.intercept(interceptor), isUsed: () => this.isUsed(), withOptions: (opt) => this.withOptions(mergeOptions(opt)) }); } /** * @returns {boolean} true if the hook has any taps or interceptors registered */ isUsed() { return this.taps.length > 0 || this.interceptors.length > 0; } /** * @param {HookInterceptor} interceptor the interceptor to register * @returns {void} */ intercept(interceptor) { this._resetCompilation(); this.interceptors.push(Object.assign({}, interceptor)); if (interceptor.register) { for (let i = 0; i < this.taps.length; i++) { this.taps[i] = interceptor.register( /** @type {FullTap & IfSet} */ (this.taps[i]) ); } } } /** * @private * @returns {void} */ _resetCompilation() { this.call = this._call; this.callAsync = this._callAsync; this.promise = this._promise; } /** * @private * @param {FullTap & IfSet} item the tap to insert into the ordered taps list * @returns {void} */ _insert(item) { this._resetCompilation(); const { taps } = this; const stage = typeof item.stage === "number" ? item.stage : 0; // Fast path: the overwhelmingly common `hook.tap("name", fn)` case // has no `before` and default stage 0. If the list is empty or the // last tap's stage is <= the new item's stage the item belongs at // the end - append in O(1), skipping the Set allocation and the // shift loop. if (!(typeof item.before === "string" || Array.isArray(item.before))) { const n = taps.length; if (n === 0 || (taps[n - 1].stage || 0) <= stage) { taps[n] = item; return; } } /** @type {Set | undefined} */ let before; if (typeof item.before === "string") { before = new Set([item.before]); } else if (Array.isArray(item.before)) { before = new Set(item.before); } let i = taps.length; while (i > 0) { i--; const tap = taps[i]; taps[i + 1] = tap; const xStage = tap.stage || 0; if (before) { if (before.has(tap.name)) { before.delete(tap.name); continue; } if (before.size > 0) { continue; } } if (xStage > stage) { continue; } i++; break; } taps[i] = item; } } Object.setPrototypeOf(Hook.prototype, null); module.exports = Hook;