@cldmv/slothlet 3.15.2 → 3.16.0

package/types/stub/lib/builders/builder.d.mts

@@ -1,3 +1,88 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/builders/builder";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * API builder class for orchestrating mode-based API construction.
+ * @class Builder
+ * @extends ComponentBase
+ * @package
+ *
+ * @description
+ * Orchestrates API building by delegating to mode-specific builders (eager/lazy).
+ * Extends ComponentBase for access to Slothlet configuration and error classes.
+ *
+ * @example
+ * const builder = new Builder(slothlet);
+ * const api = await builder.buildAPI({ dir: "./api" });
+ */
+export class Builder extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Create Builder instance.
+     * @param {object} slothlet - Slothlet orchestrator instance.
+     * @package
+     *
+     * @description
+     * Stores Slothlet reference for accessing configuration and components.
+     *
+     * @example
+     * const builder = new Builder(slothlet);
+     */
+    constructor(slothlet: object);
+    /**
+     * Build API from directory or file.
+     * @param {Object} options - Build options
+     * @param {string} [options.dir] - Directory or file to build from. Required unless `syntheticExports` is set (synthetic / in-memory leaf, #117).
+     * @param {string} [options.mode="eager"] - Loading mode (eager or lazy)
+     * @param {Object} [options.ownership] - Ownership manager (uses slothlet's if not provided)
+     * @param {Object} [options.contextManager] - Context manager (uses slothlet's if not provided)
+     * @param {string} [options.instanceID] - Instance ID (uses slothlet's if not provided)
+     * @param {Object} [options.config] - Configuration (uses slothlet's if not provided)
+     * @param {string} [options.apiPathPrefix=""] - Prefix for API paths (for api.add support)
+     * @param {string} [options.collisionContext="initial"] - Collision context
+     * @param {string} [options.moduleID] - Stable module identifier (cache key; enables later reload/remove)
+     * @param {string|null} [options.cacheBust=null] - Cache-busting value forwarded to the loader/mode
+     * @param {string|null} [options.collisionMode=null] - Per-call collision mode override (lazy builds)
+     * @param {Function|null} [options.fileFilter=null] - Optional filter function (fileName) => boolean to load specific files only
+     * @param {Object|null} [options.syntheticExports=null] - Inline `{ default?, ...named }` exports to build
+     *   from instead of scanning `dir` (synthetic / in-memory leaf, #117). When set, `dir` is not required.
+     * @param {string} [options.syntheticName="synthetic"] - Intermediate key name for the synthetic build.
+     * @param {boolean} [options.rootUnwrap=false] - The mount exposes the single root entry's exports
+     *   directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api
+     *   level and must contribute no path segment either.
+     * @returns {Promise<Object>} Raw API object (unwrapped)
+     * @public
+     *
+     * @description
+     * Validates inputs and delegates to mode-specific builder (buildEagerAPI or buildLazyAPI).
+     * When fileFilter is provided, only files matching the filter are loaded.
+     *
+     * @example
+     * const api = await builder.buildAPI({ dir: "./api_tests/api_test", mode: "eager" });
+     *
+     * @example
+     * // Load specific file only
+     * const api = await builder.buildAPI({
+     *   dir: "./api_tests/api_test",
+     *   mode: "eager",
+     *   fileFilter: (fileName) => fileName === "math.mjs"
+     * });
+     */
+    public buildAPI(options: {
+        dir?: string | undefined;
+        mode?: string | undefined;
+        ownership?: Object | undefined;
+        contextManager?: Object | undefined;
+        instanceID?: string | undefined;
+        config?: Object | undefined;
+        apiPathPrefix?: string | undefined;
+        collisionContext?: string | undefined;
+        moduleID?: string | undefined;
+        cacheBust?: string | null | undefined;
+        collisionMode?: string | null | undefined;
+        fileFilter?: Function | null | undefined;
+        syntheticExports?: Object | null | undefined;
+        syntheticName?: string | undefined;
+        rootUnwrap?: boolean | undefined;
+    }): Promise<Object>;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/builders/modes-processor.d.mts

