@cldmv/slothlet 2.11.0 → 3.0.1

package/types/dist/slothlet.d.mts

@@ -1,152 +1,225 @@
 /**
- * Live-binding reference to the current API instance.
- * This is updated whenever a new API instance is created.
- * Dynamically imported modules can access this at runtime.
- * @type {object}
- * @private
- * @internal
- */
-export const self: object;
-/**
- * Live-binding reference for contextual data.
- * @type {object}
- * @private
- * @internal
+ * Create a new Slothlet instance and load an API from a directory.
+ * This is the sole public entry point for slothlet. Each call produces an independent
+ * API instance with its own component graph, context store, and lifecycle.
+ * @alias module:@cldmv/slothlet
+ * @async
+ * @param {SlothletOptions} config - Configuration options
+ * @returns {Promise<SlothletAPI>} Fully loaded, proxy-based API object
+ * @public
+ * @example
+ * // Minimal usage
+ * const api = await slothlet({ dir: "./api" });
+ * const result = await api.math.add(2, 3);
+ * await api.slothlet.shutdown();
+ *
+ * @example
+ * // Lazy mode with background materialization
+ * const api = await slothlet({
+ *   dir: "./api",
+ *   mode: "lazy",
+ *   backgroundMaterialize: true
+ * });
+ *
+ * @example
+ * // With hooks
+ * const api = await slothlet({ dir: "./api", hook: true });
+ * api.slothlet.hook.on("before", "**", (endpoint, args) => { /* ... *\/ });
+ *
+ * @example
+ * // Hot-reload a module at runtime
+ * await api.slothlet.api.reload("./api/math.mjs");
+ *
+ * @example
+ * // Strict collision control
+ * const api = await slothlet({
+ *   dir: "./api",
+ *   api: { collision: { initial: "merge", api: "error" } }
+ * });
  */
-export const context: object;
+export function slothlet(config: SlothletOptions): Promise<SlothletAPI>;
+export default slothlet;
 /**
- * Live-binding reference for reference data.
- * @type {object}
- * @private
- * @internal
+ * Configuration options passed to `slothlet()`.
  */
