@arkstack/foundry 0.19.5 → 0.20.0

package/README.md

@@ -16,24 +16,32 @@ pnpm add @arkstack/foundry
 
 **`src/Hook.ts`**
 
-A global, named hook registry for extending Arkstack internals without modifying core code. Hooks are keyed by name and support positional slots (`before`, `after`, or any custom string).
+A global, named hook registry for extending Arkstack internals without modifying core code. Hooks are keyed by name and support positional slots (`before`, `after`, or any custom string). There is one registry per process: `@arkstack/common` re-exports this same `Hook`.
 
-#### `Hook.set(name, hook)`
+#### `Hook.on(name, positions)`
 
-Registers a hook. Multiple calls for the same name are merged.
+Registers callbacks for a hook's positions. Registering the same name again merges: only the positions supplied are added or replaced.
 
 ```ts
 import { Hook } from '@arkstack/foundry'
 
-Hook.set('request:handle', {
+Hook.on('request:handle', {
   before: (ctx) => console.log('before handler'),
   after: (ctx) => console.log('after handler'),
 })
 ```
 
+#### `Hook.emit(name, pos, ...args)`
+
+Calls a position with the given arguments and returns its result: a Promise for an async hook, so it can be awaited. When nothing is registered there it does nothing and returns `undefined`, so callers need no `has()` check.
+
+```ts
+await Hook.emit('request:handle', 'before', ctx)
+```
+
 #### `Hook.get(name, pos?)`
 
-Retrieves the full hook object or a specific positional handler.
+Retrieves the full hook object or one position's callback, without calling it.
 
 ```ts
 const hook = Hook.get('request:handle') // IHook | undefined
@@ -49,25 +57,29 @@ Hook.has('request:handle') // true | false
 Hook.has('request:handle', 'after') // true | false
 ```
 
-#### `Hook.unset(name?, pos?)`
+#### `Hook.off(name?, pos?)`
 
-Removes a hook or a single positional handler. If the hook becomes empty after removal, it is deleted entirely. Called with no arguments, it delegates to `Hook.clear()`.
+Removes a hook or a single position. A hook left with no positions is deleted. Called with no arguments it clears every hook; a name that isn't registered is a no-op.
 
 ```ts
-Hook.unset('request:handle', 'before') // removes only the 'before' handler
-Hook.unset('request:handle') // removes the entire hook
-Hook.unset() // clears all hooks
+Hook.off('request:handle', 'before') // removes only the 'before' callback
+Hook.off('request:handle') // removes the entire hook
+Hook.off() // clears all hooks
 ```
 
-#### `Hook.getAll()`
+#### `Hook.all()`
 
 Returns all registered hooks as a plain record.
 
 ```ts
-const hooks = Hook.getAll()
+const hooks = Hook.all()
 // { 'request:handle': { before: fn, after: fn } }
 ```
 
 #### `Hook.clear()`
 
 Clears all registered hooks.
+
+#### Deprecated aliases
+
+`set()` → `on()`, `unset()` → `off()`, `getAll()` → `all()`. `get(name, pos, ...args)` with arguments still calls the hook, but use `emit()`; `get()` should only retrieve.

package/dist/index.d.ts

@@ -7,23 +7,44 @@ type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N]
 type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
 type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
 type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
+type HookResult<N extends string, P extends string> = HookPos<N, P> extends ((...args: any[]) => infer R) ? R : unknown;
 //#endregion
 //#region src/Hook.d.ts
 declare class Hook {
   private static hooks;
   /**
-   * Hooks define code that should run within defined boundaries to add extra functionalities.
+   * Register callbacks for a hook's positions. Registering the same name again
+   * merges: only the positions supplied are added or replaced.
    *
    * @param name
-   * @param value
+   * @param hook
    */
-  static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
+  static on<N extends HookName>(name: N | (string & {}), hook: Partial<HookFor<N>>): void;
   /**
-   * Check if a hook is defined by name
+   * @deprecated Use {@link Hook.on}; `set` merges rather than replaces.
    *
    * @param name
+   * @param hook
+   */
+  static set<N extends HookName>(name: N | (string & {}), hook: Partial<HookFor<N>>): void;
+  /**
+   * Check if a hook is defined by name, or a position of it.
+   *
+   * @param name
+   * @param pos
    */
   static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
+  /**
+   * Run a hook position with the given arguments and return its result (a
+   * Promise for an async hook, so it can be awaited). A no-op returning
+   * `undefined` when nothing is registered there, so call sites need no
+   * {@link Hook.has} check.
+   *
+   * @param name
+   * @param pos
+   * @param args
+   */
+  static emit<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P & string>): HookResult<N, P & string> | undefined;
   /**
    * Retrieve a defined hook by name
    *
@@ -31,35 +52,46 @@ declare class Hook {
    */
   static get<N extends HookName>(name: N): HookFor<N> | undefined;
   /**
-   * Retrieve a defined hook by name and position
+   * Retrieve a defined hook's position by name and position
    *
    * @param name
    * @param pos
    */
