@cldmv/slothlet 1.0.1 → 2.0.1

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

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview String sanitization utilities for slothlet API property names. Internal file (not exported in package.json).
+ * @module @cldmv/slothlet.helpers.sanitize
+ * @memberof module:@cldmv/slothlet.helpers
+ * @internal
+ * @package
+ *
+ * @description
+ * Advanced string sanitization system for converting arbitrary file names into valid JavaScript
+ * property names suitable for slothlet's dot-notation API access. Implements sophisticated
+ * identifier validation, segment-based transformation rules, and configurable casing policies.
+ *
+ * Key features:
+ * - Valid identifier detection with fast-path optimization
+ * - Configurable first-segment casing (lowerFirst option)
+ * - Advanced rule-based transformation (leave, upper, lower arrays)
+ * - Cross-platform filename compatibility
+ * - Edge case handling for special characters and numeric prefixes
+ * - Camel-case conversion for multi-segment identifiers
+ *
+ * Technical implementation:
+ * - Uses regex-based validation for JavaScript identifier compliance
+ * - Segment splitting on non-identifier characters [^A-Za-z0-9_$]
+ * - Rule precedence: leave → upper → lower → default casing
+ * - Safety fallbacks for empty results and invalid identifier starts
+ * - Performance-optimized with early returns for valid identifiers
+ *
+ * Usage context:
+ * - File-to-API mapping in slothlet module loading
+ * - Dynamic property name generation for module namespaces
+ * - Sanitization of user-provided file names into safe property accessors
+ *
+ *
+ * @example
+ * // ESM (internal)
+ * import { sanitizePathName } from '@cldmv/slothlet/helpers/sanitize';
+ * // Internal example using package.json exports
+ *
+ * @example
+ * // Relative import (internal)
+ * import { sanitizePathName } from './sanitize.mjs';
+ * const apiKey = sanitizePathName('auto-ip.mjs');
+ */
+/**
+ * @function sanitizePathName
+ * @package
+ * @internal
+ * @param {string} input - The input string to sanitize (e.g., file name, path segment)
+ * @param {Object} [opts={}] - Sanitization configuration options
+ * @param {boolean} [opts.lowerFirst=true] - Lowercase the first character of the first segment for camelCase convention
+ * @param {Object} [opts.rules={}] - Advanced segment transformation rules
+ * @param {string[]} [opts.rules.leave=[]] - Segments to preserve exactly as-is (case-sensitive)
+ * @param {string[]} [opts.rules.upper=[]] - Segments to force to UPPERCASE
+ * @param {string[]} [opts.rules.lower=[]] - Segments to force to lowercase
+ * @returns {string} Valid JavaScript identifier safe for dot-notation property access
+ * @throws {TypeError} When input parameter is not a string
+ *
+ * @description
+ * Sanitize a string into a JS identifier suitable for dot-path usage.
+ * Core sanitization function that converts arbitrary strings (typically file names) into
+ * valid JavaScript identifiers following slothlet's API naming conventions.
+ *
+ * Sanitization algorithm:
+ * 1. **Fast path**: If input is already a valid JS identifier, return unchanged
+ * 2. **Segmentation**: Split on non-identifier characters [^A-Za-z0-9_$]
+ * 3. **Prefix cleanup**: Remove leading digits/invalid chars from first segment
+ * 4. **Rule application**: Apply leave/upper/lower rules with precedence
+ * 5. **Default casing**: First segment respects lowerFirst, others get title case
+ * 6. **Safety checks**: Ensure result starts with valid identifier character
+ *
+ * Rule precedence (applied in order):
+ * - `leave` rules: Preserve segment exactly as provided
+ * - `upper` rules: Force segment to UPPERCASE
+ * - `lower` rules: Force segment to lowercase
+ * - Default behavior: Apply standard camelCase conversion
+ *
+ * Edge case handling:
+ * - Empty input → "_" (safe fallback identifier)
+ * - Numeric prefixes → Stripped from first segment
+ * - All invalid chars → Returns "_" + cleaned content
+ * - No valid segments → Returns "_"
+ *
+ * @example
+ * // Basic sanitization (already valid identifiers unchanged)
+ * sanitizePathName("autoIP");                // "autoIP"  (no change needed)
+ * sanitizePathName("validIdentifier");       // "validIdentifier" (no change needed)
+ * sanitizePathName("auto_ip");               // "auto_ip" (valid identifier preserved)
+ *
+ * @example
+ * // Standard camelCase conversion
+ * sanitizePathName("auto-ip");               // "autoIp" (dash becomes camelCase)
+ * sanitizePathName("my file!.mjs");          // "myFileMjs" (spaces and special chars removed)
+ * sanitizePathName("foo-bar-baz");           // "fooBarBaz" (multi-segment camelCase)
+ *
+ * @example
+ * // Numeric prefix handling
+ * sanitizePathName("2autoIP");               // "autoIP" (leading digits stripped)
+ * sanitizePathName("123-test-file");         // "testFile" (digits stripped, camelCase applied)
+ *
+ * @example
+ * // First character casing control
+ * sanitizePathName("My-File");                        // "myFile" (lowerFirst=true default)
+ * sanitizePathName("My-File", { lowerFirst: false }); // "MyFile" (preserve capital first)
+ * sanitizePathName("API-util", { lowerFirst: false }); // "APIUtil" (preserve capital first)
+ *
+ * @example
+ * // Advanced rule-based transformation
+ * sanitizePathName("foo-api-json", {
+ *   rules: {
+ *     leave: ["foo"],    // Keep "foo" exactly as-is
+ *     upper: ["api"],    // Force "api" to "API"
+ *     lower: ["JSON"]    // Force "JSON" to "json"
+ *   }
+ * }); // Result: "fooAPIjson"
+ *
+ * @example
+ * // Real-world slothlet file mapping scenarios
+ * sanitizePathName("auto-ip.mjs");           // "autoIp" (common filename pattern)
+ * sanitizePathName("parseJSON.mjs");         // "parseJSON" (preserve common acronym)
+ * sanitizePathName("get-HTTP-status.js");    // "getHTTPStatus" (multi-acronym handling)
+ * sanitizePathName("root-math.mjs");         // "rootMath" (typical slothlet module name)
+ *
+ * @example
+ * // Edge cases and safety handling
+ * sanitizePathName("");                      // "_" (empty string fallback)
+ * sanitizePathName("123");                   // "_" (all numeric becomes fallback)
+ * sanitizePathName("!@#$%");                 // "_" (all special chars becomes fallback)
+ * sanitizePathName("valid@#$invalid");       // "validInvalid" (special chars removed)
+ */
+export function sanitizePathName(input: string, opts?: {
+    lowerFirst?: boolean;
+    rules?: {
+        leave?: string[];
+        upper?: string[];
+        lower?: string[];
+    };
+}): string;
+//# sourceMappingURL=sanitize.d.mts.map

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,wCAlFW,MAAM,SAEd;IAAuB,UAAU,GAAzB,OAAO;IACO,KAAK,GAC3B;QAA8B,KAAK,GAA3B,MAAM,EAAE;QACc,KAAK,GAA3B,MAAM,EAAE;QACc,KAAK,GAA3B,MAAM,EAAE;KAChB;CAAA,GAAU,MAAM,CAkIlB"}

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,110 @@
+/**
+ * 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;
+};
+/**
+ * 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":"AA44CA;;;;;;;;;GASG;AACH,kDARW,WAAS,MAAM,UACf,WAAS,MAAM,QAwCzB;AApzCD;;;;;GAKG;AACH,sBAJU,MAAM,CAIoE;AAKpF;;;;;;;GAOG;AACH,mBAJU,MAAM,CAIO;AAEvB;;;;;GAKG;AACH,sBAJU,MAAM,CAIU;AAE1B;;;;;GAKG;AACH,wBAJU,MAAM,CAIY;;;;;;;;;UA4xCd,MAAM;;;;;;WAIN,OAAO;;;;;;;eAGP,MAAM;;;;;;;;YAIN,OAAO;;;;;;;;WAKP,MAAM;;;;;;;eAKN,MAAM;;;;;;cAIN,MAAM;;;;;;gBAGN,MAAM;;AAtzCpB;;;;;;;;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 };