@arkstack/foundry 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# `@arkstack/foundry`
+
+[![Foundry](https://img.shields.io/npm/dt/@arkstack/foundry?style=flat-square&label=@arkstack/foundry&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/foundry)](https://www.npmjs.com/package/@arkstack/foundry)
+
+Extensibility primitives and framework internals for the Arkstack ecosystem. This package provides the tools that shape how Arkstack behaves at runtime. Hooks, lifecycle interception, and utilities designed to extend and adapt the framework without modifying its core.
+
+## Installation
+
+```bash
+pnpm add @arkstack/foundry
+```
+
+## Modules
+
+### Hook
+
+**`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/foundry';
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+//#region src/types.d.ts
+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[];
+//#endregion
+//#region src/Hook.d.ts
+declare class Hook {
+  private static hooks;
+  static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
+  static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
+  static get<N extends HookName>(name: N): HookFor<N> | undefined;
+  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, ...args: HookArgs<N, P>): void;
+  static getAll: () => Record<string, IHook> & HookRegistry;
+  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
+  static clear: () => void;
+}
+//#endregion
+export { Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,71 @@
+//#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
+export { Hook };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/Hook.ts"],"sourcesContent":["import { HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook } from './types'\n\nexport class Hook {\n    private static hooks = new Map<string, IHook>()\n\n    /**\n     * Hooks define code that should run within defined boundaries to add extra functionalities.\n     * \n     * @param name \n     * @param value \n     */\n    static set<N extends HookName> (\n        name: N | (string & {}),\n        hook: HookFor<N>\n    ) {\n        const oldhook = this.hooks.get(name) ?? {}\n\n        this.hooks.set(name, {\n            ...oldhook,\n            ...hook,\n        })\n    }\n\n    /**\n     * Check if a hook is defined by name\n     * \n     * @param name \n     */\n    static has<N extends HookName, P extends HookPositions<N>> (name: N | (string & {}), pos?: P) {\n        if (pos && this.hooks.has(name))\n            return Boolean(this.get(name, pos))\n\n        return this.hooks.has(name)\n    }\n\n    /**\n     * Retrieve a defined hook by name\n     * \n     * @param name \n     */\n    static get<N extends HookName> (name: N): HookFor<N> | undefined\n    /**\n     * Retrieve a defined hook by name and position\n     * \n     * @param name \n     * @param pos \n     */\n    static get<N extends HookName, P extends HookPositions<N>> (name: N, pos: P): HookPos<N, P> | undefined\n    /**\n     * Retrieve a defined hook by name and position the set args for callback\n     * \n     * @param name \n     * @param pos \n     */\n    static get<N extends HookName, P extends HookPositions<N>> (name: N, pos: P, ...args: HookArgs<N, P>): void\n    static get<N extends HookName, P extends HookPositions<N>> (\n        name: N,\n        pos?: P,\n        ...args: HookArgs<N, P> | any[]\n    ): HookFor<N> | HookPos<N, P> | undefined {\n        const hook = this.hooks.get(name)\n\n        if (!hook) return undefined\n        if (pos === undefined) return hook as HookFor<N>\n\n        const fn = hook[pos]\n        if (!fn) return undefined\n\n        if (args.length > 0) return fn(...args) as HookPos<N, P>\n\n        return fn as HookPos<N, P>\n    }\n\n    /**\n     * Retrieve all defined hooks\n     * \n     * @param name \n     */\n    static getAll = () => {\n        const hooks: Record<string, IHook> & HookRegistry = {}\n\n        for (const [name, value] of this.hooks)\n            hooks[name] = value\n\n        return hooks\n    }\n\n    /**\n     * Remove the defined hook\n     * \n     * @param name \n     */\n    static unset<N extends HookName, P extends HookPositions<N>> (name?: N | (string & {}), pos?: P) {\n        if (name && this.hooks.has(name)) {\n            if (pos !== undefined) {\n                const hook = this.get(name)\n                if (hook?.[pos]) delete hook[pos]\n\n                return Object.keys(hook ?? {}).length < 1\n                    ? void this.hooks.delete(name)\n                    : undefined\n            }\n\n            this.hooks.delete(name)\n        } else this.clear()\n    }\n\n    /**\n     * Clear all the defined hooks\n     */\n    static clear = () => {\n        this.hooks.clear()\n    }\n}\n"],"mappings":";AAEA,IAAa,OAAb,MAAkB;CACd,OAAe,wBAAQ,IAAI,KAAoB;;;;;;;CAQ/C,OAAO,IACH,MACA,MACF;EACE,MAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI,EAAE;EAE1C,KAAK,MAAM,IAAI,MAAM;GACjB,GAAG;GACH,GAAG;GACN,CAAC;;;;;;;CAQN,OAAO,IAAqD,MAAyB,KAAS;EAC1F,IAAI,OAAO,KAAK,MAAM,IAAI,KAAK,EAC3B,OAAO,QAAQ,KAAK,IAAI,MAAM,IAAI,CAAC;EAEvC,OAAO,KAAK,MAAM,IAAI,KAAK;;CAuB/B,OAAO,IACH,MACA,KACA,GAAG,MACmC;EACtC,MAAM,OAAO,KAAK,MAAM,IAAI,KAAK;EAEjC,IAAI,CAAC,MAAM,OAAO,KAAA;EAClB,IAAI,QAAQ,KAAA,GAAW,OAAO;EAE9B,MAAM,KAAK,KAAK;EAChB,IAAI,CAAC,IAAI,OAAO,KAAA;EAEhB,IAAI,KAAK,SAAS,GAAG,OAAO,GAAG,GAAG,KAAK;EAEvC,OAAO;;;;;;;CAQX,OAAO,eAAe;EAClB,MAAM,QAA8C,EAAE;EAEtD,KAAK,MAAM,CAAC,MAAM,UAAU,KAAK,OAC7B,MAAM,QAAQ;EAElB,OAAO;;;;;;;CAQX,OAAO,MAAuD,MAA0B,KAAS;EAC7F,IAAI,QAAQ,KAAK,MAAM,IAAI,KAAK,EAAE;GAC9B,IAAI,QAAQ,KAAA,GAAW;IACnB,MAAM,OAAO,KAAK,IAAI,KAAK;IAC3B,IAAI,OAAO,MAAM,OAAO,KAAK;IAEtB,OAAO,KAAK,QAAQ,EAAE,CAAC,CAAC,SAAS,KAC7B,KAAK,MAAM,OAAO,KAAK;IADlC;;GAKJ,KAAK,MAAM,OAAO,KAAK;SACpB,KAAK,OAAO;;;;;CAMvB,OAAO,cAAc;EACjB,KAAK,MAAM,OAAO"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@arkstack/foundry",
+  "version": "0.11.0",
+  "type": "module",
+  "description": "Extensibility primitives and framework internals for the Arkstack ecosystem.",
+  "homepage": "https://arkstack.toneflix.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkstack-tmp/arkstack.git",
+    "directory": "packages/foundry"
+  },
+  "keywords": [
+    "foundry",
+    "utilities",
+    "helpers",
+    "logging",
+    "configuration",
+    "error-handling",
+    "validation",
+    "arkstack"
+  ],
+  "files": [
+    "dist",
+    "resources"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "version:patch": "pnpm version patch"
+  }
+}