@cldmv/slothlet-types 3.15.3 → 3.16.0

package/lib/helpers/class-instance-wrapper.d.mts

@@ -1,3 +1,57 @@
+/**
+ * @function runtime_shouldWrapMethod
+ * @package
+ * @param {*} value - The value to check
+ * @param {string|symbol} prop - The property name
+ * @returns {boolean} True if the method should be wrapped
+ *
+ * @description
+ * Determines if a method should be wrapped with context preservation.
+ * Excludes constructors, Object.prototype methods, and internal methods.
+ *
+ * @example
+ * runtime_shouldWrapMethod(myInstance.method, "method"); // true
+ * runtime_shouldWrapMethod(myInstance.constructor, "constructor"); // false
+ */
+export function runtime_shouldWrapMethod(value: any, prop: string | symbol): boolean;
+/**
+ * @function runtime_isClassInstance
+ * @package
+ * @param {*} val - The value to check
+ * @returns {boolean} True if the value is a class instance that should be wrapped
+ *
+ * @description
+ * Determines if a value is a class instance (not a plain object, array, or primitive)
+ * that should have its methods wrapped to preserve AsyncLocalStorage context.
+ * Uses systematic exclusion lists for better maintainability.
+ *
+ * @example
+ * // Check if value is a class instance
+ * const isInstance = runtime_isClassInstance(new MyClass());
+ */
 export function runtime_isClassInstance(val: any): boolean;
-export function runtime_shouldWrapMethod(value: any, prop: any): boolean;
-export function runtime_wrapClassInstance(instance: any, contextManager: any, instanceID: any, instanceCache: any, capturedWrapper: any): any;
+/**
+ * @function runtime_wrapClassInstance
+ * @package
+ * @param {object} instance - The class instance to wrap
+ * @param {object} contextManager - The context manager (async or live)
+ * @param {string} instanceID - The slothlet instance ID
+ * @param {WeakMap} instanceCache - The cache for wrapped instances
+ * @param {object} [capturedWrapper] - Wrapper of the module that created this instance,
+ *   snapshotted at wrap time. Used as the caller identity for the instance's method calls so
+ *   that `self.*` calls from a class method are permission-checked as the creating module
+ *   (the method is neither exempt from nor spuriously denied by the permission layer).
+ * @returns {Proxy} A proxied instance with context-aware method calls
+ *
+ * @description
+ * Wraps a class instance so that all method calls maintain the AsyncLocalStorage context.
+ * This ensures that calls to methods on returned class instances preserve the slothlet
+ * context for runtime imports like `self` and `context`.
+ *
+ * V3 Adaptation: Uses contextManager.runInContext() instead of V2's runWithCtx().
+ *
+ * @example
+ * // Wrap a class instance to preserve context
+ * const wrappedInstance = runtime_wrapClassInstance(instance, contextManager, instanceID, instanceCache, creatingWrapper);
+ */
+export function runtime_wrapClassInstance(instance: object, contextManager: object, instanceID: string, instanceCache: WeakMap<any, any>, capturedWrapper?: object): ProxyConstructor;

package/lib/helpers/config.d.mts

