@cldmv/slothlet 1.0.3 → 2.1.0

package/types/dist/lib/helpers/sanitize.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/sanitize.mjs"],"names":[],"mappings":"AAmEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wCAjEW,MAAM,SAEd;IAAuB,UAAU,GAAzB,OAAO;IACO,KAAK,GAC3B;QAA8B,KAAK,GAA3B,MAAM,EAAE;QACc,gBAAgB,GAAtC,MAAM,EAAE;QACc,KAAK,GAA3B,MAAM,EAAE;QACc,KAAK,GAA3B,MAAM,EAAE;KAChB;CAAA,GAAU,MAAM,CA+QlB"}

package/types/dist/lib/modes/slothlet_eager.d.mts

@@ -0,0 +1,66 @@
+/**
+ * @function eager_wrapWithRunCtx
+ * @internal
+ * @package
+ * @alias module:@cldmv/slothlet.modes.eager.eager_wrapWithRunCtx
+ * @memberof module:@cldmv/slothlet.modes.eager
+ * @param {*} obj - The object/function to wrap
+ * @param {object} instance - The slothlet instance that will have boundapi.__ctx attached
+ * @returns {*} The wrapped object/function
+ *
+ * @description
+ * Recursively wraps all functions in an object with runWithCtx for eager mode.
+ * This makes eager mode use the same call stack optimization as lazy mode.
+ *
+ * @example
+ * // Wrapping a function
+ * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
+ *
+ * @example
+ * // Wrapping an object with nested functions
+ * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
+ *
+ * @example
+ * // Wrapping a function
+ * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
+ *
+ * @example
+ * // Wrapping an object with nested functions
+ * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
+ * const wrappedFn = eager_wrapWithRunCtx(originalFunction, instance);
+ *
+ * @example
+ * // Wrapping an object with nested functions
+ * const wrappedObj = eager_wrapWithRunCtx({ method: fn }, instance);
+ */
+/**
+ * @function create
+ * @internal
+ * @package
+ * @async
+ * @alias module:@cldmv/slothlet.modes.eager.create
+ * @memberof module:@cldmv/slothlet.modes.eager
+ * @param {string} dir - Directory to load
+ * @param {boolean} [rootLevel=true] - Is this the root level?
+ * @param {number} [maxDepth=Infinity] - Maximum depth to traverse
+ * @param {number} [currentDepth=0] - Current traversal depth
+ * @returns {Promise<object>} Complete API object with all modules loaded
+ * @throws {Error} When module loading or directory traversal fails
+ *
+ * @description
+ * Creates the eager API for slothlet (mode: eager).
+ * Immediately loads all modules and constructs the complete API structure.
+ *
+ * @example
+ * // Internal usage - called by slothlet core
+ * const api = await create('./api_test', true, 3, 0);
+ * // Returns: { math: { add: [Function], multiply: [Function] }, ... }
+ *
+ * @example
+ * // Root-level processing with function exports
+ * const api = await create('./api_test', true);
+ * // If root has default function: api becomes that function with properties
+ * // Otherwise: api is object with module properties
+ */
+export function create(dir: string, rootLevel?: boolean, maxDepth?: number, currentDepth?: number): Promise<object>;
+//# sourceMappingURL=slothlet_eager.d.mts.map

package/types/dist/lib/modes/slothlet_eager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet_eager.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_eager.mjs"],"names":[],"mappings":"AA8HA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,4BAtBW,MAAM,cACN,OAAO,aACP,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAqE3B"}

package/types/dist/lib/modes/slothlet_lazy.d.mts

@@ -0,0 +1,32 @@
+/**
+ * @function create
+ * @internal
+ * @package
+ * @async
+ * @alias module:@cldmv/slothlet.modes.lazy.create
+ * @memberof module:@cldmv/slothlet.modes.lazy
+ * @param {string} dir - Root directory
+ * @param {boolean} [rootLevel=true] - Root level flag
+ * @param {number} [maxDepth=Infinity] - Maximum depth to traverse
+ * @param {number} [currentDepth=0] - Current depth (for internal recursion only)
+ * @returns {Promise<function|object>} Root API object or function (if default export)
+ * @throws {Error} When module loading or directory traversal fails
+ *
+ * @description
+ * Creates a lazy API structure. Root-level files are loaded immediately (mirrors eager).
+ * Directories become lazy proxies. Nested directories remain lazy after materialization
+ * via _buildCategory recursion with subdirHandler.
+ *
+ * @example
+ * // Internal usage - called by slothlet core
+ * const api = await create('./api_test', true, 3, 0);
+ * // Returns: { math: [Function: lazyFolder_math], ... } (lazy proxies)
+ *
+ * @example
+ * // Root-level processing with function exports
+ * const api = await create('./api_test', true);
+ * // If root has default function: api becomes that function with properties
+ * // Otherwise: api is object with lazy proxy properties
+ */
+export function create(dir: string, rootLevel?: boolean, maxDepth?: number, currentDepth?: number): Promise<Function | object>;
+//# sourceMappingURL=slothlet_lazy.d.mts.map

package/types/dist/lib/modes/slothlet_lazy.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet_lazy.d.mts","sourceRoot":"","sources":["../../../../dist/lib/modes/slothlet_lazy.mjs"],"names":[],"mappings":"AAgJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4BAvBW,MAAM,cACN,OAAO,aACP,MAAM,iBACN,MAAM,GACJ,OAAO,CAAC,WAAS,MAAM,CAAC,CAwEpC"}

package/types/dist/lib/runtime/runtime.d.mts

