@wordpress/hooks 3.2.1

package/build-types/validateHookName.d.ts

@@ -0,0 +1,12 @@
+export default validateHookName;
+/**
+ * Validate a hookName string.
+ *
+ * @param {string} hookName The hook name to validate. Should be a non empty string containing
+ *                          only numbers, letters, dashes, periods and underscores. Also,
+ *                          the hook name cannot begin with `__`.
+ *
+ * @return {boolean} Whether the hook name is valid.
+ */
+declare function validateHookName(hookName: string): boolean;
+//# sourceMappingURL=validateHookName.d.ts.map

package/build-types/validateHookName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateHookName.d.ts","sourceRoot":"","sources":["../src/validateHookName.js"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AACH,4CANW,MAAM,GAIL,OAAO,CAwBlB"}

package/build-types/validateNamespace.d.ts

@@ -0,0 +1,11 @@
+export default validateNamespace;
+/**
+ * Validate a namespace string.
+ *
+ * @param {string} namespace The namespace to validate - should take the form
+ *                           `vendor/plugin/function`.
+ *
+ * @return {boolean} Whether the namespace is valid.
+ */
+declare function validateNamespace(namespace: string): boolean;
+//# sourceMappingURL=validateNamespace.d.ts.map

package/build-types/validateNamespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateNamespace.d.ts","sourceRoot":"","sources":["../src/validateNamespace.js"],"names":[],"mappings":";AAAA;;;;;;;GAOG;AACH,8CALW,MAAM,GAGL,OAAO,CAkBlB"}

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@wordpress/hooks",
+	"version": "3.2.1",
+	"description": "WordPress hooks library.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"hooks"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/hooks/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/hooks"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=12"
+	},
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"types": "build-types",
+	"dependencies": {
+		"@babel/runtime": "^7.13.10"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "8f7f052bc04e3f4eb50f479ced14be1489b9fa79"
+}

package/src/createAddHook.js

@@ -0,0 +1,107 @@
+/**
+ * Internal dependencies
+ */
+import validateNamespace from './validateNamespace.js';
+import validateHookName from './validateHookName.js';
+
+/**
+ * @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
+ */
+
+/**
+ * Returns a function which, when invoked, will add a hook.
+ *
+ * @param {import('.').Hooks}    hooks    Hooks instance.
+ * @param {import('.').StoreKey} storeKey
+ *
+ * @return {AddHook} Function that adds a new hook.
+ */
+function createAddHook( hooks, storeKey ) {
+	return function addHook( hookName, namespace, callback, priority = 10 ) {
+		const hooksStore = hooks[ storeKey ];
+
+		if ( ! validateHookName( hookName ) ) {
+			return;
+		}
+
+		if ( ! validateNamespace( namespace ) ) {
+			return;
+		}
+
+		if ( 'function' !== typeof callback ) {
+			// eslint-disable-next-line no-console
+			console.error( 'The hook callback must be a function.' );
+			return;
+		}
+
+		// Validate numeric priority
+		if ( 'number' !== typeof priority ) {
+			// eslint-disable-next-line no-console
+			console.error(
+				'If specified, the hook priority must be a number.'
+			);
+			return;
+		}
+
+		const 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;
+			for ( i = handlers.length; i > 0; i-- ) {
+				if ( priority >= handlers[ i - 1 ].priority ) {
+					break;
+				}
+			}
+
+			if ( i === handlers.length ) {
+				// If append, operate via direct assignment.
+				handlers[ i ] = handler;
+			} else {
+				// Otherwise, insert before index via splice.
+				handlers.splice( i, 0, handler );
+			}
+
+			// We may also be currently executing this hook.  If the callback
+			// 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 ) => {
+				if (
+					hookInfo.name === hookName &&
+					hookInfo.currentIndex >= i
+				) {
+					hookInfo.currentIndex++;
+				}
+			} );
+		} else {
+			// This is the first hook of its type.
+			hooksStore[ hookName ] = {
+				handlers: [ handler ],
+				runs: 0,
+			};
+		}
+
+		if ( hookName !== 'hookAdded' ) {
+			hooks.doAction(
+				'hookAdded',
+				hookName,
+				namespace,
+				callback,
+				priority
+			);
+		}
+	};
+}
+
+export default createAddHook;

package/src/createCurrentHook.js

@@ -0,0 +1,22 @@
+/**
+ * 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
+ *
+ * @return {() => string | null} Function that returns the current hook name or null.
+ */
+function createCurrentHook( hooks, storeKey ) {
+	return function currentHook() {
+		const hooksStore = hooks[ storeKey ];
+
+		return (
+			hooksStore.__current[ hooksStore.__current.length - 1 ]?.name ??
+			null
+		);
+	};
+}
+
+export default createCurrentHook;

package/src/createDidHook.js