@@ -1,3 +1,72 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/builders/modes-processor";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * ModesProcessor - Handles mode-specific file and directory processing.
+ *
+ * @class
+ * @extends ComponentBase
+ * @package
+ */
+export class ModesProcessor extends ComponentBase {
+    static slothletProperty: string;
+    /**
+     * Creates a new ModesProcessor instance.
+     *
+     * @param {Object} slothlet - Parent slothlet instance
+     */
+    constructor(slothlet: Object);
+    /**
+     * Recursively walk a directory's scanned files/subdirectories and compose them onto `api`.
+     * @param {Object} api - Root api object being built.
+     * @param {Array<Object>} files - This directory's own files (from the loader's scan structure).
+     * @param {{name: string, path?: string, children: {files: Array, directories: Array}}} directory - This directory's own scan node.
+     * @param {number} currentDepth - Recursion depth, for `apiDepth` enforcement.
+     * @param {string} mode - `"eager"` or `"lazy"`.
+     * @param {boolean} isRoot - Whether this call is the top-level (mount root) invocation.
+     * @param {boolean} recursive - Whether to descend into subdirectories at all.
+     * @param {boolean} [populateDirectly=false] - Pour this directory's contents directly into `api` (no nested namespace level) — used for transparent-folder and lazy-materialization callers.
+     * @param {string} [apiPathPrefix=""] - Dotted api path prefix this directory's own entries are built under.
+     * @param {string} [collisionContext="initial"] - `"initial"` or `"api"` — which `config.collision` policy governs this build.
+     * @param {string|null} [moduleID=null] - Module id every leaf produced by this call is attributed to.
+     * @param {string|null} [sourceFolder=null] - Filesystem path this directory was scanned from, for metadata.
+     * @param {string|null} [cacheBust=null] - Cache-busting value forwarded to dynamic imports.
+     * @param {string|null} [collisionModeOverride=null] - Per-call override (e.g. `api.add()`'s `forceOverwrite`) that takes precedence over `collisionContext`'s config default for every leaf this call (and its own recursive calls) produces.
+     * @param {boolean} [rootUnwrap=false] - The mount exposes its single root entry's exports directly at the mount path (a single-file or synthetic `api.add()`), so that entry creates no api level.
+     * @returns {Promise<Function|null>} The root-level default-export contributor function, if one was found at this call's own top level; otherwise `null`.
+     * @package
+     */
+    processFiles(api: Object, files: Array<Object>, directory: {
+        name: string;
+        path?: string;
+        children: {
+            files: any[];
+            directories: any[];
+        };
+    }, currentDepth: number, mode: string, isRoot: boolean, recursive: boolean, populateDirectly?: boolean, apiPathPrefix?: string, collisionContext?: string, moduleID?: string | null, sourceFolder?: string | null, cacheBust?: string | null, collisionModeOverride?: string | null, rootUnwrap?: boolean): Promise<Function | null>;
+    /**
+     * Create lazy wrapper for subdirectory (lazy mode only)
+     * @param {Object} dir - Directory structure to materialize on first access.
+     * @param {string} apiPath - Current (already composed) API path for this subdirectory.
+     * @param {string} [moduleID] - Owning module id, threaded into the loader and ownership registration.
+     * @param {string} [sourceFolder] - Parent's source folder path; this subdirectory's own source folder is derived from it.
+     * @param {*} [cacheBust] - Cache-busting token passed through to `loadModule`.
+     * @param {Object} [fileFolderCollisionImpl] - Pre-existing implementation properties from a file/folder name collision, merged onto the materialized result so they survive lazy materialization.
+     * @param {string} [collisionMode] - Effective (override-or-config-resolved) collision mode to apply within this subdirectory.
+     * @param {string} [collisionContext] - Collision context ("initial" | "api") this subdirectory was mounted under, threaded to ownership/ collision-detection calls.
+     * @returns {Proxy} Lazy unified wrapper
+     * @public
+     */
+    public createLazySubdirectoryWrapper(dir: Object, apiPath: string, moduleID?: string, sourceFolder?: string, cacheBust?: any, fileFolderCollisionImpl?: Object, collisionMode?: string, collisionContext?: string): ProxyConstructor;
+    /**
+     * Apply root contributor pattern - merge API into root function
+     * @param {Object} api - API object with properties
+     * @param {Function|null} rootFunction - Root contributor function
+     * @param {Object} config - Configuration
+     * @param {string} mode - Mode name for debug messages
+     * @returns {Promise<Object|Function>} Final API (function if root contributor, object otherwise)
+     * @public
+     */
+    public applyRootContributor(api: Object, rootFunction: Function | null, mode: string): Promise<Object | Function>;
+    #private;
+}
+import { ComponentBase } from "#factories/component-base";

