fix(types): resolve subclass factory return types to specific hook types

claude · claude · commit 49bf9b48f10c · 2026-04-28T13:47:46.000Z
Each subclass factory (SyncHook, AsyncParallelHook, ...) was returning the
generic `Hook&lt;T, R, AdditionalOptions&gt;` type, so consumers calling
`new SyncHook()` got `Hook&lt;...&gt;` from JSDoc-generated types instead of the
specific `SyncHook&lt;...&gt;` declared in the public `tapable.d.ts`.

Mirror the public class declarations: each subclass file gets a typedef
that re-exports the corresponding class from `tapable.d.ts` (with a
`Type` suffix to avoid colliding with the factory function name in scope),
then wires it as the factory's `@returns` and inner cast target.

This keeps the V8 hidden-class optimization intact (still factory
functions, no real `class extends Hook`) while aligning the JSDoc types
with what tapable.d.ts already promises to consumers.
diff --git a/lib/AsyncParallelBailHook.js b/lib/AsyncParallelBailHook.js
@@ -21,6 +21,16 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncParallelBailHook` class declared in `tapable.d.ts` for
+ * use as the factory function's return type, so `new AsyncParallelBailHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template R
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncParallelBailHook<T, R, AdditionalOptions>} AsyncParallelBailHookType
+ */
+
 class AsyncParallelBailHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -107,7 +117,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new AsyncParallelBailHook instance
+ * @returns {AsyncParallelBailHookType<T, R, AdditionalOptions>} a new AsyncParallelBailHook instance
  */
 function AsyncParallelBailHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -119,7 +129,7 @@ function AsyncParallelBailHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {AsyncParallelBailHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/AsyncParallelHook.js b/lib/AsyncParallelHook.js
@@ -21,6 +21,15 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncParallelHook` class declared in `tapable.d.ts` for use
+ * as the factory function's return type, so `new AsyncParallelHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncParallelHook<T, AdditionalOptions>} AsyncParallelHookType
+ */
+
 class AsyncParallelHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -52,7 +61,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, void, AdditionalOptions>} a new AsyncParallelHook instance
+ * @returns {AsyncParallelHookType<T, AdditionalOptions>} a new AsyncParallelHook instance
  */
 function AsyncParallelHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -64,7 +73,7 @@ function AsyncParallelHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, void, AdditionalOptions>} */ (
+	return /** @type {AsyncParallelHookType<T, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/AsyncSeriesBailHook.js b/lib/AsyncSeriesBailHook.js
@@ -21,6 +21,16 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncSeriesBailHook` class declared in `tapable.d.ts` for
+ * use as the factory function's return type, so `new AsyncSeriesBailHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template R
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncSeriesBailHook<T, R, AdditionalOptions>} AsyncSeriesBailHookType
+ */
+
 class AsyncSeriesBailHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -58,7 +68,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new AsyncSeriesBailHook instance
+ * @returns {AsyncSeriesBailHookType<T, R, AdditionalOptions>} a new AsyncSeriesBailHook instance
  */
 function AsyncSeriesBailHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -70,7 +80,7 @@ function AsyncSeriesBailHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {AsyncSeriesBailHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/AsyncSeriesHook.js b/lib/AsyncSeriesHook.js
@@ -21,6 +21,15 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncSeriesHook` class declared in `tapable.d.ts` for use
+ * as the factory function's return type, so `new AsyncSeriesHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncSeriesHook<T, AdditionalOptions>} AsyncSeriesHookType
+ */
+
 class AsyncSeriesHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -52,7 +61,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, void, AdditionalOptions>} a new AsyncSeriesHook instance
+ * @returns {AsyncSeriesHookType<T, AdditionalOptions>} a new AsyncSeriesHook instance
  */
 function AsyncSeriesHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -64,7 +73,7 @@ function AsyncSeriesHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, void, AdditionalOptions>} */ (
+	return /** @type {AsyncSeriesHookType<T, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/AsyncSeriesLoopHook.js b/lib/AsyncSeriesLoopHook.js
@@ -21,6 +21,15 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncSeriesLoopHook` class declared in `tapable.d.ts` for
+ * use as the factory function's return type, so `new AsyncSeriesLoopHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncSeriesLoopHook<T, AdditionalOptions>} AsyncSeriesLoopHookType
+ */
+
 class AsyncSeriesLoopHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -52,7 +61,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, void, AdditionalOptions>} a new AsyncSeriesLoopHook instance