@@ -0,0 +1,39 @@
+/**
+ * Internal dependencies
+ */
+import validateHookName from './validateHookName.js';
+
+/**
+ * @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.
+ */
+
+/**
+ * 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
+ *
+ * @return {DidHook} Function that returns a hook's call count.
+ */
+function createDidHook( hooks, storeKey ) {
+	return function didHook( hookName ) {
+		const hooksStore = hooks[ storeKey ];
+
+		if ( ! validateHookName( hookName ) ) {
+			return;
+		}
+
+		return hooksStore[ hookName ] && hooksStore[ hookName ].runs
+			? hooksStore[ hookName ].runs
+			: 0;
+	};
+}
+
+export default createDidHook;

package/src/createDoingHook.js

@@ -0,0 +1,37 @@
+/**
+ * @callback DoingHook
+ * 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.
+ */
+
+/**
+ * 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
+ *
+ * @return {DoingHook} Function that returns whether a hook is currently
+ *                     being executed.
+ */
+function createDoingHook( hooks, storeKey ) {
+	return function doingHook( hookName ) {
+		const hooksStore = hooks[ storeKey ];
+
+		// If the hookName was not passed, check for any current hook.
+		if ( 'undefined' === typeof hookName ) {
+			return 'undefined' !== typeof hooksStore.__current[ 0 ];
+		}
+
+		// Return the __current hook.
+		return hooksStore.__current[ 0 ]
+			? hookName === hooksStore.__current[ 0 ].name
+			: false;
+	};
+}
+
+export default createDoingHook;

package/src/createHasHook.js

@@ -0,0 +1,40 @@
+/**
+ * @callback HasHook
+ *
+ * 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.
+ */
+/**
+ * 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
+ *
+ * @return {HasHook} Function that returns whether any handlers are
+ *                   attached to a particular hook and optional namespace.
+ */
+function createHasHook( hooks, storeKey ) {
+	return function hasHook( hookName, namespace ) {
+		const hooksStore = hooks[ storeKey ];
+
+		// Use the namespace if provided.
+		if ( 'undefined' !== typeof namespace ) {
+			return (
+				hookName in hooksStore &&
+				hooksStore[ hookName ].handlers.some(
+					( hook ) => hook.namespace === namespace
+				)
+			);
+		}
+
+		return hookName in hooksStore;
+	};
+}
+
+export default createHasHook;

package/src/createHooks.js

@@ -0,0 +1,59 @@
+/**
+ * Internal dependencies
+ */
+import createAddHook from './createAddHook';
+import createRemoveHook from './createRemoveHook';
+import createHasHook from './createHasHook';
+import createRunHook from './createRunHook';
+import createCurrentHook from './createCurrentHook';
+import createDoingHook from './createDoingHook';
+import createDidHook from './createDidHook';
+
+/**
+ * Internal class for constructing hooks. Use `createHooks()` function
+ *
+ * Note, it is necessary to expose this class to make its type public.
+ *
+ * @private
+ */
+export class _Hooks {
+	constructor() {
+		/** @type {import('.').Store} actions */
+		this.actions = Object.create( null );
+		this.actions.__current = [];
+
+		/** @type {import('.').Store} filters */
+		this.filters = Object.create( null );
+		this.filters.__current = [];
+
+		this.addAction = createAddHook( this, 'actions' );
+		this.addFilter = createAddHook( this, 'filters' );
+		this.removeAction = createRemoveHook( this, 'actions' );
+		this.removeFilter = createRemoveHook( this, 'filters' );
+		this.hasAction = createHasHook( this, 'actions' );
+		this.hasFilter = createHasHook( this, 'filters' );
+		this.removeAllActions = createRemoveHook( this, 'actions', true );
+		this.removeAllFilters = createRemoveHook( this, 'filters', true );
+		this.doAction = createRunHook( this, 'actions' );
+		this.applyFilters = createRunHook( this, 'filters', true );
+		this.currentAction = createCurrentHook( this, 'actions' );
+		this.currentFilter = createCurrentHook( this, 'filters' );
+		this.doingAction = createDoingHook( this, 'actions' );
+		this.doingFilter = createDoingHook( this, 'filters' );
+		this.didAction = createDidHook( this, 'actions' );
+		this.didFilter = createDidHook( this, 'filters' );
+	}
+}
+
+/** @typedef {_Hooks} Hooks */
+
+/**
+ * Returns an instance of the hooks object.
+ *
+ * @return {Hooks} A Hooks instance.
+ */
+function createHooks() {
+	return new _Hooks();
+}
+
+export default createHooks;

package/src/createRemoveHook.js