package/types/stub/lib/factories/component-base.d.mts

@@ -0,0 +1,177 @@
+// AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Base class for Slothlet component classes.
+ * @class ComponentBase
+ * @package
+ *
+ * @description
+ * Provides common Slothlet property access for handlers, builders, and processors.
+ * All component classes should extend this to gain consistent access to the Slothlet
+ * instance's configuration, API references, and error classes. Components are instantiated
+ * with a reference to the Slothlet class itself, making them modular extensions.
+ *
+ * @example
+ * class ApiManager extends ComponentBase {
+ *   constructor(slothlet) {
+ *     super(slothlet);
+ *     this.state = { addHistory: [] };
+ *   }
+ *
+ *   someMethod() {
+ *     if (this.debug?.api) {
+ *       console.log(`Slothlet: ${this.instanceID}`);
+ *     }
+ *     throw new this.SlothletError("INVALID_CONFIG", { reason: "bad input" });
+ *   }
+ * }
+ */
+export class ComponentBase {
+    /**
+     * Complete set of property names reserved by the slothlet framework.
+     *
+     * @description
+     * These keys are either private wrapper internals, read-only info props exposed
+     * through the proxy, write-blocked lifecycle keys, or builtin namespace keys
+     * injected at the API root level. Used by all components to distinguish framework
+     * internals from user-defined properties when:
+     *   - Collecting user-set custom properties for preservation across reload
+     *     (`_collectCustomProperties` in api-manager.mjs)
+     *   - Extracting child keys for impl reconstruction (`_extractFullImpl`)
+     *   - Determining whether a set(trap) write should be silently absorbed (`setTrap`)
+     *   - Filtering what getTrap exposes externally on wrapper proxies
+     *
+     * Note: `_materialize` is included here (skip for collection/extraction) but
+     * setTrap exempts it since the framework needs to write it directly.
+     *
+     * @type {Set<string>}
+     * @static
+     */
+    static INTERNAL_KEYS: Set<string>;
+    /**
+     * Create a component base instance.
+     * @param {object} slothlet - Slothlet class instance.
+     * @package
+     *
+     * @description
+     * Stores the Slothlet reference for access via getters. The Slothlet class itself
+     * is passed (not a separate "instance" object), making components modular extensions
+     * of Slothlet.
+     *
+     * @example
+     * super(slothlet);
+     */
+    constructor(slothlet: object);
+    /**
+     * Get Slothlet instance via the canonical internal accessor name.
+     * @returns {object} Slothlet instance.
+     * @package
+     *
+     * @description
+     * Prototype getter — NOT an own property — so the JS Proxy invariant for
+     * non-configurable own properties never applies. UnifiedWrapper's getTrap blocks
+     * this name via the underscore-filter before it can reach the getter.
+     *
+     * @example
+     * const s = this.____slothlet;
+     */
+    get ____slothlet(): object;
+    /**
+     * Get Slothlet instance (internal access).
+     * @returns {object} Slothlet instance.
+     * @package
+     *
+     * @description
+     * Provides direct access to the Slothlet instance for legacy code compatibility.
+     * Prefer using specific getters (config, helpers, handlers) when possible.
+     *
+     * @example
+     * this.slothlet.debug("api", { action: "assigned" });
+     */
+    get slothlet(): object;
+    /**
+     * Get Slothlet configuration.
+     * @returns {object} Slothlet configuration object.
+     * @package
+     *
+     * @description
+     * Provides access to the Slothlet config for collision modes, debug settings, etc.
+     * Named with ____ prefix to avoid shadowing user API names like 'config'.
+     *
+     * @example
+     * const collisionMode = this.____config.collision.api;
+     */
+    get ____config(): object;
+    /**
+     * Get Slothlet instance ID.
+     * @returns {string} Slothlet instance identifier.
+     * @package
+     */
+    get instanceID(): string;
+    /**
+     * Get SlothletError class.
+     * @returns {Function} SlothletError constructor.
+     * @package
+     *
+     * @description
+     * Provides access to SlothletError without importing in every file.
+     * Components can throw errors via `new this.SlothletError(...)`.
+     *
+     * @example
+     * throw new this.SlothletError("INVALID_CONFIG", { reason: "missing dir" });
+     */
+    get SlothletError(): Function;
+    /**
+     * Get SlothletWarning class.
+     * @returns {Function} SlothletWarning constructor.
+     * @package
+     *
+     * @description
+     * Provides access to SlothletWarning without importing in every file.
+     * Components can issue warnings via `new this.SlothletWarning(...)`.
+     *
+     * @example
+     * new this.SlothletWarning("WARNING_DEPRECATED", { feature: "oldApi" });
+     */
+    get SlothletWarning(): Function;
+    /**
+     * Emit a non-throwing diagnostic lifecycle event (`impl:warning` or `impl:error`).
+     * @param {"warning"|"error"} level - Diagnostic level → `impl:warning` or `impl:error`.
+     * @param {object} data - Diagnostic payload.
+     * @param {string} data.code - i18n code (e.g. "WARN_SYNTHETIC_ROOT_COLLISION") used to translate `message`.
+     * @param {object} data.context - Structured context object passed to the diagnostic (also the i18n interpolation params).
+     * @param {string} [data.apiPath] - API path where the mutation was attempted ("" / "(root)" for root).
+     * @param {string} [data.source] - Command family that produced the diagnostic (addApi | reload | buildAPI | module-mount).
+     * @param {string} [data.moduleID] - Module identifier, when one is in scope.
+     * @param {Error} [data.error] - The originating Error / SlothletError (impl:error only).
+     * @returns {Promise<void>} Resolves once all subscribers (including async ones) have run.
+     * @package
+     *
+     * @description
+     * Fires an additive lifecycle event for a diagnostic the framework handled WITHOUT throwing —
+     * a warning, or a runtime error a command caught and continued past. Observers registered via
+     * `api.slothlet.lifecycle.on("impl:warning"|"impl:error", fn)` — or the construction-time
+     * `lifecycle` config option — receive these regardless of the `silent` config: `silent`
+     * suppresses console output only, never events. The human-readable `message` is translated
+     * from `code` + `context` here so subscribers get a ready-to-display string even when the
+     * corresponding SlothletWarning/SlothletError was never constructed (e.g. under `silent`).
+     *
+     * Emission stays per-site: each diagnostic location calls this explicitly, mirroring how each
+     * site constructs its own `this.SlothletWarning`. The SlothletError / SlothletWarning classes
+     * remain context-free (no slothlet reference) and are never coupled to the lifecycle emitter.
+     *
+     * @example
+     * await this.emitImplDiagnostic("warning", {
+     *   apiPath: "", code: "WARN_SYNTHETIC_ROOT_EMPTY", context: { apiPath: "(root)" }, source: "addApi"
+     * });
+     */
+    emitImplDiagnostic(level: "warning" | "error", data: {
+        code: string;
+        context: object;
+        apiPath?: string | undefined;
+        source?: string | undefined;
+        moduleID?: string | undefined;
+        error?: Error | undefined;
+    }): Promise<void>;
+    #private;
+}