@@ -1,170 +1,320 @@
+/**
+ * Normalize the `hook` config (V2-style support) into a canonical
+ * `{ enabled, pattern, suppressErrors }` object.
+ *
+ * Accepts the boolean form (enable/disable with the catch-all pattern), the string form
+ * (enable, restricting hooks to a global path pattern — e.g. `"database.*"`), or the full
+ * object form. Idempotent: an already-normalized object normalizes to an equivalent object,
+ * so `reload()` can re-feed it.
+ *
+ * Exported as a standalone function (not just a {@link Config} method) because the HookManager
+ * is constructed during `_initializeComponents` — BEFORE `transformConfig` runs — so it cannot
+ * rely on the normalized config being in place yet, and must normalize the raw `config.hook`
+ * itself from the same source of truth.
+ *
+ * @param {boolean|string|Object} [hook] - Raw hook config in any supported form.
+ * @returns {{enabled: boolean, pattern: (string|null), suppressErrors: boolean, pin: boolean}} Normalized hook config.
+ * @public
+ */
+export function normalizeHookConfig(hook?: boolean | string | Object): {
+    enabled: boolean;
+    pattern: (string | null);
+    suppressErrors: boolean;
+    pin: boolean;
+};
+/**
+ * Configuration normalization utilities
+ * @class Config
+ * @extends ComponentBase
+ * @public
+ */
 export class Config extends ComponentBase {
     static slothletProperty: string;
-    normalizeCollision(collision: any): {
-        initial: string;
-        api: string;
-    };
-    normalizeRuntime(runtime: any): "async" | "live";
-    normalizeMode(mode: any): "eager" | "lazy";
-    normalizeMutations(mutations: any): {
-        add: boolean;
-        remove: boolean;
-        reload: boolean;
-        permissions: boolean;
-    };
-    normalizeDebug(debug: any): {
-        builder: any;
-        api: any;
-        index: any;
-        modes: any;
-        wrapper: any;
-        ownership: any;
-        context: any;
-        initialization: any;
-        materialize: any;
-        versioning: any;
-        permissions: any;
-    };
-    normalizeEnvTarget(platform: any, hasManifest?: boolean): "browser" | "node";
-    normalizeHook(hook: any): {
+    /**
+     * Normalize collision configuration for handling property collisions
+     * @param {string|Object} collision - Collision mode or object with per-context modes
+     * @returns {Object} Normalized collision configuration with initial and api.slothlet.api.add modes
+     * @public
+     *
+     * @description
+     * Normalizes collision handling configuration for both initial load (buildAPI)
+     * and hot reload (api.add) contexts. Supports six collision modes:
+     * - "skip": Silently ignore collision, keep existing value
+     * - "warn": Warn about collision, keep existing value
+     * - "replace": Replace existing value completely
+     * - "merge": Merge properties (preserve original + add new)
+     * - "merge-replace": Merge properties (add new + overwrite existing with new values)
+     * - "error": Throw error on collision
+     *
+     * @example
+     * // String shorthand applies to both contexts
+     * normalizeCollision("merge")
+     * // => { initial: "merge", api: "merge" }
+     *
+     * @example
+     * // Object allows per-context control
+     * normalizeCollision({ initial: "warn", api: "error" })
+     * // => { initial: "warn", api: "error" }
+     */
+    public normalizeCollision(collision: string | Object): Object;
+    /**
+     * Normalize runtime input to internal standard format
+     * @param {string} runtime - Input runtime type (various formats accepted)
+     * @returns {string} Normalized runtime type ("async" or "live")
+     * @public
+     */
+    public normalizeRuntime(runtime: string): string;
+    /**
+     * Normalize mode input to internal standard format
+     * @param {string} mode - Input mode type (various formats accepted)
+     * @returns {string} Normalized mode type ("eager" or "lazy")
+     * @public
+     */
+    public normalizeMode(mode: string): string;
+    /**
+     * Normalize mutations configuration for API modification control
+     * @param {Object} mutations - Mutations config object with add/remove/reload properties
+     * @returns {Object} Normalized mutations configuration
+     * @public
+     *
+     * @description
+     * Normalizes mutation control configuration for API runtime modifications.
+     * Controls whether api.slothlet.api.add(), api.slothlet.api.remove(), and
+     * api.slothlet.reload() operations are allowed.
+     *
+     * @example
+     * // Allow all mutations (default)
+     * normalizeMutations({ add: true, remove: true, reload: true })
+     * // => { add: true, remove: true, reload: true }
+     *
+     * @example
+     * // Disable all mutations
+     * normalizeMutations({ add: false, remove: false, reload: false })
+     * // => { add: false, remove: false, reload: false }
+     */
+    public normalizeMutations(mutations: Object): Object;
+    /**
+     * Normalize debug configuration
+     * @param {boolean|Object} debug - Debug flag or object with targeted flags
+     * @returns {Object} Normalized debug object with all flags
+     * @public
+     */
+    public normalizeDebug(debug: boolean | Object): Object;
+    /**
+     * Normalize execution-environment target from the raw `platform` config value.
+     *
+     * @description
+     * Distinct from `normalizeEnv()` which handles the `process.env` snapshot
+     * allowlist (`config.env`). This method determines *where* slothlet is executing
+     * so that filesystem-dependent code paths can be bypassed in browser/worker builds.
+     *
+     * When `platform` is omitted the method auto-detects by checking whether
+     * `process.versions.node` is available (true in Node.js; absent or undefined
+     * in browsers, web workers, and Electron renderers without nodeIntegration).
+     * Pass `"browser"` or `"node"` to override auto-detection for edge cases
+     * (e.g. Deno, Electron with custom process polyfills).
+     *
+     * @param {*} platform - Raw value of `config.platform` before normalisation.
+     * @returns {"browser"|"node"} Execution-environment target.
+     * @public
+     *
+     * @example
+     * normalizeEnvTarget("browser"); // => "browser" (explicit override)
+     * normalizeEnvTarget("node");    // => "node"    (explicit override)
+     * normalizeEnvTarget(undefined); // => "browser" or "node" (auto-detected)
+     */
+    public normalizeEnvTarget(platform: any, hasManifest?: boolean): "browser" | "node";
+    /**
+     * Normalize the `hook` config (V2-style support) into a canonical
+     * `{ enabled, pattern, suppressErrors }` object.
+     *
+     * Accepts the boolean form (enable/disable with the catch-all pattern), the string form
+     * (enable, restricting hooks to a global path pattern — e.g. `"database.*"`), or the full
+     * object form. Idempotent: an already-normalized object normalizes to an equivalent object,
+     * so `reload()` can re-feed it. Shared by {@link transformConfig} and the HookManager so both
+     * derive the same values regardless of construction order (the manager is built before
+     * transformConfig runs, so it cannot rely on the normalized config being in place yet).
+     *
+     * @param {boolean|string|Object} [hook] - Raw hook config in any supported form.
+     * @returns {{enabled: boolean, pattern: (string|null), suppressErrors: boolean, pin: boolean}} Normalized hook config.
+     * @public
+     */
+    public normalizeHook(hook?: boolean | string | Object): {
         enabled: boolean;
-        pattern: string;
+        pattern: (string | null);
         suppressErrors: boolean;
         pin: boolean;
     };
-    transformConfig(config?: {}): {
-        base: any;
-        dir: any;
-        manifest: any;
-        resolveModuleSpecifier: any;
-        envTarget: string;
-        mode: string;
-        runtime: string;
-        apiDepth: any;
-        reference: any;
-        context: any;
-        i18n: {
-            language: any;
-        } | null;
-        lifecycle: any;
-        debug: {
-            builder: any;
-            api: any;
-            index: any;
-            modes: any;
-            wrapper: any;
-            ownership: any;
-            context: any;
-            initialization: any;
-            materialize: any;
-            versioning: any;
-            permissions: any;
-        };
-        diagnostics: boolean;
-        collectLifecycleHooks: boolean;
-        hook: {
-            enabled: boolean;
-            pattern: string;
-            suppressErrors: boolean;
-            pin: boolean;
-        };
-        collision: {
-            initial: string;
-            api: string;
-        };
-        api: {
-            collision: {
-                initial: string;
-                api: string;
-            };
-            mutations: {
-                add: boolean;
-                remove: boolean;
-                reload: boolean;
-                permissions: boolean;
-            } | {
-                add: boolean;
-                remove: boolean;
-                reload: boolean;
-            };
-        };
-        scope: any;
-        tracking: {
-            materialization: boolean;
-        };
-        backgroundMaterialize: boolean;
-        silent: boolean;
-        typescript: {
-            enabled: boolean;
-            mode: string;
-            types?: undefined;
-            target?: undefined;
-            sourcemap?: undefined;
-        } | {
-            enabled: boolean;
-            mode: string;
-            types: any;
-            target: any;
-            sourcemap: any;
-        } | null;
-        env: {
-            include: any;
-        } | null;
-        versionDispatcher: any;
-        import: any;
-        permissions: {
-            defaultPolicy: string;
-            enabled: boolean;
-            audit: string;
-            readGating: boolean;
-            failOpenOnAbsentCaller: boolean;
-            references: {
-                capture: boolean;
-            };
-            private: {
-                host: string;
-            };
-            rules: any;
-        } | null;
-        suppressFixes: Set<any>;
-    };
-    normalizeSuppressFixes(suppressFixes: any, silent: any): Set<any>;
-    normalizeTypeScript(typescript: any): {
-        enabled: boolean;
-        mode: string;
-        types?: undefined;
-        target?: undefined;
-        sourcemap?: undefined;
-    } | {
-        enabled: boolean;
-        mode: string;
-        types: any;
-        target: any;
-        sourcemap: any;
-    } | null;
-    normalizeEnv(env: any): {
-        include: any;
-    } | null;
-    normalizeLifecycle(lifecycle: any): any;
-    normalizePermissions(permissions: any): {
-        defaultPolicy: string;
-        enabled: boolean;
-        audit: string;
-        readGating: boolean;
-        failOpenOnAbsentCaller: boolean;
-        references: {
-            capture: boolean;
-        };
-        private: {
-            host: string;
-        };
-        rules: any;
+    /**
+     * Transform and validate configuration
+     * @param {Object} config - Raw configuration options
+     * @returns {Object} Normalized configuration
+     * @throws {SlothletError} If configuration is invalid
+     * @public
+     */
+    public transformConfig(config?: Object): Object;
+    /**
+     * Normalize and validate the suppressFixes option. Emits a deprecation warning for each
+     * rule ID present. Invalid entries (non-strings, unknown rule IDs) are silently dropped.
+     *
+     * @param {string[]|undefined} suppressFixes - Raw suppressFixes value from user config.
+     * @param {boolean} silent - If true, suppress warnings.
+     * @returns {Set<string>} Normalized set of suppressed rule IDs.
+     * @example
+     * // Rule IDs use the <rule>_<PR> form. The C03 fix landed in PR #116.
+     * normalizeSuppressFixes(["C03_116"], false); // emits WARN_SUPPRESS_FIX_ACTIVE for C03_116
+     * @public
+     */
+    public normalizeSuppressFixes(suppressFixes: string[] | undefined, silent: boolean): Set<string>;
+    /**
+     * Normalize TypeScript configuration
+     * @param {boolean|string|Object} typescript - TypeScript config (true, "fast", or { mode: "fast"|"strict", ... })
+     * @returns {Object|null} Normalized TypeScript configuration or null if disabled
+     * @public
+     */
+    public normalizeTypeScript(typescript: boolean | string | Object): Object | null;
+    /**
+     * Normalize env snapshot configuration.
+     *
+     * @description
+     * Validates the `env` option from user config. When `include` is a non-empty
+     * string array, returns `{ include }` (the allowlist used by `_captureEnvSnapshot`).
+     * Any other value — including `undefined`, `null`, `{}`, or an empty `include`
+     * array — is normalised to `null`, meaning the full `process.env` snapshot is used.
+     *
+     * @param {Object|null|undefined} env - Raw env option from user config.
+     * @param {string[]} [env.include] - Allowlist of env variable names to capture.
+     * @returns {{ include: string[] }|null} Normalized env config, or `null` for full snapshot.
+     * @public
+     *
+     * @example
+     * // No restriction — full snapshot
+     * normalizeEnv(undefined); // => null
+     * normalizeEnv(null);      // => null
+     * normalizeEnv({});        // => null
+     *
+     * @example
+     * // Include allowlist
+     * normalizeEnv({ include: ["NODE_ENV", "PORT"] });
+     * // => { include: ["NODE_ENV", "PORT"] }
+     *
+     * @example
+     * // Non-string keys in the include array are filtered out
+     * normalizeEnv({ include: ["NODE_ENV", 42, null] });
+     * // => { include: ["NODE_ENV"] }
+     */
+    public normalizeEnv(env: Object | null | undefined): {
+        include: string[];
     } | null;
+    /**
+     * Normalize + validate the construction-time `lifecycle` subscription map (#148).
+     *
+     * @description
+     * The `lifecycle` option registers event handlers on the Lifecycle emitter BEFORE the api builds,
+     * so events emitted during cold-start `buildAPI` (init-time `impl:warning` / `impl:created` / …)
+     * are observable. It is a plain object mapping an event name to a handler function or an array of
+     * handler functions. Any event name is accepted — registration is just early `subscribe()` calls,
+     * so these handlers also receive runtime events afterward.
+     *
+     * Idempotent: an already-normalized map (values already functions / arrays of functions) passes
+     * through unchanged, so `reload()` can re-feed it.
+     *
+     * @param {object|null|undefined} lifecycle - Raw `lifecycle` option from user config.
+     * @returns {object|null} The validated map, or `null` when absent.
+     * @throws {SlothletError} INVALID_CONFIG when the shape is not a plain object of functions / function arrays.
+     * @public
+     *
+     * @example
+     * normalizeLifecycle({ "impl:warning": (data) => log(data) });
+     * // => { "impl:warning": (data) => log(data) }
+     *
+     * @example
+     * normalizeLifecycle({ "impl:error": [onError, auditError] });
+     * // => { "impl:error": [onError, auditError] }
+     */
+    public normalizeLifecycle(lifecycle: object | null | undefined): object | null;
+    /**
+     * Normalize + validate the `routines` config option (#341).
+     *
+     * @description
+     * A routine is a named cross-module runnable: every mounted module that exports a function
+     * matching a configured routine name gets stacked into one chain at its resolved api path, and
+     * a root cascade runs every matching contribution anywhere, ordered per the entry's `order`.
+     * See `docs/LIFECYCLE.md` ("Routines") for the full contract.
+     *
+     * Each entry normalizes to `{ name, mode, recursive, order }` — `recursive` and `order` are
+     * always present on the normalized output, even when the raw entry omitted them:
+     * - `"name"` (string, no `:`) → `{ name, mode: "manual", recursive: false, order: "mount" }`.
+     * - `"name:mode"` (string, split once on the first `:`) → `{ name, mode, recursive: false, order: <mode-defaulted> }`.
+     * - `{ name, mode?, recursive?, order? }` (object) → `mode` defaults to `"manual"`, `recursive` to
+     *   `false`, and `order` to {@link DEFAULT_ROUTINE_ORDER_BY_MODE}`[mode]` when each is omitted.
+     *
+     * Providing `routines` at all REPLACES {@link DEFAULT_ROUTINES} — that is the off-switch
+     * (`routines: []` disables every routine). Omitting the option keeps the built-in defaults.
+     * `slothlet.defaults.routines` is the frozen source of those defaults, exported for a consumer
+     * to spread (extend) or filter (drop one) rather than replace wholesale.
+     *
+     * Idempotent: an already-normalized list (every entry already `{ name, mode, recursive, order }`)
+     * normalizes to an equivalent list — same values, always freshly-built objects (never the same
+     * references) — so `reload()` can safely re-feed it.
+     *
+     * @param {undefined|null|Array<string|{name: string, mode?: string, recursive?: boolean, order?: string}>} routines - Raw `routines` option.
+     * @returns {Array<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy", recursive: boolean, order: "mount"|"depth"}>} Normalized routines list.
+     * @throws {SlothletError} INVALID_CONFIG when the shape is invalid, a name is empty/reserved/an invalid glob, or a mode/order is unrecognized.
+     * @public
+     *
+     * @example
+     * normalizeRoutines(undefined);
+     * // => [{ name: "initialize", mode: "startup", recursive: false, order: "mount" },
+     * //     { name: "shutdown", mode: "shutdown", recursive: false, order: "depth" }]
+     *
+     * @example
+     * normalizeRoutines(["launch", "prefetch:startup", { name: "warmup" }]);
+     * // => [{ name: "launch", mode: "manual", recursive: false, order: "mount" },
+     * //     { name: "prefetch", mode: "startup", recursive: false, order: "mount" },
+     * //     { name: "warmup", mode: "manual", recursive: false, order: "mount" }]
+     *
+     * @example
+     * normalizeRoutines([]);
+     * // => [] — disables every routine
+     */
+    public normalizeRoutines(routines: undefined | null | Array<string | {
+        name: string;
+        mode?: string;
+        recursive?: boolean;
+        order?: string;
+    }>): Array<{
+        name: string;
+        mode: "manual" | "startup" | "shutdown" | "destroy";
+        recursive: boolean;
+        order: "mount" | "depth";
+    }>;
+    /**
+     * Normalize permissions configuration.
+     *
+     * @param {object|null} [permissions] - Raw permissions config from user.
+     * @param {string} [permissions.defaultPolicy="allow"] - Fallback policy: "allow" or "deny".
+     * @param {boolean} [permissions.enabled=true] - Global toggle.
+     * @param {string|boolean} [permissions.audit="default"] - Audit level: `"default"` (denied + self-bypass only),
+     *   `"verbose"` (all decisions). `true` and `false` are accepted and both normalize to `"default"`.
+     * @param {object} [permissions.references] - Options governing api functions held as references.
+     * @param {boolean} [permissions.references.capture=true] - When `true` (the default), a function read
+     *   out of the api carries the identity of the module that read it, so it stays enforced as that module
+     *   wherever it is later invoked. Set `false` to restore the older host-initiated treatment.
+     * @param {boolean} [permissions.failOpenOnAbsentCaller=false] - When `false` (the default), calls
+     *   and reads occurring inside an active context with no resolvable (or forged) caller identity
+     *   fail closed (denied); only genuinely host-initiated calls are exempt via the trusted-root
+     *   marker. Set `true` to restore the legacy fail-open behaviour.
+     * @param {boolean} [permissions.readGating=true] - When `true` (the default), reading a terminal
+     *   data value (primitive, Buffer, TypedArray, Date, Map, etc.) off a module API path is
+     *   permission-checked, the same way calls are. Set `false` to opt out and gate calls only.
+     * @param {Array<object>} [permissions.rules=[]] - Initial permission rules.
+     * @returns {object|null} Normalized permissions config, or null when permissions is absent or not an object.
+     *
+     * @example
+     * normalizePermissions({ defaultPolicy: "deny", rules: [{ caller: "**", target: "admin.**", effect: "deny" }] });
+     * // => { defaultPolicy: "deny", enabled: true, audit: "default", readGating: true, rules: [...] }
+     */
+    normalizePermissions(permissions?: object | null): object | null;
 }
-export function normalizeHookConfig(hook: any): {
-    enabled: boolean;
-    pattern: string;
-    suppressErrors: boolean;
-    pin: boolean;
-};
 import { ComponentBase } from "#factories/component-base";

package/lib/helpers/defaults.d.mts

@@ -1 +1,40 @@
+/**
+ * The default `apiDepth` (directory-traversal depth) applied when a caller does not specify one.
+ * Unbounded by default. The config normalizer ({@link module:@cldmv/slothlet/helpers/config}) is
+ * what every real compose path reads — it resolves `config.apiDepth` once and the mode processors
+ * receive that already-normalized value. The mode processors' and the loader's own parameter
+ * defaults exist only for the case where they are invoked directly, bypassing normalization (a
+ * standalone call, a future direct consumer); they read this same constant so that case can never
+ * silently disagree with the normalized default.
+ * @type {number}
+ */
 export const DEFAULT_API_DEPTH: number;
+/**
+ * The built-in `routines` list applied when a caller omits the `routines` config option entirely.
+ * Each entry is `{ name, mode }` (bare mount-relative names, non-recursive, mode-defaulted `order`)
+ * — see `docs/LIFECYCLE.md` ("Routines") for the full contract, including the `recursive`/`order`/
+ * `destroy`-mode fields a caller-supplied entry may also set. Passing `routines` at all REPLACES
+ * this list (it is the off-switch); a consumer that wants to extend rather than replace it spreads
+ * this array: `slothlet.defaults.routines`.
+ *
+ * Frozen at every level (the array, and each entry object) so a consumer's spread copies the
+ * entries by reference safely without risking a mutation here leaking across consumers.
+ * @type {ReadonlyArray<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy"}>}
+ */
+export const DEFAULT_ROUTINES: ReadonlyArray<{
+    name: string;
+    mode: "manual" | "startup" | "shutdown" | "destroy";
+}>;
+/**
+ * The complete set of framework-reserved export names — names a module export can never
+ * meaningfully claim because the framework's own wrapper machinery already owns them.
+ *
+ * Derived as the union of {@link ComponentBase.INTERNAL_KEYS} (wrapper state/control properties)
+ * and `IMPL_METADATA_KEYS` (child-adoption metadata) — the same two Sets `isFrameworkReservedKey()`
+ * (`#handlers/unified-wrapper`) checks against, combined here into one Set for convenient
+ * introspection. Wrapped via {@link freezeSet} — `Object.freeze()` alone would leave `add`/
+ * `delete`/`clear` callable, letting a consumer mutate this shared singleton (and corrupt what
+ * every other consumer in the same process sees) despite it claiming to be frozen.
+ * @type {ReadonlySet<string>}
+ */
+export const RESERVED_EXPORTS: ReadonlySet<string>;

package/lib/helpers/eventemitter-context.d.mts

@@ -1,4 +1,30 @@
-export function cleanupEventEmitterResources(): void;
-export function disableEventEmitterPatching(): void;
+/**
+ * Set the context checker callback
+ * Called by the runtime to register a way to detect API context
+ * @param {Function} checker - Function that returns true if in API context
+ * @public
+ */
+export function setApiContextChecker(checker: Function): void;
+/**
+ * Enable EventEmitter context propagation by patching EventEmitter.prototype.
+ * This should be called ONCE globally when the first slothlet instance is created.
+ * Subsequent calls will be ignored (patching is global).
+ *
+ * @public
+ */
 export function enableEventEmitterPatching(): void;
-export function setApiContextChecker(checker: any): void;
+/**
+ * Disable EventEmitter context propagation and restore original methods.
+ * This should only be called when ALL slothlet instances have been shut down.
+ *
+ * @public
+ */
+export function disableEventEmitterPatching(): void;
+/**
+ * Cleanup all tracked EventEmitters created within slothlet API context.
+ * This removes all listeners from tracked emitters and clears tracking structures.
+ * Should be called during shutdown to prevent memory leaks and hanging processes.
+ *
+ * @public
+ */
+export function cleanupEventEmitterResources(): void;

package/lib/helpers/eventtarget-context.d.mts

@@ -1,2 +1,20 @@
-export function disableEventTargetPatching(): void;
+/**
+ * Enable context propagation through `EventTarget` listeners.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how
+ * EventEmitter patching behaves.
+ *
+ * @returns {void}
+ * @public
+ */
 export function enableEventTargetPatching(): void;
+/**
+ * Restore the original `EventTarget` methods.
+ *
+ * Restores a method only when the patch installed here is still in place, so anything that replaced
+ * it afterwards keeps ownership of its own restore.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableEventTargetPatching(): void;

package/lib/helpers/eventtarget-property-context.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Pin `on*` handler assignments to the module that makes them.
+ *
+ * Called once globally when the first instance is created; later calls are ignored, matching how the
+ * other boundary patches behave. Costs nothing when no runtime registered a pinning strategy — the
+ * wrapper hands the callback straight through.
+ *
+ * @returns {void}
+ * @public
+ */
+export function enableEventTargetPropertyPatching(): void;
+/**
+ * Restore the original `on*` handler accessors.
+ *
+ * Restores an accessor only when the patch installed here is still in place, so anything that replaced
+ * it afterwards keeps ownership of its own restore.
+ *
+ * @returns {void}
+ * @public
+ */
+export function disableEventTargetPropertyPatching(): void;