@@ -0,0 +1,88 @@
+/**
+ * Internal dependencies
+ */
+import validateNamespace from './validateNamespace.js';
+import validateHookName from './validateHookName.js';
+
+/**
+ * @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.
+ */
+
+/**
+ * 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.
+ *
+ * @return {RemoveHook} Function that removes hooks.
+ */
+function createRemoveHook( hooks, storeKey, removeAll = false ) {
+	return function removeHook( hookName, namespace ) {
+		const hooksStore = hooks[ storeKey ];
+
+		if ( ! validateHookName( hookName ) ) {
+			return;
+		}
+
+		if ( ! removeAll && ! validateNamespace( namespace ) ) {
+			return;
+		}
+
+		// Bail if no hooks exist by this name
+		if ( ! hooksStore[ hookName ] ) {
+			return 0;
+		}
+
+		let handlersRemoved = 0;
+
+		if ( removeAll ) {
+			handlersRemoved = hooksStore[ hookName ].handlers.length;
+			hooksStore[ hookName ] = {
+				runs: hooksStore[ hookName ].runs,
+				handlers: [],
+			};
+		} else {
+			// Try to find the specified callback to remove.
+			const handlers = hooksStore[ hookName ].handlers;
+			for ( let i = handlers.length - 1; i >= 0; i-- ) {
+				if ( handlers[ i ].namespace === namespace ) {
+					handlers.splice( i, 1 );
+					handlersRemoved++;
+					// This callback may also be part of a hook that is
+					// currently executing.  If the callback we're removing
+					// comes after the current callback, there's no problem;
+					// otherwise we need to decrease the execution index of any
+					// other runs by 1 to account for the removed element.
+					hooksStore.__current.forEach( ( hookInfo ) => {
+						if (
+							hookInfo.name === hookName &&
+							hookInfo.currentIndex >= i
+						) {
+							hookInfo.currentIndex--;
+						}
+					} );
+				}
+			}
+		}
+
+		if ( hookName !== 'hookRemoved' ) {
+			hooks.doAction( 'hookRemoved', hookName, namespace );
+		}
+
+		return handlersRemoved;
+	};
+}
+
+export default createRemoveHook;

package/src/createRunHook.js

@@ -0,0 +1,66 @@
+/**
+ * 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=false] Whether each hook callback is expected to
+ *                                                      return its first argument.
+ *
+ * @return {(hookName:string, ...args: unknown[]) => unknown} Function that runs hook callbacks.
+ */
+function createRunHook( hooks, storeKey, returnFirstArg = false ) {
+	return function runHooks( hookName, ...args ) {
+		const hooksStore = hooks[ storeKey ];
+
+		if ( ! hooksStore[ hookName ] ) {
+			hooksStore[ hookName ] = {
+				handlers: [],
+				runs: 0,
+			};
+		}
+
+		hooksStore[ hookName ].runs++;
+
+		const handlers = hooksStore[ hookName ].handlers;
+
+		// The following code is stripped from production builds.
+		if ( 'production' !== process.env.NODE_ENV ) {
+			// Handle any 'all' hooks registered.
+			if ( 'hookAdded' !== hookName && hooksStore.all ) {
+				handlers.push( ...hooksStore.all.handlers );
+			}
+		}
+
+		if ( ! handlers || ! handlers.length ) {
+			return returnFirstArg ? args[ 0 ] : undefined;
+		}
+
+		const hookInfo = {
+			name: hookName,
+			currentIndex: 0,
+		};
+
+		hooksStore.__current.push( hookInfo );
+
+		while ( hookInfo.currentIndex < handlers.length ) {
+			const handler = handlers[ hookInfo.currentIndex ];
+
+			const result = handler.callback.apply( null, args );
+			if ( returnFirstArg ) {
+				args[ 0 ] = result;
+			}
+
+			hookInfo.currentIndex++;
+		}
+
+		hooksStore.__current.pop();
+
+		if ( returnFirstArg ) {
+			return args[ 0 ];
+		}
+	};
+}
+
+export default createRunHook;

package/src/index.js

@@ -0,0 +1,82 @@
+/**
+ * Internal dependencies
+ */
+import createHooks from './createHooks';
+
+/** @typedef {(...args: any[])=>any} Callback */
+
+/**
+ * @typedef Handler
+ * @property {Callback} callback  The callback
+ * @property {string}   namespace The namespace
+ * @property {number}   priority  The namespace
+ */
+
+/**
+ * @typedef Hook
+ * @property {Handler[]} handlers Array of handlers
+ * @property {number}    runs     Run counter
+ */
+
+/**
+ * @typedef Current
+ * @property {string} name         Hook name
+ * @property {number} currentIndex The index
+ */
+
+/**
+ * @typedef {Record<string, Hook> & {__current: Current[]}} Store
+ */
+
+/**
+ * @typedef {'actions' | 'filters'} StoreKey
+ */
+
+/**
+ * @typedef {import('./createHooks').Hooks} Hooks
+ */
+
+export const defaultHooks = createHooks();
+
+const {
+	addAction,
+	addFilter,
+	removeAction,
+	removeFilter,
+	hasAction,
+	hasFilter,
+	removeAllActions,
+	removeAllFilters,
+	doAction,
+	applyFilters,
+	currentAction,
+	currentFilter,
+	doingAction,
+	doingFilter,
+	didAction,
+	didFilter,
+	actions,
+	filters,
+} = defaultHooks;
+
+export {
+	createHooks,
+	addAction,
+	addFilter,
+	removeAction,
+	removeFilter,
+	hasAction,
+	hasFilter,
+	removeAllActions,
+	removeAllFilters,
+	doAction,
+	applyFilters,
+	currentAction,
+	currentFilter,
+	doingAction,
+	doingFilter,
+	didAction,
+	didFilter,
+	actions,
+	filters,
+};