-export const reference: object;
-export default slothlet;
 export type SlothletOptions = {
     /**
-     * - Directory to load API modules from.
-     * - Can be absolute or relative path.
-     * - If relative, resolved from the calling file's location.
-     * - Defaults to "api" directory relative to caller.
+     * - Directory to scan for API modules. Relative paths are resolved from the calling file.
      */
-    dir?: string;
+    dir: string;
     /**
-     * - Loading strategy (legacy option):
-     * - `true`: Lazy loading - modules loaded on-demand when accessed (lower initial load, proxy overhead)
-     * - `false`: Eager loading - all modules loaded immediately (default, higher initial load, direct access)
+     * - Loading strategy.
+     * - `"eager"` — all modules are loaded immediately at startup (default).
+     * - `"lazy"` — modules are loaded on first access via a Proxy.
+     * Also accepted: `"immediate"` / `"preload"` (eager aliases); `"deferred"` / `"proxy"` (lazy aliases).
      */
-    lazy?: boolean;
+    mode?: "eager" | "lazy";
     /**
-     * - Loading mode (alternative to lazy option):
-     * - `"lazy"`: Lazy loading - modules loaded on-demand when accessed (same as lazy: true)
-     * - `"eager"`: Eager loading - all modules loaded immediately (same as lazy: false)
-     * - `"singleton"`, `"vm"`, `"worker"`, `"fork"`: Execution engine mode (legacy, use engine option instead)
-     * - Takes precedence over lazy option when both are provided
+     * - Context propagation runtime.
+     * - `"async"` — AsyncLocalStorage (Node.js built-in, recommended for production).
+     * - `"live"` — Experimental live bindings.
+     * Also accepted: `"asynclocalstorage"` / `"als"` / `"node"` as aliases for `"async"`.
      */
-    mode?: string;
+    runtime?: "async" | "live";
     /**
-     * - Execution environment mode:
-     * - `"singleton"`: Single shared instance within current process (default, fastest)
-     * - `"vm"`: Isolated VM context for security/isolation
-     * - `"worker"`: Web Worker or Worker Thread execution
-     * - `"fork"`: Child process execution for complete isolation
+     * - Directory traversal depth. `Infinity` scans all subdirectories (default). `0` scans only the root.
      */
-    engine?: string;
+    apiDepth?: number;
     /**
-     * - Runtime binding system:
-     * - `"async"` or `"asynclocalstorage"`: Use AsyncLocalStorage for context isolation (default, recommended)
-     * - `"live"` or `"livebindings"`: Use live binding system for dynamic context updates
-     * - Controls how `self`, `context`, and `reference` bindings are managed across function calls
+     * - Object merged into the per-request context accessible inside API functions via `import { context } from "@cldmv/slothlet/runtime"`.
      */
-    runtime?: string;
+    context?: object | null;
     /**
-     * - Directory traversal depth control:
-     * - `Infinity`: Traverse all subdirectories recursively (default)
-     * - `0`: Only load files in root directory, no subdirectories
-     * - `1`, `2`, etc.: Limit traversal to specified depth levels
+     * - Object whose properties are merged directly onto the root API and also available as `api.slothlet.reference`.
      */
-    apiDepth?: number;
+    reference?: object | null;
     /**
-     * - Debug output control:
-     * - `true`: Enable verbose logging for module loading, API construction, and binding operations
-     * - `false`: Silent operation (default)
-     * - Can be set via command line flag `--slothletdebug`, environment variable `SLOTHLET_DEBUG=true`, or options parameter
-     * - Command line and environment settings become the default for all instances unless overridden
+     * - Controls how per-request scope data is merged. `"shallow"` merges top-level keys; `"deep"` recurses into nested objects.
      */
-    debug?: boolean;
+    scope?: {
+        merge: "shallow" | "deep";
+    };
     /**
-     * - API structure and calling convention:
-     * - `"auto"`: Auto-detect based on root module exports (function vs object) - recommended (default)
-     * - `"function"`: Force API to be callable as function with properties attached
-     * - `"object"`: Force API to be plain object with method properties
+     * - API build and mutation settings.
      */
-    api_mode?: string;
+    api?: {
+        collision?: string | {
+            initial: string;
+            api: string;
+        };
+        mutations?: object;
+    };
     /**
-     * - Controls whether addApi can overwrite existing API endpoints:
-     * - `true`: Allow overwrites (default, backwards compatible)
-     * - `false`: Prevent overwrites, log warning and skip when attempting to overwrite existing endpoints
-     * - Applies to both function and object overwrites at the final key of the API path
+     * - Hook system configuration.
+     * - `false` — disabled (default).
+     * - `true` — enabled, all endpoints.
+     * - `string` — enabled with a default glob pattern.
+     * - `object` — full control: `{ enabled: boolean, pattern?: string, suppressErrors?: boolean }`.
      */
-    allowApiOverwrite?: boolean;
+    hook?: boolean | string | object;
     /**
-     * - Enable module-based API ownership tracking for selective overwrites:
-     * - `true`: Track which modules register APIs, enable forceOverwrite with moduleId validation
-     * - `false`: Disable ownership tracking (default, no performance overhead)
-     * - When enabled, supports hot-reloading scenarios where modules can selectively overwrite only their own APIs
-     * - Requires moduleId parameter in addApi options when using forceOverwrite capability
+     * - Enable verbose internal logging. `true` enables all categories.
+     * Pass an object with sub-keys `builder`, `api`, `index`, `modes`, `wrapper`, `ownership`, `context` to target specific subsystems.
      */
-    enableModuleOwnership?: boolean;
+    debug?: boolean | object;
     /**
-     * - Context data object injected into live-binding `context` reference.
-     * - Available to all loaded modules via `import { context } from "@cldmv/slothlet/runtime"`. Useful for request data,
-     * - user sessions, environment configs, etc.
+     * - Suppress all console output from slothlet (warnings, deprecations). Does not affect `debug`.
      */
-    context?: object;
+    silent?: boolean;
     /**
-     * - Reference object merged into the API root level.
-     * - Properties not conflicting with loaded modules are added directly to the API.
-     * - Useful for utility functions, constants, or external service connections.
+     * - Enable the `api.slothlet.diag.*` introspection namespace. Intended for testing; do not enable in production.
      */
-    reference?: object;
+    diagnostics?: boolean;
     /**
-     * - Filename sanitization options for API property names.
-     * - Controls how file names are converted to valid JavaScript identifiers.
-     * - Default behavior: camelCase conversion with lowerFirst=true.
+     * - Enable internal tracking. Pass `true` or `{ materialization: true }` to track lazy-mode materialization progress.
      */
-    sanitize?: {
-        lowerFirst?: boolean;
-        preserveAllUpper?: boolean;
-        preserveAllLower?: boolean;
-        rules?: {
-            leave?: string[];
-            leaveInsensitive?: string[];
-            upper?: string[];
-            lower?: string[];
-        };
-    };
-};
-export type SlothletAPI = {
+    tracking?: boolean | object;
     /**
-     * - Shuts down the API instance and cleans up all resources
+     * - When `mode: "lazy"`, immediately begins materializing all paths in the background after init.
      */
-    shutdown: () => Promise<void>;
+    backgroundMaterialize?: boolean;
     /**
-     * - Dynamically adds API modules from a folder to a specified API path
+     * - Internationalization settings (dev-facing, process-global).
+     * `{ language: string }` — selects the locale for framework messages (e.g. `"en-us"`, `"fr-fr"`, `"ja-jp"`).
      */
-    addApi: (apiPath: string, folderPath: string) => Promise<void>;
+    i18n?: object;
     /**
-     * - Returns metadata about the current API instance configuration. In lazy mode with showAll=false, returns an array of property keys. In lazy mode with showAll=true, returns a Promise resolving to an object. In eager mode, returns a plain object.
+     * - TypeScript support.
+     * - `false` — disabled (default).
+     * - `true` or `"fast"` — esbuild transpilation, no type checking.
+     * - `"strict"` — tsc compilation with type checking and `.d.ts` generation.
+     * See [TYPESCRIPT.md](docs/TYPESCRIPT.md) for the full configuration reference.
      */
-    describe: (showAll?: boolean) => ((string | symbol)[] | object | Promise<object>);
+    typescript?: boolean | "fast" | "strict" | object;
 };
 /**
- * Creates a slothlet API instance with the specified configuration.
- * This is the main entry point that can be called directly as a function.
- * @async
- * @alias module:@cldmv/slothlet
- * @param {SlothletOptions} [options={}] - Configuration options for creating the API
- * @returns {Promise<SlothletAPI>} The bound API object or function with management methods
- * @public
+ * Bound API object returned by `slothlet()`.
+ * The root contains all loaded module exports plus the reserved `slothlet` namespace.
  */
