@arkstack/common 0.19.5 → 0.20.0

package/README.md

@@ -439,71 +439,7 @@ RequestException.abortIf(!user.isActive, 'Account is suspended', 403)
 
 **`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).
-
-#### `Hook.set(name, hook)`
-
-Registers a hook. Multiple calls for the same name are merged.
-
-```ts
-import { Hook } from '@arkstack/common'
-
-Hook.set('request:handle', {
-  before: (ctx) => console.log('before handler'),
-  after: (ctx) => console.log('after handler'),
-})
-```
-
----
-
-#### `Hook.get(name, pos?)`
-
-Retrieves the full hook object or a specific positional handler.
-
-```ts
-const hook = Hook.get('request:handle') // IHook | undefined
-const before = Hook.get('request:handle', 'before') // function | undefined
-```
-
----
-
-#### `Hook.has(name, pos?)`
-
-Checks whether a hook (or a specific position within it) exists.
-
-```ts
-Hook.has('request:handle') // true | false
-Hook.has('request:handle', 'after') // true | false
-```
-
----
-
-#### `Hook.unset(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()`.
-
-```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.getAll()`
-
-Returns all registered hooks as a plain record.
-
-```ts
-const hooks = Hook.getAll()
-// { 'request:handle': { before: fn, after: fn } }
-```
-
----
-
-#### `Hook.clear()`
-
-Clears all registered hooks.
+Re-exports `Hook` from `@arkstack/foundry`; both imports are the same process-wide registry. See the [`@arkstack/foundry` README](../foundry/README.md#hook) for the API (`on`, `emit`, `get`, `has`, `off`, `all`, `clear`). Declare typed hook names by augmenting `HookRegistry` on `@arkstack/foundry`.
 
 ---
 

package/dist/{helpers-DpnBcrO9.d.ts → helpers-Dq0l34ve.d.ts}

@@ -1,3 +1,4 @@
+import { HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, HookResult, IHook } from "@arkstack/foundry";
 import { ChannelOptions, Cipher, CipherOptions, Codec, DeriveOptions, DerivedKey, EncryptionKey, FingerprintOptions, KeyInput, KeyPair, Keys, SealedBox, SecureChannel, SerializedKeyPair } from "@arkstack/encryption";
 import { NodeCipher } from "@arkstack/encryption/node";
 import { JitiOptions, JitiResolveOptions } from "jiti";
@@ -334,14 +335,6 @@ interface ArkstackErrorPayload {
   /** Custom fields contributed by an exception's `body`. */
   [key: string]: unknown;
 }
-interface HookRegistry {}
-type Position = 'before' | 'after' | (string & {});
-type IHook = { [P in Position]?: (...args: any[]) => void; };
-type HookName = keyof HookRegistry extends never ? string : keyof HookRegistry | (string & {});
-type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N] : IHook;
-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 Choice<Value> = {
   value: Value;
   name?: string;
@@ -715,4 +708,4 @@ declare const abortIf: <T>(boolean: T, message?: string, code?: number) => asser
  */
 declare const assertFound: <T>(value: T | null | undefined, message: string, code?: number) => asserts value is T;
 //#endregion
-export { HookPos as $, SealedBox as A, ConfigShape as B, Encryption as C, KeyPair as D, KeyInput as E, ArkstackErrorShape as F, EnvRegistry as G, DotPathValue as H, Choice as I, GlobalConfig as J, EnvReturn as K, Choices as L, SerializedKeyPair as M, AppConfig as N, Keys as O, ArkstackErrorPayload as P, HookName as Q, Concrete as R, DerivedKey as S, FingerprintOptions as T, EnvKey as U, DotPath as V, EnvLookup as W, HookArgs as X, GlobalEnv as Y, HookFor as Z, ChannelOptions as _, abort as a, LoggerParseSignature as at, Codec as b, getModel as c, Primitive as ct, isClass as d, PublishFilter as dt, HookPositions as et, normalizePositiveInteger as f, PublishGroup as ft, Hash as g, setModelResolver as h, ModelResolver as i, LoggerLog as it, SecureChannel as j, NodeCipher as k, getModelSync as l, PublishConfirmation as lt, resolvePagination as m, Logger as mt, ModelConstructor as n, IHook as nt, abortIf as o, MergedConfig as ot, perPage as p, UnionToIntersection as pt, FileImporter as q, ModelRegistry as r, LoggerChalk as rt, assertFound as s, PaginationOptions as st, AbstractModelConstructor as t, HookRegistry as tt, initializeGlobalContext as u, PublishEntry as ut, Cipher as v, EncryptionKey as w, DeriveOptions as x, CipherOptions as y, ConfigRegistry as z };
+export { HookPos as $, SealedBox as A, ConfigShape as B, Encryption as C, KeyPair as D, KeyInput as E, ArkstackErrorShape as F, EnvRegistry as G, DotPathValue as H, Choice as I, GlobalConfig as J, EnvReturn as K, Choices as L, SerializedKeyPair as M, AppConfig as N, Keys as O, ArkstackErrorPayload as P, HookName as Q, Concrete as R, DerivedKey as S, FingerprintOptions as T, EnvKey as U, DotPath as V, EnvLookup as W, HookArgs as X, GlobalEnv as Y, HookFor as Z, ChannelOptions as _, abort as a, LoggerLog as at, Codec as b, getModel as c, PaginationOptions as ct, isClass as d, PublishEntry as dt, HookPositions as et, normalizePositiveInteger as f, PublishFilter as ft, Hash as g, setModelResolver as h, Logger as ht, ModelResolver as i, LoggerChalk as it, SecureChannel as j, NodeCipher as k, getModelSync as l, Primitive as lt, resolvePagination as m, UnionToIntersection as mt, ModelConstructor as n, HookResult as nt, abortIf as o, LoggerParseSignature as ot, perPage as p, PublishGroup as pt, FileImporter as q, ModelRegistry as r, IHook as rt, assertFound as s, MergedConfig as st, AbstractModelConstructor as t, HookRegistry as tt, initializeGlobalContext as u, PublishConfirmation as ut, Cipher as v, EncryptionKey as w, DeriveOptions as x, CipherOptions as y, ConfigRegistry as z };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /// <reference path="./app.d.ts" />
-import { $ as HookPos, A as SealedBox, B as ConfigShape, C as Encryption, D as KeyPair, E as KeyInput, F as ArkstackErrorShape, G as EnvRegistry, H as DotPathValue, I as Choice, J as GlobalConfig, K as EnvReturn, L as Choices, M as SerializedKeyPair, N as AppConfig, O as Keys, P as ArkstackErrorPayload, Q as HookName, R as Concrete, S as DerivedKey, T as FingerprintOptions, U as EnvKey, V as DotPath, W as EnvLookup, X as HookArgs, Y as GlobalEnv, Z as HookFor, _ as ChannelOptions, a as abort, at as LoggerParseSignature, b as Codec, c as getModel, ct as Primitive, d as isClass, dt as PublishFilter, et as HookPositions, f as normalizePositiveInteger, ft as PublishGroup, g as Hash, h as setModelResolver, i as ModelResolver, it as LoggerLog, j as SecureChannel, k as NodeCipher, l as getModelSync, lt as PublishConfirmation, m as resolvePagination, mt as Logger, n as ModelConstructor, nt as IHook, o as abortIf, ot as MergedConfig, p as perPage, pt as UnionToIntersection, q as FileImporter, r as ModelRegistry, rt as LoggerChalk, s as assertFound, st as PaginationOptions, t as AbstractModelConstructor, tt as HookRegistry, u as initializeGlobalContext, ut as PublishEntry, v as Cipher, w as EncryptionKey, x as DeriveOptions, y as CipherOptions, z as ConfigRegistry } from "./helpers-DpnBcrO9.js";
+import { $ as HookPos, A as SealedBox, B as ConfigShape, C as Encryption, D as KeyPair, E as KeyInput, F as ArkstackErrorShape, G as EnvRegistry, H as DotPathValue, I as Choice, J as GlobalConfig, K as EnvReturn, L as Choices, M as SerializedKeyPair, N as AppConfig, O as Keys, P as ArkstackErrorPayload, Q as HookName, R as Concrete, S as DerivedKey, T as FingerprintOptions, U as EnvKey, V as DotPath, W as EnvLookup, X as HookArgs, Y as GlobalEnv, Z as HookFor, _ as ChannelOptions, a as abort, at as LoggerLog, b as Codec, c as getModel, ct as PaginationOptions, d as isClass, dt as PublishEntry, et as HookPositions, f as normalizePositiveInteger, ft as PublishFilter, g as Hash, h as setModelResolver, ht as Logger, i as ModelResolver, it as LoggerChalk, j as SecureChannel, k as NodeCipher, l as getModelSync, lt as Primitive, m as resolvePagination, mt as UnionToIntersection, n as ModelConstructor, nt as HookResult, o as abortIf, ot as LoggerParseSignature, p as perPage, pt as PublishGroup, q as FileImporter, r as ModelRegistry, rt as IHook, s as assertFound, st as MergedConfig, t as AbstractModelConstructor, tt as HookRegistry, u as initializeGlobalContext, ut as PublishConfirmation, v as Cipher, w as EncryptionKey, x as DeriveOptions, y as CipherOptions, z as ConfigRegistry } from "./helpers-Dq0l34ve.js";
+import { Hook } from "@arkstack/foundry";
 import { Arkstack } from "@arkstack/contract";
 import { ForkOptions } from "node:child_process";
 import pino from "pino";
@@ -329,60 +330,6 @@ declare class Publisher {
   static confirmables(pkg: string | true): PublishConfirmation[];
 }
 //#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.
-   *
-   * @param name
-   * @param value
-   */
-  static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
-  /**
-   * Check if a hook is defined by name
-   *
-   * @param name
-   */
-  static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
-  /**
-   * Retrieve a defined hook by name
-   *
-   * @param name
-   */
-  static get<N extends HookName>(name: N): HookFor<N> | undefined;
-  /**
-   * Retrieve a defined hook 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;
-  /**
-   * Retrieve a defined hook by name and position the set args for callback
-   *
-   * @param name
-   * @param pos
-   */
-  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P>): void;
-  /**
-   * Retrieve all defined hooks
-   *
-   * @param name
-   */
-  static getAll: () => Record<string, IHook> & HookRegistry;
-  /**
-   * Remove the defined hook
-   *
-   * @param name
-   */
-  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
-  /**
-   * Clear all the defined hooks
-   */
-  static clear: () => void;
-}
-//#endregion
 //#region src/EnvLoader.d.ts
 /**
  * Loads environment variables, reading the `.env` file on first access.
@@ -533,4 +480,4 @@ declare const devServer: (options: DevServerRunnerOptions) => {
   closeWatcher(): Promise<void>;
 };
 //#endregion
-export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, type ChannelOptions, Choice, Choices, Cipher, type CipherOptions, Codec, Concrete, ConfigLoader, ConfigRegistry, ConfigShape, type DeriveOptions, type DerivedKey, DevServerRunnerOptions, DotPath, DotPathValue, Encryption, EncryptionKey, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, type FingerprintOptions, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, type KeyInput, KeyPair, Keys, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, ModelResolver, NodeCipher, PaginationOptions, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, SealedBox, SecureChannel, type SerializedKeyPair, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, setModelResolver, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, type ChannelOptions, Choice, Choices, Cipher, type CipherOptions, Codec, Concrete, ConfigLoader, ConfigRegistry, ConfigShape, type DeriveOptions, type DerivedKey, DevServerRunnerOptions, DotPath, DotPathValue, Encryption, EncryptionKey, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, type FingerprintOptions, GlobalConfig, GlobalEnv, Hash, Hook, type HookArgs, type HookFor, type HookName, type HookPos, type HookPositions, type HookRegistry, type HookResult, type IHook, type KeyInput, KeyPair, Keys, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, ModelResolver, NodeCipher, PaginationOptions, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, SealedBox, SecureChannel, type SerializedKeyPair, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devServer, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, setModelResolver, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { _ as EnvLoader, a as env, c as nodeEnv, d as resolveRuntimeDir, f as resolveRuntimeModule, g as configLoader, h as ConfigLoader, i as discoverCommands, l as outputDir, m as CONFIG_KEY, n as appUrl, o as importFile, p as toOutputPath, r as config, s as interopDefault, t as appKey, u as rebuildOutput, v as envLoader } from "./system-DzAzwH__.js";
 import { A as SecureChannel, C as Codec, D as Keys, E as KeyPair, O as NodeCipher, S as Cipher, T as EncryptionKey, _ as setModelResolver, b as Exception, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, k as SealedBox, l as assertFound, m as normalizePositiveInteger, p as isClass, s as abort, u as getModel, v as RequestException, w as Encryption, x as Hash, y as AppException } from "./utils-DwfM0lt4.js";
-import { Hook as Hook$1 } from "@arkstack/foundry";
+import { Hook, Hook as Hook$1 } from "@arkstack/foundry";
 import { Arkstack } from "@arkstack/contract";
 import { str } from "@h3ravel/support";
 import path from "node:path";
@@ -19,7 +19,7 @@ const bindGracefulShutdown = (shutdown, defer) => {
 		"SIGQUIT"
 	].forEach((signal) => {
 		process.on(signal, async () => {
-			if (Hook$1.has("shutdown", "before")) Hook$1.get("shutdown", "after", {});
+			await Hook$1.emit("shutdown", "before", {});
 			await shutdown();
 		});
 	});
@@ -37,7 +37,7 @@ const bindGracefulShutdown = (shutdown, defer) => {
 */
 const bootWithDetectedPort = async (boot, preferredPort = 3e3, app, defer) => {
 	const port = await detect(preferredPort);
-	if (Hook$1.has("boot", "before")) Hook$1.get("boot", "before", port, app);
+	await Hook$1.emit("boot", "before", port, app);
 	if (app && !globalThis.app) globalThis.app = () => app;
 	globalThis.env = env;
 	globalThis.config = config;
@@ -49,7 +49,7 @@ const bootWithDetectedPort = async (boot, preferredPort = 3e3, app, defer) => {
 	await boot(port);
 	await initializeGlobalContext();
 	bindGracefulShutdown(async () => await app?.shutdown(), defer);
-	if (Hook$1.has("boot", "after")) Hook$1.get("boot", "after", port, app);
+	await Hook$1.emit("boot", "after", port, app);
 };
 const renderError = ({ message = "An unexpected error occurred.", stack, title, code = 500 }) => {
 	title = {
@@ -520,74 +520,6 @@ var Logger = class Logger {
 	}
 };
 //#endregion
-//#region src/Hook.ts
-var Hook = class {
-	static hooks = /* @__PURE__ */ new Map();
-	/**
-	* Hooks define code that should run within defined boundaries to add extra functionalities.
-	*
-	* @param name
-	* @param value
-	*/
-	static set(name, hook) {
-		const oldhook = this.hooks.get(name) ?? {};
-		this.hooks.set(name, {
-			...oldhook,
-			...hook
-		});
-	}
-	/**
-	* Check if a hook is defined by name
-	*
-	* @param name
-	*/
-	static has(name, pos) {
-		if (pos && this.hooks.has(name)) return Boolean(this.get(name, pos));
-		return this.hooks.has(name);
-	}
-	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;
-	}
-	/**
-	* Retrieve all defined hooks
-	*
-	* @param name
-	*/
-	static getAll = () => {
-		const hooks = {};
-		for (const [name, value] of this.hooks) hooks[name] = value;
-		return hooks;
-	};
-	/**
-	* Remove the defined hook
-	*
-	* @param name
-	*/
-	static unset(name, pos) {
-		if (name && this.hooks.has(name)) {
-			if (pos !== void 0) {
-				const hook = this.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();
-	}
-	/**
-	* Clear all the defined hooks
-	*/
-	static clear = () => {
-		this.hooks.clear();
-	};
-};
-//#endregion
 //#region src/tls.ts
 let devCertCache;
 /**

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { A as SealedBox, C as Encryption, D as KeyPair, E as KeyInput, M as SerializedKeyPair, O as Keys, S as DerivedKey, T as FingerprintOptions, _ as ChannelOptions, a as abort, b as Codec, c as getModel, d as isClass, f as normalizePositiveInteger, g as Hash, h as setModelResolver, i as ModelResolver, j as SecureChannel, k as NodeCipher, l as getModelSync, m as resolvePagination, n as ModelConstructor, o as abortIf, p as perPage, r as ModelRegistry, s as assertFound, t as AbstractModelConstructor, u as initializeGlobalContext, v as Cipher, w as EncryptionKey, x as DeriveOptions, y as CipherOptions } from "../helpers-DpnBcrO9.js";
+import { A as SealedBox, C as Encryption, D as KeyPair, E as KeyInput, M as SerializedKeyPair, O as Keys, S as DerivedKey, T as FingerprintOptions, _ as ChannelOptions, a as abort, b as Codec, c as getModel, d as isClass, f as normalizePositiveInteger, g as Hash, h as setModelResolver, i as ModelResolver, j as SecureChannel, k as NodeCipher, l as getModelSync, m as resolvePagination, n as ModelConstructor, o as abortIf, p as perPage, r as ModelRegistry, s as assertFound, t as AbstractModelConstructor, u as initializeGlobalContext, v as Cipher, w as EncryptionKey, x as DeriveOptions, y as CipherOptions } from "../helpers-Dq0l34ve.js";
 import { Model } from "arkormx";
 //#region src/utils/traits.d.ts
 declare const crc32: (str: string) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.19.5",
+  "version": "0.20.0",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -43,13 +43,13 @@
     "otpauth": "^9.5.1",
     "pino": "^10.3.1",
     "selfsigned": "^2.4.1",
-    "@arkstack/encryption": "^0.19.5"
+    "@arkstack/encryption": "^0.20.0"
   },
   "peerDependencies": {
     "@h3ravel/support": "^2.2.7",
     "arkormx": "^2.12.8",
-    "@arkstack/contract": "^0.19.5",
-    "@arkstack/foundry": "^0.19.5"
+    "@arkstack/contract": "^0.20.0",
+    "@arkstack/foundry": "^0.20.0"
   },
   "optionalDependencies": {
     "@faker-js/faker": "^10.4.0"