@cldmv/slothlet-types 3.15.2 → 3.16.0

package/lib/handlers/hook-manager.d.mts

@@ -1,5 +1,22 @@
+/**
+ * Manages hooks for API function interception.
+ * Supports before/after/always/error hooks with pattern matching and priority ordering.
+ *
+ * @class HookManager
+ * @extends ComponentBase
+ */
 export class HookManager extends ComponentBase {
+    /**
+     * Property name for auto-discovery
+     * @type {string}
+     * @static
+     */
     static slothletProperty: string;
+    /**
+     * Creates a new HookManager instance.
+     * @param {object} slothlet - Parent slothlet instance
+     */
+    constructor(slothlet: object);
     enabled: boolean;
     defaultPattern: string;
     suppressErrors: boolean;
@@ -9,80 +26,296 @@ export class HookManager extends ComponentBase {
     hooks: Map<any, any>;
     registrationOrder: number;
     reportedErrors: WeakSet<object>;
-    on(typePattern: any, handler: any, options?: {}): any;
-    remove(filter?: {}): number;
-    enable(filter?: {}): number;
-    disable(filter?: {}): number;
-    enablePattern(pattern: any): number;
-    disablePattern(pattern: any): number;
-    resetPatternFilter(): void;
-    setPinEnforced(value: any): boolean;
-    list(filter?: {}): {
-        registeredHooks: {
-            id: any;
-            type: any;
-            pattern: any;
-            priority: any;
-            subset: any;
-            enabled: any;
-            lockCaller: any;
-        }[];
+    /**
+     * Register a hook for API functions.
+     *
+     * @param {string} typePattern - Path pattern then hook type, `"pattern:type"` (e.g. `"math.*:before"`).
+     *   The legacy `"type:pattern"` form (e.g. `"before:math.*"`) is still accepted but deprecated.
+     * @param {function} handler - Hook handler function
+     * @param {object} [options={}] - Hook options
+     * @param {string} [options.id] - Unique identifier (auto-generated if not provided)
+     * @param {number} [options.priority=0] - Higher = earlier execution
+     * @param {string} [options.subset=DEFAULT_HOOK_SUBSET] - Phase: "before", "primary", or "after" ({@link HOOK_SUBSETS})
+     * @param {boolean} [options.lockCaller=true] - Pin the registering module's caller
+     *   identity onto the handler so its `self.*` calls and permission checks are
+     *   attributed to the module that registered the hook, not the caller whose API
+     *   call triggered it. On by default; pass `false` to opt out — the handler then
+     *   runs un-pinned, with whatever async context is ambient when it fires (for a
+     *   `before` hook, typically none, so a `self.*` call inside it has no context).
+     *   No effect when the hook is registered outside a module (no caller identity to
+     *   capture) or when `handler` is already a `lockCaller`-wrapped function.
+     * @returns {string} Hook ID
+     * @public
+     *
+     * @example
+     * hookManager.on("math.*:before", ({ args }) => {
+     *   console.log("Args:", args);
+     *   return args;
+     * }, { priority: 100 });
+     */
+    public on(typePattern: string, handler: Function, options?: {
+        id?: string | undefined;
+        priority?: number | undefined;
+        subset?: string | undefined;
+        lockCaller?: boolean | undefined;
+    }): string;
+    /**
+     * Remove hooks matching filter criteria.
+     *
+     * @param {object} [filter={}] - Filter criteria
+     * @param {string} [filter.id] - Remove hook by ID
+     * @param {string} [filter.type] - Remove hooks by type
+     * @param {string} [filter.pattern] - Remove hooks matching pattern
+     * @returns {number} Number of hooks removed
+     * @public
+     */
+    public remove(filter?: {
+        id?: string | undefined;
+        type?: string | undefined;
+        pattern?: string | undefined;
+    }): number;
+    /**
+     * Enable hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = enable all, string = pattern)
+     * @param {string} [filter.id] - Enable hook by ID
+     * @param {string} [filter.type] - Enable hooks by type
+     * @param {string} [filter.pattern] - Enable hooks matching pattern
+     * @returns {number} Number of hooks enabled
+     * @public
+     */
+    public enable(filter?: object | string): number;
+    /**
+     * Disable hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = disable all, string = pattern)
+     * @param {string} [filter.id] - Disable hook by ID
+     * @param {string} [filter.type] - Disable hooks by type
+     * @param {string} [filter.pattern] - Disable hooks matching pattern
+     * @returns {number} Number of hooks disabled
+     * @public
+     */
+    public disable(filter?: object | string): number;
+    /**
+     * Restrict hook execution to a path pattern at runtime (the global path filter).
+     *
+     * Distinct from {@link enable}/{@link disable}, which toggle the `enabled` flag of
+     * individual registered hooks by their registration pattern. This narrows *which API
+     * paths* the hook system applies to at all — the runtime counterpart of the `hook.pattern`
+     * config. Once any pattern is enabled the filter is active, and a hook fires only when the
+     * called path matches at least one enabled pattern. Adding `"**"` matches every path.
+     *
+     * @param {string} pattern - Glob path pattern to restrict execution to (e.g. "math.*").
+     * @returns {number} The number of patterns now in the active filter.
+     * @public
+     *
+     * @example
+     * api.slothlet.hook.enablePattern("database.*"); // only intercept database.* paths
+     */
+    public enablePattern(pattern: string): number;
+    /**
+     * Remove a path pattern from the runtime global path filter.
+     *
+     * When the last enabled pattern is removed the filter deactivates, so hooks once again
+     * apply to every path (an unrestricted state, matching a `"**"` default).
+     *
+     * @param {string} pattern - The previously-enabled path pattern to remove.
+     * @returns {number} The number of patterns remaining in the filter.
+     * @public
+     *
+     * @example
+     * api.slothlet.hook.disablePattern("database.*"); // stop restricting to database.*
+     */
+    public disablePattern(pattern: string): number;
+    /**
+     * Reset the runtime global path filter back to the configured `hook.pattern` default.
+     *
+     * Clears any runtime {@link enablePattern}/{@link disablePattern} changes. If the configured
+     * default is the catch-all `"**"` the filter ends up inactive (unrestricted); otherwise it is
+     * re-seeded with the configured pattern.
+     *
+     * @returns {void}
+     * @public
+     */
+    public resetPatternFilter(): void;
+    /**
+     * Set the pin-enforcement policy at runtime (backs `api.slothlet.hook.pin.enable`/`disable`).
+     * When true (the default) module hooks are force-pinned to their owner; false permits a
+     * per-registration `lockCaller: false`. The public wrapper is host-only when permissions are
+     * enabled — `slothlet.hook.pin.*` falls under the `slothlet.hook.**` deny baseline.
+     *
+     * @param {boolean} value - True to enforce pinning (force-pin module hooks), false to permit unpinned.
+     * @returns {boolean} The policy value now in effect.
+     * @public
+     */
+    public setPinEnforced(value: boolean): boolean;
+    /**
+     * List registered hooks matching filter criteria.
+     *
+     * @param {object|string} [filter={}] - Filter criteria (empty = list all), type string, or pattern string
+     * @param {string} [filter.id] - List hook by ID
+     * @param {string} [filter.type] - List hooks by type
+     * @param {string} [filter.pattern] - List hooks matching pattern
+     * @param {boolean} [filter.enabled] - Filter by enabled state
+     * @returns {object} Object with registeredHooks array property
+     * @public
+     */
+    public list(filter?: object | string): object;
+    /**
+     * Get hooks for a specific API path and type.
+     * Used internally by UnifiedWrapper.
+     *
+     * @param {string} type - Hook type (before/after/always/error)
+     * @param {string} apiPath - API path (e.g., "math.add")
+     * @returns {Array<object>} Sorted array of matching hooks
+     * @public
+     */
+    public getHooksForPath(type: string, apiPath: string): Array<object>;
+    /**
+     * Derive the dispatch strategy for a path from the current hook set.
+     *
+     * @param {string} path - API path about to be called
+     * @returns {{asyncBefore: boolean, asyncAfter: boolean}} Whether any matching transforming
+     *   hook is asynchronous.
+     * @public
+     *
+     * @description
+     * The strategy is a property of the CALL, derived per invocation from the registration state —
+     * never baked onto the leaf, so removing an async hook returns the path to synchronous
+     * dispatch. Only TRANSFORMING hooks (before/after) are consulted: `always` and `error` are
+     * observers whose return values are never consumed, so they never force promotion. Cached per
+     * path behind the registry epoch; the hot-path cost is one integer compare.
+     */
+    public getDispatchStrategy(path: string): {
+        asyncBefore: boolean;
+        asyncAfter: boolean;
     };
-    getHooksForPath(type: any, apiPath: any): any[];
-    getDispatchStrategy(path: any): any;
-    executeBeforeHooks(path: any, args: any, api: any, ctx: any): {
-        args: any;
-        shortCircuit: boolean;
-        value: any;
-    } | {
-        args: any;
-        shortCircuit: boolean;
-        value?: undefined;
-    };
-    executeAfterHooks(path: any, result: any, args: any, api: any, ctx: any): {
-        modified: boolean;
-        result?: undefined;
-    } | {
-        modified: boolean;
-        result: any;
-    };
-    executeBeforeHooksAsync(path: any, args: any, api: any, ctx: any): Promise<{
-        args: any;
-        shortCircuit: boolean;
-        value: any;
-    } | {
-        args: any;
-        shortCircuit: boolean;
-        value?: undefined;
-    }>;
-    executeAfterHooksAsync(path: any, result: any, args: any, api: any, ctx: any): Promise<{
-        modified: boolean;
-        result?: undefined;
-    } | {
-        modified: boolean;
-        result: any;
-    }>;
-    executeAlwaysHooks(path: any, args: any, resultOrError: any, hasError: boolean | undefined, errors: any[] | undefined, api: any, ctx: any): void;
-    executeErrorHooks(path: any, error: any, source: any, args: any, api: any, ctx: any): void;
-    getCompilePatternForDiagnostics(): (pattern: any) => any;
-    exportHooks(): {
-        typePattern: string;
-        handler: any;
-        options: {
-            id: any;
-            priority: any;
-            subset: any;
-            lockCaller: any;
-            async: any;
-        };
-        ownerPath: any;
-        version: any;
-        groupId: any;
-        ownerFilePath: any;
-        enabled: any;
-    }[];
-    importHooks(registrations: any): void;
-    shutdown(): Promise<void>;
+    /**
+     * Execute before hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Array} args - Function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {object} Result object: { args, shortCircuit, value }
+     * @public
+     */
+    public executeBeforeHooks(path: string, args: any[], api: object, ctx: object): object;
+    /**
+     * Execute after hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {*} result - Function return value
+     * @param {Array} args - Original function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {HookExecutionResult} Object indicating if result was modified and the final result
+     * @public
+     */
+    public executeAfterHooks(path: string, result: any, args: any[], api: object, ctx: object): HookExecutionResult;
+    /**
+     * Execute before hooks asynchronously — the promoted-pipeline twin of
+     * {@link executeBeforeHooks}.
+     *
+     * @param {string} path - API path being called
+     * @param {Array} args - Function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {Promise<object>} Result object: { args, shortCircuit, value }
+     * @public
+     *
+     * @description
+     * Same protocol and strict registration order as the sync variant, with one difference: a
+     * handler's thenable return is AWAITED rather than refused — the caller of a promoted path
+     * already receives a Promise, so awaiting the chain changes nothing observable. A synchronous
+     * handler's return is used as-is (no microtask tick is inserted for it).
+     */
+    public executeBeforeHooksAsync(path: string, args: any[], api: object, ctx: object): Promise<object>;
+    /**
+     * Execute after hooks asynchronously — the promoted-pipeline twin of
+     * {@link executeAfterHooks}.
+     *
+     * @param {string} path - API path being called
+     * @param {*} result - Function return value (already settled)
+     * @param {Array} args - Original function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @returns {Promise<HookExecutionResult>} Object indicating if result was modified and the final result
+     * @public
+     *
+     * @description
+     * Same protocol and ordering as the sync variant; a thenable transform is awaited (that is the
+     * cell this pipeline exists for) and a synchronous transform costs no microtask tick.
+     */
+    public executeAfterHooksAsync(path: string, result: any, args: any[], api: object, ctx: object): Promise<HookExecutionResult>;
+    /**
+     * Execute always hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Array} args - Function arguments
+     * @param {*} resultOrError - Function result or error
+     * @param {boolean} hasError - Whether an error occurred
+     * @param {Array<Error>} errors - Array of errors that occurred
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @public
+     */
+    public executeAlwaysHooks(path: string, args: any[], resultOrError: any, hasError: boolean | undefined, errors: Array<Error> | undefined, api: object, ctx: object): void;
+    /**
+     * Execute error hooks for an API path.
+     *
+     * @param {string} path - API path being called
+     * @param {Error} error - The error that occurred
+     * @param {object} source - Error source info with type, hookTag, hookId, timestamp, stack
+     * @param {Array} args - Function arguments
+     * @param {object} api - Bound API object
+     * @param {object} ctx - User context object
+     * @public
+     */
+    public executeErrorHooks(path: string, error: Error, source: object, args: any[], api: object, ctx: object): void;
+    /**
+     * Get the pattern compilation function for diagnostic purposes.
+     * Only exposed when diagnostics mode is enabled.
+     *
+     * @returns {function} The pattern compilation function
+     * @internal
+     */
+    getCompilePatternForDiagnostics(): Function;
+    /**
+     * Export all registered hooks (including handler closures) so they can be
+     * re-registered on a fresh HookManager instance after a full reload.
+     *
+     * @returns {Array<object>} Snapshot of all current hook registrations.
+     * @public
+     */
+    public exportHooks(): Array<object>;
+    /**
+     * Re-register hooks exported by {@link exportHooks} into this (new) instance.
+     * Called after a full `api.slothlet.reload()` to restore user-registered hooks.
+     *
+     * @param {Array<object>} registrations - Snapshot returned by exportHooks().
+     * @returns {void}
+     * @public
+     */
+    public importHooks(registrations: Array<object>): void;
+    /**
+     * Cleanup hook manager on shutdown.
+     * @public
+     */
+    public shutdown(): Promise<void>;
     #private;
 }
+/**
+ * Result returned by hook execution methods.
+ */
+export type HookExecutionResult = {
+    /**
+     * - Whether any hook modified the result value.
+     */
+    modified: boolean;
+    /**
+     * - The final (possibly hook-modified) return value.
+     */
+    result?: any;
+};
 import { ComponentBase } from "#factories/component-base";

package/lib/handlers/lifecycle-token.d.mts

@@ -1,3 +1,48 @@
-export function getInstanceToken(slothlet: any): any;
-export function registerInstance(slothlet: any): void;
-export function verifyToken(slothlet: any, token: any): boolean;
+/**
+ * Registers a Slothlet instance and creates its per-instance lifecycle capability token.
+ *
+ * Safe to call multiple times on the same instance (idempotent) — subsequent calls are
+ * silently ignored, preserving the original token. This handles the reload code path where
+ * `load()` is called again on the same Slothlet object.
+ *
+ * @param {object} slothlet - The Slothlet instance to register.
+ * @returns {void}
+ * @package
+ *
+ * @example
+ * // Called once (or on reload) in Slothlet.load():
+ * registerInstance(this);
+ */
+export function registerInstance(slothlet: object): void;
+/**
+ * Returns the per-instance capability token for the given Slothlet instance.
+ *
+ * Used internally by `lifecycle.mjs` (emit dispatch) and `modes-processor.mjs`
+ * (direct tagSystemMetadata call for folder wrappers). Requires a live registered
+ * Slothlet instance — cannot be exploited without one.
+ *
+ * @param {object} slothlet - A registered Slothlet instance.
+ * @returns {symbol|undefined} The instance token, or undefined if not registered.
+ * @package
+ *
+ * @example
+ * handler(data, getInstanceToken(this.slothlet));
+ */
+export function getInstanceToken(slothlet: object): symbol | undefined;
+/**
+ * Verifies that `token` is the registered capability token for the given Slothlet instance.
+ *
+ * Used by `metadata.mjs` inside `tagSystemMetadata()` to reject calls that did not
+ * originate from the internal lifecycle dispatch path.
+ *
+ * @param {object} slothlet - A registered Slothlet instance.
+ * @param {*} token - The token value to verify.
+ * @returns {boolean} `true` only if `token` is the exact Symbol registered for `slothlet`.
+ * @package
+ *
+ * @example
+ * if (!verifyToken(this.slothlet, token)) {
+ *   throw new this.SlothletError("METADATA_LIFECYCLE_BYPASS", ...);
+ * }
+ */
+export function verifyToken(slothlet: object, token: any): boolean;

package/lib/handlers/lifecycle.d.mts

@@ -1,12 +1,93 @@
+/**
+ * Lifecycle event manager for impl changes
+ * @extends ComponentBase
+ * @public
+ */
 export class Lifecycle extends ComponentBase {
+    /**
+     * Where this component should be mounted on the Slothlet instance
+     * @type {string}
+     */
     static slothletProperty: string;
+    /**
+     * @param {object} slothlet - Slothlet instance
+     */
+    constructor(slothlet: object);
     subscribers: Map<any, any>;
     eventLog: any[];
     maxLogSize: number;
-    subscribe(event: any, handler: any): () => void;
-    on(event: any, handler: any): () => void;
-    off(event: any, handler: any): void;
-    unsubscribe(event: any, handler: any): void;
-    emit(event: any, data: any): Promise<void>;
+    /**
+     * Subscribe to lifecycle event
+     * @param {string} event - Event name (impl:created, impl:changed, impl:removed, materialized:complete, path:collision)
+     * @param {Function} handler - Event handler function(eventData)
+     * @returns {Function} Unsubscribe function
+     * @public
+     *
+     * @description
+     * Subscribe to lifecycle events to react to impl changes.
+     *
+     * @example
+     * const unsubscribe = lifecycle.subscribe("impl:changed", (data) => {
+     *   console.log("Impl changed:", data.apiPath, data.source);
+     * });
+     */
+    public subscribe(event: string, handler: Function): Function;
+    /**
+     * Alias for subscribe() - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function
+     * @returns {Function} Unsubscribe function
+     * @public
+     *
+     * @example
+     * lifecycle.on('materialized:complete', (data) => {
+     *   console.log(`${data.total} modules materialized`);
+     * });
+     */
+    public on(event: string, handler: Function): Function;
+    /**
+     * Unsubscribe from lifecycle event - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function to remove
+     * @public
+     *
+     * @example
+     * const handler = (data) => console.log(data);
+     * lifecycle.on('impl:changed', handler);
+     * lifecycle.off('impl:changed', handler);
+     */
+    public off(event: string, handler: Function): void;
+    /**
+     * Alias for off() - standard EventEmitter pattern
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler function to remove
+     * @public
+     */
+    public unsubscribe(event: string, handler: Function): void;
+    /**
+     * Emit lifecycle event
+     * @param {string} event - Event name
+     * @param {object} data - Event data
+     * @private
+     *
+     * @description
+     * Emit event to all subscribers. Event data should include:
+     * - apiPath: API path where impl exists
+     * - impl: The implementation object
+     * - source: Source of event (initial, hot-reload, materialization, etc)
+     * - moduleID: Module identifier (if applicable)
+     * - filePath: File path (if applicable)
+     * - metadata: Additional metadata
+     *
+     * @example
+     * lifecycle.emit("impl:created", {
+     *   apiPath: "math.add",
+     *   impl: addFunction,
+     *   source: "initial",
+     *   moduleID: "base_abc123",
+     *   filePath: "/path/to/math.mjs"
+     * });
+     */
+    private emit;
 }
 import { ComponentBase } from "#factories/component-base";

package/lib/handlers/materialize-manager.d.mts

@@ -1,12 +1,80 @@
+/**
+ * Manager for tracking lazy folder materialization state
+ * @class MaterializeManager
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Provides access to lazy materialization state via `api.slothlet.materialize`.
+ * Tracks count of unmaterialized lazy folders and provides boolean state, statistics,
+ * and wait functionality for synchronization.
+ *
+ * @example
+ * const api = await slothlet({ base: "./api", mode: "lazy" });
+ *
+ * // Check if fully materialized
+ * if (api.slothlet.materialize.materialized) {
+ *   console.log("All lazy folders loaded!");
+ * }
+ *
+ * // Get statistics
+ * const stats = api.slothlet.materialize.get();
+ * console.log(`${stats.percentage}% loaded (${stats.remaining}/${stats.total} remaining)`);
+ *
+ * // Wait for full materialization
+ * await api.slothlet.materialize.wait();
+ */
 export class MaterializeManager extends ComponentBase {
     static slothletProperty: string;
-    get materialized(): boolean;
-    get(): {
-        total: any;
-        materialized: number;
-        remaining: any;
-        percentage: number;
-    };
-    wait(): Promise<any>;
+    /**
+     * Create MaterializeManager instance
+     * @param {object} slothlet - Slothlet orchestrator instance
+     * @package
+     */
+    constructor(slothlet: object);
+    /**
+     * Get materialization state as a boolean
+     * Returns true when all lazy wrappers have been materialized
+     * @returns {boolean} True if fully materialized, false if any lazy folders remain
+     * @public
+     *
+     * @example
+     * if (api.slothlet.materialize.materialized) {
+     *   console.log("API is fully loaded");
+     * }
+     */
+    public get materialized(): boolean;
+    /**
+     * Get detailed materialization statistics
+     * @returns {Object} Statistics object with total, materialized, remaining, percentage
+     * @public
+     *
+     * @example
+     * const stats = api.slothlet.materialize.get();
+     * // { total: 5, materialized: 3, remaining: 2, percentage: 60 }
+     */
+    public get(): Object;
+    /**
+     * Wait for full materialization (all lazy folders loaded)
+     * Returns immediately if already fully materialized
+     * @returns {Promise<void>} Resolves when all lazy wrappers have materialized
+     * @public
+     *
+     * @example
+     * // Wait for API to fully load
+     * await api.slothlet.materialize.wait();
+     * console.log("All modules loaded!");
+     *
+     * @example
+     * // Wait with timeout
+     * const timeoutPromise = new Promise((_, reject) =>
+     *   setTimeout(() => reject(new Error("Timeout")), 5000)
+     * );
+     * await Promise.race([
+     *   api.slothlet.materialize.wait(),
+     *   timeoutPromise
+     * ]);
+     */
+    public wait(): Promise<void>;
 }
 import { ComponentBase } from "#factories/component-base";