-export function slothlet(options?: SlothletOptions): Promise<SlothletAPI>;
+export type SlothletAPI = {
+    /**
+     * - Like `shutdown()` but additionally invokes registered destroy hooks before teardown. %%sig: (): void%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ dir: './api' });|await api.destroy();%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ dir: './api' });|  await api.destroy();|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ dir: './api' });|  await api.destroy();|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ dir: './api' });|await api.destroy();%%
+     */
+    destroy: () => void;
+    /**
+     * - Convenience alias for `slothlet.shutdown()`. Shuts down the instance and invokes any user-provided shutdown hook first. %%sig: (): void%% %%example: // ESM usage via slothlet API|import slothlet from "@cldmv/slothlet";|const api = await slothlet({ dir: './api' });|await api.shutdown();%% %%example: // ESM usage via slothlet API (inside async function)|async function example() {|  const { default: slothlet } = await import("@cldmv/slothlet");|  const api = await slothlet({ dir: './api' });|  await api.shutdown();|}%% %%example: // CJS usage via slothlet API (top-level)|let slothlet;|(async () => {|  ({ slothlet } = await import("@cldmv/slothlet"));|  const api = await slothlet({ dir: './api' });|  await api.shutdown();|})();%% %%example: // CJS usage via slothlet API (inside async function)|const slothlet = require("@cldmv/slothlet");|const api = await slothlet({ dir: './api' });|await api.shutdown();%%
+     */
+    shutdown: () => void;
+    /**
+     * - Built-in control namespace. All framework internals live here to avoid collisions with loaded modules.
+     */
+    slothlet: {
+        api: {
+            add: Function;
+            reload: Function;
+            remove: Function;
+        };
+        context: {
+            get: Function;
+            inspect: () => any;
+            run: Function;
+            scope: Function;
+            set: Function;
+        };
+        diag?: {
+            caches?: {
+                get?: () => any;
+                getAllModuleIDs?: () => string[];
+                has?: Function;
+            };
+            context?: object;
+            describe?: Function;
+            getAPI?: () => any;
+            getOwnership?: () => any;
+            hook?: object;
+            inspect?: () => any;
+            owner?: {
+                get?: Function;
+            };
+            reference?: object;
+            SlothletWarning?: () => SlothletWarning;
+        };
+        hook: {
+            clear: Function;
+            disable: Function;
+            enable: Function;
+            list: Function;
+            off: Function;
+            on: Function;
+            remove: Function;
+        };
+        lifecycle: {
+            off: Function;
+            on: Function;
+        };
+        materialize: {
+            get: () => any;
+            materialized: boolean;
+            wait: () => Promise<void>;
+        };
+        metadata: {
+            caller: () => any | null;
+            get: Function;
+            remove: Function;
+            removeFor: Function;
+            self: () => any | null;
+            set: Function;
+            setFor: Function;
+            setGlobal: Function;
+        };
+        owner: {
+            get: Function;
+        };
+        ownership: {
+            get: Function;
+            unregister: Function;
+        };
+        reference?: object;
+        reload: Function;
+        run: Function;
+        scope: Function;
+        shutdown: () => Promise<void>;
+    };
+};
+import { SlothletWarning } from "@cldmv/slothlet/errors";
 //# sourceMappingURL=slothlet.d.mts.map