package/types/stub/lib/helpers/caller-pinning.d.mts

@@ -1,3 +1,23 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/caller-pinning";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * Register the strategy for binding a callback to whoever scheduled it.
+ *
+ * @param {Function|null} strategy - Takes a callback and returns a replacement that re-enters the
+ *   registering module's context when it runs. `null` clears the registration.
+ * @returns {void}
+ * @internal
+ */
+export function setApiCallerPinner(strategy: Function | null): void;
+/**
+ * Bind a callback to the caller active right now, if the runtime supplies a way to.
+ *
+ * Called by each scheduling boundary at registration time. Returns the callback unchanged when no
+ * pinner is registered (the async runtime) or when there is no caller to pin (the host scheduling
+ * its own work), so the boundary pays nothing outside a module call.
+ *
+ * @param {Function} callback - Callback about to be deferred.
+ * @returns {Function} The callback, bound to the current caller where one exists.
+ * @internal
+ */
+export function pinToCurrentCaller(callback: Function): Function;

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

@@ -1,3 +1,59 @@
 // AUTO-GENERATED by tools/build/build-typestubs.mjs — do not edit.
-// Re-exports the real declarations from @cldmv/slothlet-types (install it for TypeScript support).
-export * from "@cldmv/slothlet-types/helpers/class-instance-wrapper";
+// Self-contained copy: this subpath is internal and not published by @cldmv/slothlet-types.
+/**
+ * @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;
+/**
+ * @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;