@@ -0,0 +1,49 @@
+export function runWithCtx(ctx: object, fn: Function, thisArg: any, args: any[]): any;
+export function getCtx(): object | null;
+export function makeWrapper(ctx: object): Function;
+/**
+ * @constant self
+ * @memberof module:@cldmv/slothlet/runtime
+ * @export module:@cldmv/slothlet/runtime
+ * @public
+ * @type {function|object}
+ *
+ * @description
+ * Live binding to the current instance's 'self' reference from AsyncLocalStorage context.
+ *
+ * @example
+ * // Access current instance self
+ * console.log(self); // Current slothlet instance
+ */
+export const self: Function | object;
+/**
+ * @constant context
+ * @memberof module:@cldmv/slothlet/runtime
+ * @export module:@cldmv/slothlet/runtime
+ * @public
+ * @type {object}
+ *
+ * @description
+ * Live binding to the current instance's 'context' data from AsyncLocalStorage context.
+ *
+ * @example
+ * // Access current context data
+ * console.log(context); // Current context object
+ */
+export const context: object;
+/**
+ * @constant reference
+ * @memberof module:@cldmv/slothlet/runtime
+ * @export module:@cldmv/slothlet/runtime
+ * @public
+ * @type {object}
+ *
+ * @description
+ * Live binding to the current instance's 'reference' object from AsyncLocalStorage context.
+ *
+ * @example
+ * // Access current reference object
+ * console.log(reference); // Current reference data
+ */
+export const reference: object;
+//# sourceMappingURL=runtime.d.mts.map

package/types/dist/lib/runtime/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime.mjs"],"names":[],"mappings":"AA0CO,gCAdI,MAAM,yBAEN,GAAG,gBAED,GAAG,CA6Bf;AAiBM,0BAZM,MAAM,GAAC,IAAI,CAY0B;AAsB3C,iCAjBI,MAAM,YAwDhB;AA4RD;;;;;;;;;;;;;GAaG;AACH,mBATU,WAAS,MAAM,CAS6B;AAEtD;;;;;;;;;;;;;GAaG;AACH,sBATU,MAAM,CAS4C;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBATU,MAAM,CASgD"}

package/types/dist/slothlet.d.mts

@@ -0,0 +1,124 @@
+/**
+ * Mutates a live-binding variable (object or function) to match a new value, preserving reference.
+ * @param {function|object} target - The variable to mutate (object or function).
+ * @param {function|object} source - The new value to copy from (object or function).
+ * @private
+ * @internal
+ * @example
+ * mutateLiveBindingFunction(self, newSelf);
+ * mutateLiveBindingFunction(boundapi, newApi);
+ */
+export function mutateLiveBindingFunction(target: Function | object, source: Function | object): void;
+/**
+ * The shared _slothlet parameter for live binding coordination.
+ * @type {string}
+ * @private
+ * @internal
+ */
+export let _slothlet: string;
+/**
+ * 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
+ */
+export const context: object;
+/**
+ * Live-binding reference for reference data.
+ * @type {object}
+ * @private
+ * @internal
+ */
+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.
+     */
+    dir?: string;
+    /**
+     * - Loading strategy:
+     * - `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)
+     */
+    lazy?: boolean;
+    /**
+     * - 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
+     */
+    apiDepth?: number;
+    /**
+     * - 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
+     */
+    debug?: boolean;
+    /**
+     * - 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
+     */
+    mode?: string;
+    /**
+     * - 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_mode?: string;
+    /**
+     * - 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.
+     */
+    context?: object;
+    /**
+     * - 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.
+     */
+    reference?: object;
+    /**
+     * - Filename sanitization options for API property names.
+     * - Controls how file names are converted to valid JavaScript identifiers.
+     * - Default behavior: camelCase conversion with lowerFirst=true.
+     */
+    sanitize?: {
+        lowerFirst?: boolean;
+        rules?: {
+            leave?: string[];
+            leaveInsensitive?: string[];
+            upper?: string[];
+            lower?: string[];
+        };
+    };
+};
+/**
+ * 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<function|object>} The bound API object or function
+ * @public
+ */
+export function slothlet(options?: SlothletOptions): Promise<Function | object>;
+//# sourceMappingURL=slothlet.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AAi5CA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AAzzCD;;;;;GAKG;AACH,sBAJU,MAAM,CAIoE;AAKpF;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UAiyCd,MAAM;;;;;;WAIN,OAAO;;;;;;;eAGP,MAAM;;;;;;;;YAIN,OAAO;;;;;;;;WAKP,MAAM;;;;;;;eAKN,MAAM;;;;;;cAIN,MAAM;;;;;;gBAGN,MAAM;;;;;;eAMjB;QAA8B,UAAU,GAA7B,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;;AAv0CD;;;;;;;;GAQG;AACH,mCAJW,eAAe,GACb,OAAO,CAAC,WAAS,MAAM,CAAC,CAiCpC"}

package/types/index.d.mts

@@ -0,0 +1,23 @@
+/**
+ * TypeScript declarations for @cldmv/slothlet index
+ * 
+ * This file is auto-generated by tools/build-exports.mjs
+ * Run: npm run build:exports to regenerate
+ */
+
+// Re-export all types from the main slothlet module
+export type * from "./dist/slothlet.d.mts";
+// If you want runtime exports, use the implementation file instead:
+export * from "./dist/slothlet.mts";
+
+// Auto-generated named export declarations (these override the re-export above)
+export const _slothlet: any;
+export const context: any;
+export const mutateLiveBindingFunction: any;
+export const reference: any;
+export const self: any;
+
+// Main slothlet export
+declare const slothlet: any;
+export default slothlet;
+export { slothlet };