package/types/dist/slothlet.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AA+LA;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAqtCd,MAAM;;;;;;WAIN,OAAO;;;;;;;;WAGP,MAAM;;;;;;;;aAKN,MAAM;;;;;;;cAKN,MAAM;;;;;;;eAIN,MAAM;;;;;;;;YAIN,OAAO;;;;;;;eAKP,MAAM;;;;;;;wBAIN,OAAO;;;;;;;;4BAIP,OAAO;;;;;;cAKP,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACY,gBAAgB,GAAnC,OAAO;QACW,KAAK,GAClC;YAAqC,KAAK,GAA/B,MAAM,EAAE;YACkB,gBAAgB,GAA1C,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;YACkB,KAAK,GAA/B,MAAM,EAAE;SACrB;KAAA;;;;;;cAIa,MAAM,OAAO,CAAC,IAAI,CAAC;;;;YACnB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;;;;cACtD,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,MAAM,GAAC,MAAM,CAAC,EAAE,GAAC,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAAC;;AArxC/E;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAiChC"}
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AAk2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iCAjCW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAsChC;;;;;;;;;SAWa,MAAM;;;;;;;WACN,OAAO,GAAC,MAAM;;;;;;;cAId,OAAO,GAAC,MAAM;;;;eAId,MAAM;;;;cACN,MAAM,GAAC,IAAI;;;;gBACX,MAAM,GAAC,IAAI;;;;YACX;QAAC,KAAK,EAAE,SAAS,GAAC,MAAM,CAAA;KAAC;;;;UAEpC;QAAuD,SAAS,GAArD,MAAM,GAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAC;QAGxB,SAAS,GAAtB,MAAM;KAEjB;;;;;;;;WAAW,OAAO,GAAC,MAAM,GAAC,MAAM;;;;;YAKrB,OAAO,GAAC,MAAM;;;;aAEd,OAAO;;;;kBACP,OAAO;;;;eACP,OAAO,GAAC,MAAM;;;;4BACd,OAAO;;;;;WACP,MAAM;;;;;;;;iBAEN,OAAO,GAAC,MAAM,GAAC,QAAQ,GAAC,MAAM;;;;;;;;;;aAW9B,MAAY,IAAI;;;;cAChB,MAAY,IAAI;;;;cAE3B;QAA4B,GAAG,EAC/B;YAAkC,GAAG;YACH,MAAM;YACN,MAAM;SACxC;QAA4B,OAAO,EACnC;YAAsC,GAAG;YACO,OAAO,EAA5C,SAAkB;YACS,GAAG;YACH,KAAK;YACL,GAAG;SACzC;QAA6B,IAAI,GACjC;YAAkC,MAAM,GACxC;gBAAqD,GAAG,GAA7C,SAAkB;gBAC0B,eAAe,GAA3D,MAAY,MAAM,EAAE;gBACY,GAAG;aAC9C;YAAkC,OAAO,GAA9B,MAAM;YACmB,QAAQ;YACE,MAAM,GAAzC,SAAkB;YACiB,YAAY,GAA/C,SAAkB;YACK,IAAI,GAA3B,MAAM;YAC6B,OAAO,GAA1C,SAAkB;YACK,KAAK,GACvC;gBAA0C,GAAG;aAC7C;YAAkC,SAAS,GAAhC,MAAM;YACsC,eAAe,GAA3D,MAAY,eAAe;SACtC;QAA4B,IAAI,EAChC;YAAmC,KAAK;YACL,OAAO;YACP,MAAM;YACN,IAAI;YACJ,GAAG;YACH,EAAE;YACF,MAAM;SACzC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,EAAE;SAC1C;QAA4B,WAAW,EACvC;YAAoD,GAAG,EAA5C,SAAkB;YACY,YAAY,EAA1C,OAAO;YAC0C,IAAI,EAArD,MAAY,OAAO,CAAE,IAAI,CAAC;SACrC;QAA4B,QAAQ,EACpC;YAAsD,MAAM,EAAjD,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;YACM,IAAI,EAA/C,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;SAChD;QAA4B,KAAK,EACjC;YAAoC,GAAG;SACvC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,UAAU;SAClD;QAA6B,SAAS,GAA3B,MAAM;QACa,MAAM;QACN,GAAG;QACH,KAAK;QACa,QAAQ,EAA7C,MAAY,OAAO,CAAE,IAAI,CAAC;KACvC;;gCA56B6D,wBAAwB"}

