Migrate hooks package to TypeScript (#70488)

im3dabasia · im3dabasia · manzoorwanijk · cbravobernal · commit 90747a19f680 · 2025-07-15T13:07:44.000+02:00
Co-authored-by: im3dabasia &lt;im3dabasia1@git.wordpress.org&gt;
Co-authored-by: manzoorwanijk &lt;manzoorwanijk@git.wordpress.org&gt;
diff --git a/packages/hooks/src/createAddHook.ts b/packages/hooks/src/createAddHook.ts
@@ -1,29 +1,43 @@
 /**
  * Internal dependencies
  */
-import validateNamespace from './validateNamespace.js';
-import validateHookName from './validateHookName.js';
+import validateNamespace from './validateNamespace';
+import validateHookName from './validateHookName';
+import type { Callback, Hooks, StoreKey } from '.';
+import type { Handler, HookInfo } from './types';
 
 /**
- * @callback AddHook
  *
  * Adds the hook to the appropriate hooks container.
- *
- * @param {string}               hookName      Name of hook to add
- * @param {string}               namespace     The unique namespace identifying the callback in the form `vendor/plugin/function`.
- * @param {import('.').Callback} callback      Function to call when the hook is run
- * @param {number}               [priority=10] Priority of this hook
  */
+export type AddHook = (
+	/**
+	 * Name of hook to add
+	 */
+	hookName: string,
+	/**
+	 * The unique namespace identifying the callback in the form.
+	 */
+	namespace: string,
+	/**
+	 * Function to call when the hook is run.
+	 */
+	callback: Callback,
+	/**
+	 * Priority of this hook
+	 */
+	priority?: number
+) => void;
 
 /**
  * Returns a function which, when invoked, will add a hook.
  *
- * @param {import('.').Hooks}    hooks    Hooks instance.
- * @param {import('.').StoreKey} storeKey
+ * @param hooks    Hooks instance.
+ * @param storeKey
  *
- * @return {AddHook} Function that adds a new hook.
+ * @return  Function that adds a new hook.
  */
-function createAddHook( hooks, storeKey ) {
+function createAddHook( hooks: Hooks, storeKey: StoreKey ): AddHook {
 	return function addHook( hookName, namespace, callback, priority = 10 ) {
 		const hooksStore = hooks[ storeKey ];
 
@@ -50,14 +64,13 @@ function createAddHook( hooks, storeKey ) {
 			return;
 		}
 
-		const handler = { callback, priority, namespace };
+		const handler: Handler = { callback, priority, namespace };
 
 		if ( hooksStore[ hookName ] ) {
 			// Find the correct insert index of the new hook.
 			const handlers = hooksStore[ hookName ].handlers;
 
-			/** @type {number} */
-			let i;
+			let i: number;
 			for ( i = handlers.length; i > 0; i-- ) {
 				if ( priority >= handlers[ i - 1 ].priority ) {
 					break;
@@ -76,7 +89,7 @@ function createAddHook( hooks, storeKey ) {
 			// we're adding would come after the current callback, there's no
 			// problem; otherwise we need to increase the execution index of
 			// any other runs by 1 to account for the added element.
-			hooksStore.__current.forEach( ( hookInfo ) => {
+			hooksStore.__current.forEach( ( hookInfo: HookInfo ) => {
 				if (
 					hookInfo.name === hookName &&
 					hookInfo.currentIndex >= i
diff --git a/packages/hooks/src/createCurrentHook.ts b/packages/hooks/src/createCurrentHook.ts
@@ -1,14 +1,22 @@
+/**
+ * Internal dependencies
+ */
+import type { Hooks, StoreKey } from './types';
+
 /**
  * Returns a function which, when invoked, will return the name of the
  * currently running hook, or `null` if no hook of the given type is currently
  * running.
  *
- * @param {import('.').Hooks}    hooks    Hooks instance.
- * @param {import('.').StoreKey} storeKey
+ * @param hooks    Hooks instance.
+ * @param storeKey
  *
- * @return {() => string | null} Function that returns the current hook name or null.
+ * @return Function that returns the current hook name or null.
  */
-function createCurrentHook( hooks, storeKey ) {
+function createCurrentHook(
+	hooks: Hooks,
+	storeKey: StoreKey
+): () => string | null {
 	return function currentHook() {
 		const hooksStore = hooks[ storeKey ];
 		const currentArray = Array.from( hooksStore.__current );
diff --git a/packages/hooks/src/createDidHook.ts b/packages/hooks/src/createDidHook.ts
@@ -1,28 +1,31 @@
 /**
  * Internal dependencies
  */
-import validateHookName from './validateHookName.js';
+import validateHookName from './validateHookName';
+import type { Hooks, StoreKey } from './types';
 
 /**
- * @callback DidHook
  *
  * Returns the number of times an action has been fired.
  *
- * @param {string} hookName The hook name to check.
- *
- * @return {number | undefined} The number of times the hook has run.
  */
+export type DidHook = (
+	/**
+	 * The hook name to check.
+	 */
+	hookName: string
+) => number | undefined;
 
 /**
  * Returns a function which, when invoked, will return the number of times a
  * hook has been called.
  *
- * @param {import('.').Hooks}    hooks    Hooks instance.
- * @param {import('.').StoreKey} storeKey
+ * @param hooks    Hooks instance.
+ * @param storeKey
  *
- * @return {DidHook} Function that returns a hook's call count.
+ * @return  Function that returns a hook's call count.
  */
-function createDidHook( hooks, storeKey ) {
+function createDidHook( hooks: Hooks, storeKey: StoreKey ): DidHook {
 	return function didHook( hookName ) {
 		const hooksStore = hooks[ storeKey ];
 
diff --git a/packages/hooks/src/createDoingHook.ts b/packages/hooks/src/createDoingHook.ts
@@ -1,24 +1,30 @@
 /**
- * @callback DoingHook
+ * Internal dependencies
+ */
+import type { Hooks, StoreKey } from './types';
+
+/**
  * Returns whether a hook is currently being executed.
  *
- * @param {string} [hookName] The name of the hook to check for.  If
- *                            omitted, will check for any hook being executed.
- *
- * @return {boolean} Whether the hook is being executed.
  */
+export type DoingHook = (
+	/**
+	 * The name of the hook to check for.
+	 * If omitted, will check for any hook being executed.
+	 */ hookName?: string
+) => boolean;
 
 /**
  * Returns a function which, when invoked, will return whether a hook is
  * currently being executed.
  *
- * @param {import('.').Hooks}    hooks    Hooks instance.
- * @param {import('.').StoreKey} storeKey
+ * @param hooks    Hooks instance.
+ * @param storeKey
  *
- * @return {DoingHook} Function that returns whether a hook is currently
+ * @return Function that returns whether a hook is currently
  *                     being executed.
  */
-function createDoingHook( hooks, storeKey ) {
+function createDoingHook( hooks: Hooks, storeKey: StoreKey ): DoingHook {
 	return function doingHook( hookName ) {
 		const hooksStore = hooks[ storeKey ];
 
diff --git a/packages/hooks/src/createHasHook.ts b/packages/hooks/src/createHasHook.ts
@@ -1,25 +1,33 @@
 /**
- * @callback HasHook
+ * Internal dependencies
+ */
+import type { Hooks, StoreKey } from './types';
+/**
  *
  * Returns whether any handlers are attached for the given hookName and optional namespace.
- *
- * @param {string} hookName    The name of the hook to check for.
- * @param {string} [namespace] Optional. The unique namespace identifying the callback
- *                             in the form `vendor/plugin/function`.
- *
- * @return {boolean} Whether there are handlers that are attached to the given hook.
  */
+export type HasHook = (
+	/**
+	 * The name of the hook to check for.
+	 */
+	hookname: string,
+	/**
+	 * The unique namespace identifying the callback in the form `vendor/plugin/function`.
+	 */
+	namespace?: string
+) => boolean;
+
 /**
  * Returns a function which, when invoked, will return whether any handlers are
  * attached to a particular hook.
  *
- * @param {import('.').Hooks}    hooks    Hooks instance.
- * @param {import('.').StoreKey} storeKey
+ * @param hooks    Hooks instance.
+ * @param storeKey
  *
- * @return {HasHook} Function that returns whether any handlers are
+ * @return  Function that returns whether any handlers are
  *                   attached to a particular hook and optional namespace.
  */
-function createHasHook( hooks, storeKey ) {
+function createHasHook( hooks: Hooks, storeKey: StoreKey ): HasHook {
 	return function hasHook( hookName, namespace ) {
 		const hooksStore = hooks[ storeKey ];
 
diff --git a/packages/hooks/src/createHooks.ts b/packages/hooks/src/createHooks.ts
@@ -8,6 +8,7 @@ import createRunHook from './createRunHook';
 import createCurrentHook from './createCurrentHook';
 import createDoingHook from './createDoingHook';
 import createDidHook from './createDidHook';
+import type { Store } from './types';
 
 /**
  * Internal class for constructing hooks. Use `createHooks()` function
@@ -17,12 +18,32 @@ import createDidHook from './createDidHook';
  * @private
  */
 export class _Hooks {
+	public actions: Store;
+	public filters: Store;
+
+	public addAction: ReturnType< typeof createAddHook >;
+	public addFilter: ReturnType< typeof createAddHook >;
+	public removeAction: ReturnType< typeof createRemoveHook >;
+	public removeFilter: ReturnType< typeof createRemoveHook >;
+	public hasAction: ReturnType< typeof createHasHook >;
+	public hasFilter: ReturnType< typeof createHasHook >;
+	public removeAllActions: ReturnType< typeof createRemoveHook >;
+	public removeAllFilters: ReturnType< typeof createRemoveHook >;
+	public doAction: ReturnType< typeof createRunHook >;
+	public doActionAsync: ReturnType< typeof createRunHook >;
+	public applyFilters: ReturnType< typeof createRunHook >;
+	public applyFiltersAsync: ReturnType< typeof createRunHook >;
+	public currentAction: ReturnType< typeof createCurrentHook >;
+	public currentFilter: ReturnType< typeof createCurrentHook >;
+	public doingAction: ReturnType< typeof createDoingHook >;
+	public doingFilter: ReturnType< typeof createDoingHook >;
+	public didAction: ReturnType< typeof createDidHook >;
+	public didFilter: ReturnType< typeof createDidHook >;
+
 	constructor() {
-		/** @type {import('.').Store} actions */
 		this.actions = Object.create( null );
 		this.actions.__current = new Set();
 
-		/** @type {import('.').Store} filters */
 		this.filters = Object.create( null );
 		this.filters.__current = new Set();
 
@@ -47,14 +68,14 @@ export class _Hooks {
 	}
 }
 
-/** @typedef {_Hooks} Hooks */
+export type Hooks = _Hooks;
 
 /**
  * Returns an instance of the hooks object.
  *
- * @return {Hooks} A Hooks instance.
+ * @return A Hooks instance.
  */
-function createHooks() {
+function createHooks(): Hooks {
 	return new _Hooks();
 }
 
diff --git a/packages/hooks/src/createRemoveHook.ts b/packages/hooks/src/createRemoveHook.ts
@@ -1,34 +1,42 @@
 /**
  * Internal dependencies
  */
-import validateNamespace from './validateNamespace.js';
-import validateHookName from './validateHookName.js';
+import validateNamespace from './validateNamespace';
+import validateHookName from './validateHookName';
+import type { Hooks, StoreKey } from './types';
 
 /**
- * @callback RemoveHook
  * Removes the specified callback (or all callbacks) from the hook with a given hookName
  * and namespace.
- *
- * @param {string} hookName  The name of the hook to modify.
- * @param {string} namespace The unique namespace identifying the callback in the
- *                           form `vendor/plugin/function`.
- *
- * @return {number | undefined} The number of callbacks removed.
  */
+export type RemoveHook = (
+	/**
+	 * The name of the hook to modify.
+	 */
+	hookName: string,
+	/**
+	 * The unique namespace identifying the callback in the form `vendor/plugin/function`.
+	 */
+	namespace: string
+) => number | undefined;
 
 /**
  * Returns a function which, when invoked, will remove a specified hook or all
  * hooks by the given name.
  *
- * @param {import('.').Hooks}    hooks             Hooks instance.
- * @param {import('.').StoreKey} storeKey
- * @param {boolean}              [removeAll=false] Whether to remove all callbacks for a hookName,
- *                                                 without regard to namespace. Used to create
- *                                                 `removeAll*` functions.
+ * @param hooks             Hooks instance.
+ * @param storeKey
+ * @param [removeAll=false] Whether to remove all callbacks for a hookName,
+ *                          without regard to namespace. Used to create
+ *                          `removeAll*` functions.
  *
- * @return {RemoveHook} Function that removes hooks.
+ * @return Function that removes hooks.
  */
-function createRemoveHook( hooks, storeKey, removeAll = false ) {
+function createRemoveHook(
+	hooks: Hooks,
+	storeKey: StoreKey,
+	removeAll: boolean = false
+): RemoveHook {
 	return function removeHook( hookName, namespace ) {
 		const hooksStore = hooks[ storeKey ];
 
diff --git a/packages/hooks/src/createRunHook.ts b/packages/hooks/src/createRunHook.ts
@@ -1,16 +1,31 @@
+/**
+ * Internal dependencies
+ */
+import type { Hooks, StoreKey } from './types';
+
+export type RunHook = (
+	hookName: string,
+	...args: unknown[]
+) => undefined | unknown;
+
 /**
  * Returns a function which, when invoked, will execute all callbacks
  * registered to a hook of the specified type, optionally returning the final
  * value of the call chain.
  *
- * @param {import('.').Hooks}    hooks          Hooks instance.
- * @param {import('.').StoreKey} storeKey
- * @param {boolean}              returnFirstArg Whether each hook callback is expected to return its first argument.
- * @param {boolean}              async          Whether the hook callback should be run asynchronously
+ * @param hooks          Hooks instance.
+ * @param storeKey
+ * @param returnFirstArg Whether each hook callback is expected to return its first argument.
+ * @param async          Whether the hook callback should be run asynchronously
  *
- * @return {(hookName:string, ...args: unknown[]) => undefined|unknown} Function that runs hook callbacks.
+ * @return Function that runs hook callbacks.
  */
-function createRunHook( hooks, storeKey, returnFirstArg, async ) {
+function createRunHook(
+	hooks: Hooks,
+	storeKey: StoreKey,
+	returnFirstArg: boolean,
+	async: boolean
+): RunHook {
 	return function runHook( hookName, ...args ) {
 		const hooksStore = hooks[ storeKey ];
 
diff --git a/packages/hooks/src/index.ts b/packages/hooks/src/index.ts
diff --git a/packages/hooks/src/types.ts b/packages/hooks/src/types.ts
diff --git a/packages/hooks/src/validateHookName.ts b/packages/hooks/src/validateHookName.ts
diff --git a/packages/hooks/src/validateNamespace.ts b/packages/hooks/src/validateNamespace.ts