-  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P): HookPos<N, P> | undefined;
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P): HookPos<N, P & string> | undefined;
   /**
-   * Retrieve a defined hook by name and position the set args for callback
+   * @deprecated Use {@link Hook.emit} to call a hook; `get` with arguments calls it.
    *
    * @param name
    * @param pos
+   * @param args
    */
-  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P>): void;
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P & string>): void;
   /**
    * Retrieve all defined hooks
+   */
+  static all: () => Record<string, IHook> & HookRegistry;
+  /**
+   * @deprecated Use {@link Hook.all}.
+   */
+  static getAll: () => Record<string, IHook> & HookRegistry;
+  /**
+   * Remove a hook, or one position of it. With no name, removes every hook.
    *
    * @param name
+   * @param pos
    */
-  static getAll: () => Record<string, IHook> & HookRegistry;
+  static off<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
   /**
-   * Remove the defined hook
+   * @deprecated Use {@link Hook.off}.
    *
    * @param name
+   * @param pos
    */
-  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
+  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): void;
   /**
    * Clear all the defined hooks
    */
   static clear: () => void;
 }
 //#endregion
-export { Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook };
+export { Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, HookResult, IHook };

package/dist/index.js

@@ -2,12 +2,13 @@
 var Hook = class {
 	static hooks = /* @__PURE__ */ new Map();
 	/**
-	* Hooks define code that should run within defined boundaries to add extra functionalities.
+	* Register callbacks for a hook's positions. Registering the same name again
+	* merges: only the positions supplied are added or replaced.
 	*
 	* @param name
-	* @param value
+	* @param hook
 	*/
-	static set(name, hook) {
+	static on(name, hook) {
 		const oldhook = this.hooks.get(name) ?? {};
 		this.hooks.set(name, {
 			...oldhook,
@@ -15,48 +16,82 @@ var Hook = class {
 		});
 	}
 	/**
-	* Check if a hook is defined by name
+	* @deprecated Use {@link Hook.on}; `set` merges rather than replaces.
+	*
+	* @param name
+	* @param hook
+	*/
+	static set(name, hook) {
+		this.on(name, hook);
+	}
+	/**
+	* Check if a hook is defined by name, or a position of it.
 	*
 	* @param name
+	* @param pos
 	*/
 	static has(name, pos) {
-		if (pos && this.hooks.has(name)) return Boolean(this.get(name, pos));
+		if (pos && this.hooks.has(name)) return Boolean(this.hooks.get(name)?.[pos]);
 		return this.hooks.has(name);
 	}
+	/**
+	* Run a hook position with the given arguments and return its result (a
+	* Promise for an async hook, so it can be awaited). A no-op returning
+	* `undefined` when nothing is registered there, so call sites need no
+	* {@link Hook.has} check.
+	*
+	* @param name
+	* @param pos
+	* @param args
+	*/
+	static emit(name, pos, ...args) {
+		const fn = this.hooks.get(name)?.[pos];
+		return fn ? fn(...args) : void 0;
+	}
 	static get(name, pos, ...args) {
 		const hook = this.hooks.get(name);
 		if (!hook) return void 0;
 		if (pos === void 0) return hook;
-		const fn = hook[pos];
-		if (!fn) return void 0;
-		if (args.length > 0) return fn(...args);
-		return fn;
+		if (args.length > 0) return void this.emit(name, pos, ...args);
+		return hook[pos];
 	}
 	/**
 	* Retrieve all defined hooks
-	*
-	* @param name
 	*/
-	static getAll = () => {
+	static all = () => {
 		const hooks = {};
 		for (const [name, value] of this.hooks) hooks[name] = value;
 		return hooks;
 	};
 	/**
-	* Remove the defined hook
+	* @deprecated Use {@link Hook.all}.
+	*/
+	static getAll = () => this.all();
+	/**
+	* Remove a hook, or one position of it. With no name, removes every hook.
 	*
 	* @param name
+	* @param pos
 	*/
-	static unset(name, pos) {
+	static off(name, pos) {
 		if (name && this.hooks.has(name)) {
 			if (pos !== void 0) {
-				const hook = this.get(name);
+				const hook = this.hooks.get(name);
 				if (hook?.[pos]) delete hook[pos];
 				Object.keys(hook ?? {}).length < 1 && this.hooks.delete(name);
 				return;
 			}
 			this.hooks.delete(name);
-		} else this.clear();
+		} else if (!name) this.clear();
+	}
+	/**
+	* @deprecated Use {@link Hook.off}.
+	*
+	* @param name
+	* @param pos
+	*/
+	static unset(name, pos) {
+		this.off(name, pos);
 	}
 	/**
 	* Clear all the defined hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/foundry",
-  "version": "0.19.5",
+  "version": "0.20.0",
   "type": "module",
   "description": "Extensibility primitives and framework internals for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",