+ * @returns {AsyncSeriesLoopHookType<T, AdditionalOptions>} a new AsyncSeriesLoopHook instance
  */
 function AsyncSeriesLoopHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -64,7 +73,7 @@ function AsyncSeriesLoopHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, void, AdditionalOptions>} */ (
+	return /** @type {AsyncSeriesLoopHookType<T, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/AsyncSeriesWaterfallHook.js b/lib/AsyncSeriesWaterfallHook.js
@@ -21,6 +21,17 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").AsArray<T>} AsArray
  */
 
+/**
+ * Mirror of the `AsyncSeriesWaterfallHook` class declared in `tapable.d.ts`
+ * for use as the factory function's return type, so
+ * `new AsyncSeriesWaterfallHook(...)` resolves to the specific subclass type
+ * instead of the generic `Hook`.
+ * @template T
+ * @template [R=AsArray<T>[0]]
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").AsyncSeriesWaterfallHook<T, R, AdditionalOptions>} AsyncSeriesWaterfallHookType
+ */
+
 class AsyncSeriesWaterfallHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -61,7 +72,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new AsyncSeriesWaterfallHookCodeFactory instance
+ * @returns {AsyncSeriesWaterfallHookType<T, R, AdditionalOptions>} a new AsyncSeriesWaterfallHook instance
  */
 function AsyncSeriesWaterfallHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -76,7 +87,7 @@ function AsyncSeriesWaterfallHook(
 	// @ts-expect-error for performance reasons
 	hook._call = undefined;
 	hook.call = undefined;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {AsyncSeriesWaterfallHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/SyncBailHook.js b/lib/SyncBailHook.js
@@ -22,6 +22,16 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").ArgumentNames<T>} ArgumentNames
  */
 
+/**
+ * Mirror of the `SyncBailHook` class declared in `tapable.d.ts` for use as
+ * the factory function's return type, so `new SyncBailHook(...)` resolves to
+ * the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template R
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").SyncBailHook<T, R, AdditionalOptions>} SyncBailHookType
+ */
+
 class SyncBailHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -68,7 +78,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new AsyncParallelBailHook instance
+ * @returns {SyncBailHookType<T, R, AdditionalOptions>} a new SyncBailHook instance
  */
 function SyncBailHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -79,7 +89,7 @@ function SyncBailHook(
 	hook.tapAsync = TAP_ASYNC;
 	hook.tapPromise = TAP_PROMISE;
 	hook.compile = COMPILE;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {SyncBailHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/SyncHook.js b/lib/SyncHook.js
@@ -22,6 +22,16 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").ArgumentNames<T>} ArgumentNames
  */
 
+/**
+ * Mirror of the `SyncHook` class declared in `tapable.d.ts` for use as the
+ * factory function's return type, so `new SyncHook(...)` resolves to the
+ * specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [R=void]
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").SyncHook<T, R, AdditionalOptions>} SyncHookType
+ */
+
 class SyncHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -63,7 +73,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new SyncHook instance
+ * @returns {SyncHookType<T, R, AdditionalOptions>} a new SyncHook instance
  */
 function SyncHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -74,7 +84,7 @@ function SyncHook(
 	hook.tapAsync = TAP_ASYNC;
 	hook.tapPromise = TAP_PROMISE;
 	hook.compile = COMPILE;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {SyncHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/SyncLoopHook.js b/lib/SyncLoopHook.js
@@ -21,6 +21,15 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").ArgumentNames<T>} ArgumentNames
  */
 
+/**
+ * Mirror of the `SyncLoopHook` class declared in `tapable.d.ts` for use as
+ * the factory function's return type, so `new SyncLoopHook(...)` resolves
+ * to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").SyncLoopHook<T, AdditionalOptions>} SyncLoopHookType
+ */
+
 class SyncLoopHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -61,7 +70,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, void, AdditionalOptions>} a new AsyncParallelBailHook instance
+ * @returns {SyncLoopHookType<T, AdditionalOptions>} a new SyncLoopHook instance
  */
 function SyncLoopHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -72,7 +81,7 @@ function SyncLoopHook(
 	hook.tapAsync = TAP_ASYNC;
 	hook.tapPromise = TAP_PROMISE;
 	hook.compile = COMPILE;
-	return /** @type {Hook<T, void, AdditionalOptions>} */ (
+	return /** @type {SyncLoopHookType<T, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
diff --git a/lib/SyncWaterfallHook.js b/lib/SyncWaterfallHook.js
@@ -21,6 +21,16 @@ const HookCodeFactory = require("./HookCodeFactory");
  * @typedef {import("./Hook").ArgumentNames<T>} ArgumentNames
  */
 
+/**
+ * Mirror of the `SyncWaterfallHook` class declared in `tapable.d.ts` for use
+ * as the factory function's return type, so `new SyncWaterfallHook(...)`
+ * resolves to the specific subclass type instead of the generic `Hook`.
+ * @template T
+ * @template [R=AsArray<T>[0]]
+ * @template [AdditionalOptions=UnsetAdditionalOptions]
+ * @typedef {import("../tapable").SyncWaterfallHook<T, R, AdditionalOptions>} SyncWaterfallHookType
+ */
+
 class SyncWaterfallHookCodeFactory extends HookCodeFactory {
 	/**
 	 * @param {ContentOptions} options content generation options
@@ -71,7 +81,7 @@ function COMPILE(options) {
  * @template [AdditionalOptions=UnsetAdditionalOptions]
  * @param {ArgumentNames<AsArray<T>>=} args argument names of the hook
  * @param {string=} name name of the hook
- * @returns {Hook<T, R, AdditionalOptions>} a new AsyncParallelBailHook instance
+ * @returns {SyncWaterfallHookType<T, R, AdditionalOptions>} a new SyncWaterfallHook instance
  */
 function SyncWaterfallHook(
 	args = /** @type {ArgumentNames<AsArray<T>>} */ (/** @type {unknown} */ ([])),
@@ -85,7 +95,7 @@ function SyncWaterfallHook(
 	hook.tapAsync = TAP_ASYNC;
 	hook.tapPromise = TAP_PROMISE;
 	hook.compile = COMPILE;
-	return /** @type {Hook<T, R, AdditionalOptions>} */ (
+	return /** @type {SyncWaterfallHookType<T, R, AdditionalOptions>} */ (
 		/** @type {unknown} */ (hook)
 	);
 }