package/types/index.d.mts

@@ -11,9 +11,7 @@ export type * from "./dist/slothlet.d.mts";
 export * from "./dist/slothlet.mts";
 
 // Auto-generated named export declarations (these override the re-export above)
-export const context: any;
-export const reference: any;
-export const self: any;
+export const async: any;
 
 // Main slothlet export
 declare const slothlet: any;

package/dist/lib/engine/README.md

@@ -1,21 +0,0 @@
-# src/lib Experimental Code
-
-This folder contains experimental modules for the slothlet API loader. The code here is either not working, partially working, or not fully tested. Use at your own risk.
-
-## Purpose
-
-The files in this folder are prototypes and work-in-progress implementations for advanced features in slothlet, such as:
-
-- **slothlet_child.mjs**: Experiments with child process or worker-based API loading and isolation.
-- **slothlet_engine.mjs**: Attempts to provide a modular engine for API loading, context binding, and shutdown management.
-- **slothlet_esm.mjs**: Explores ES module dynamic loading and compatibility.
-- **slothlet_helpers.mjs**: Utility functions for API flattening, key conversion, and module handling.
-- **slothlet_worker.mjs**: Prototypes for worker thread-based API execution and communication.
-
-## Status
-
-These modules are not guaranteed to work and may be incomplete, buggy, or subject to breaking changes. They are intended for experimentation and future development, not for production use.
-
-## Contribution
-
-If you wish to contribute, please review the code and leave comments or suggestions. Any improvements or bug fixes are welcome, but stability is not guaranteed.

package/dist/lib/engine/slothlet_child.mjs

@@ -1,59 +0,0 @@
-/*
-	Copyright 2026 CLDMV/Shinrai
-
-	Licensed under the Apache License, Version 2.0 (the "License");
-	you may not use this file except in compliance with the License.
-	You may obtain a copy of the License at
-
-		http://www.apache.org/licenses/LICENSE-2.0
-
-	Unless required by applicable law or agreed to in writing, software
-	distributed under the License is distributed on an "AS IS" BASIS,
-	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-	See the License for the specific language governing permissions and
-	limitations under the License.
-*/
-
-
-
-import { installGlobalsInCurrentRealm, extendSelfWithReference, installPortalForSelf } from "./slothlet_helpers.mjs";
-
-let initialized = false;
-
-process.on("message", async (msg) => {
-	try {
-		if (msg.t === "init") {
-			if (initialized) return;
-			initialized = true;
-
-			const { entry, loadConfig, contextMap, reference } = msg;
-
-			
-			installGlobalsInCurrentRealm(contextMap);
-
-			
-			const { slothlet } = await import(entry);
-			if (!slothlet) throw new Error("Entry did not export `slothlet`");
-
-			const api = await slothlet.load(loadConfig, { context: contextMap, reference });
-			globalThis.self = api;
-
-			
-			extendSelfWithReference(globalThis.self, reference);
-			installPortalForSelf();
-
-			process.send({ id: msg.id, ok: 1, result: true });
-		} else if (msg.t === "call") {
-			const result = await globalThis._portal.call(msg.path, msg.args || []);
-			process.send({ id: msg.id, ok: 1, result });
-		} else if (msg.t === "batch") {
-			const result = await globalThis._portal.batch(msg.ops || []);
-			process.send({ id: msg.id, ok: 1, result });
-		} else if (msg.t === "dispose") {
-			process.send({ id: msg.id, ok: 1, result: true });
-			process.exit(0);
-		}
-	} catch (e) {
-		process.send({ id: msg.id, ok: 0, error: String(e?.stack || e) });
-	}
-});