@cldmv/slothlet 2.11.0 → 3.0.1

package/types/dist/lib/helpers/api_builder/decisions.d.mts

@@ -1,213 +0,0 @@
-/**
- * Auto-flattening decision logic that determines whether a module should be flattened
- * based on filename matching, export patterns, and context.
- *
- * @function getFlatteningDecision
- * @internal
- * @package
- * @param {object} options - Flattening analysis options
- * @param {object} options.mod - The loaded module object
- * @param {string} options.fileName - Original filename (without extension)
- * @param {string} options.apiPathKey - Sanitized API key for the module
- * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist in the container
- * @param {boolean} options.isSelfReferential - Whether this is a self-referential export
- * @param {boolean} [options.moduleHasDefault] - Whether this specific module has a default export.
- *   Should use originalAnalysis.hasDefault when available for accuracy, as !!mod.default
- *   may be inaccurate after processModuleFromAnalysis modifies module structure.
- * @param {string} [options.categoryName] - Container/category name for context
- * @param {number} [options.totalModules=1] - Total number of modules in container
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {{
- *   shouldFlatten: boolean,
- *   flattenToRoot: boolean,
- *   flattenToCategory: boolean,
- *   preserveAsNamespace: boolean,
- *   useAutoFlattening: boolean,
- *   reason: string
- * }} Flattening decision result
- *
- * @description
- * Determines flattening behavior based on slothlet's established rules:
- *
- * 1. Self-referential exports: Never flatten (preserve as namespace)
- * 2. Multi-default context: Flatten modules WITHOUT defaults, preserve WITH defaults
- * 3. Single named export matching filename: Auto-flatten to use export directly
- * 4. Filename matches container: Flatten contents to container level
- * 5. Traditional context: Preserve as namespace unless auto-flattening applies
- *
- * @example
- * // Internal usage - single named export matching filename
- * const decision = getFlatteningDecision({
- *   mod: { math: { add: fn, multiply: fn } },
- *   fileName: "math", apiPathKey: "math",
- *   hasMultipleDefaultExports: false, isSelfReferential: false
- * });
- * // Returns: { shouldFlatten: true, useAutoFlattening: true, reason: "auto-flatten single named export" }
- */
-export function getFlatteningDecision(options: {
-    mod: object;
-    fileName: string;
-    apiPathKey: string;
-    hasMultipleDefaultExports: boolean;
-    isSelfReferential: boolean;
-    moduleHasDefault?: boolean;
-    categoryName?: string;
-    totalModules?: number;
-    debug?: boolean;
-}): {
-    shouldFlatten: boolean;
-    flattenToRoot: boolean;
-    flattenToCategory: boolean;
-    preserveAsNamespace: boolean;
-    useAutoFlattening: boolean;
-    reason: string;
-};
-/**
- * Handles function name preference logic for better API naming.
- *
- * @function applyFunctionNamePreference
- * @internal
- * @package
- * @param {object} options - Name preference options
- * @param {object} options.mod - The loaded module object
- * @param {string} options.fileName - Original filename (without extension)
- * @param {string} options.apiPathKey - Sanitized API key
- * @param {object} options.categoryModules - Target category modules object
- * @param {function} options.toapiPathKey - Function to sanitize names to API keys
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {{hasPreferredName: boolean, preferredKey: string}} Name preference result
- *
- * @description
- * Implements slothlet's function name preference logic where the original function name
- * is preferred over the sanitized filename when they represent the same semantic meaning
- * but have different capitalization (e.g., autoIP vs autoIp, parseJSON vs parseJson).
- *
- * @example
- * // Internal usage in _buildCategory
- * const preference = applyFunctionNamePreference({
- *   mod: { autoIP: function autoIP() {} },
- *   fileName: "auto-ip", apiPathKey: "autoIp",
- *   categoryModules, toapiPathKey: this._toapiPathKey, debug: true
- * });
- * // Returns: { hasPreferredName: true, preferredKey: "autoIP" }
- */
-export function applyFunctionNamePreference(options: {
-    mod: object;
-    fileName: string;
-    apiPathKey: string;
-    categoryModules: object;
-    toapiPathKey: Function;
-    debug?: boolean;
-}): {
-    hasPreferredName: boolean;
-    preferredKey: string;
-};
-/**
- * Processes a single module and applies it to the target API object based on flattening decisions.
- *
- * @function processModuleForAPI
- * @internal
- * @package
- * @param {object} options - Module processing options
- * @param {object} options.mod - The loaded module object
- * @param {string} options.fileName - Original filename (without extension)
- * @param {string} options.apiPathKey - Sanitized API key for the module
- * @param {boolean} options.hasMultipleDefaultExports - Whether multiple default exports exist
- * @param {boolean} options.isSelfReferential - Whether this is a self-referential export
- * @param {object} options.api - Target API object to modify (could be root api or categoryModules)
- * @param {function} [options.getRootDefault] - Function to get current root default function
- * @param {function} [options.setRootDefault] - Function to set the root default function
- * @param {object} [options.context] - Processing context
- * @param {boolean} [options.context.debug=false] - Enable debug logging
- * @param {string} [options.context.mode="unknown"] - Processing mode (root, subfolder, eager, lazy)
- * @param {string} [options.context.categoryName] - Container/category name
- * @param {number} [options.context.totalModules=1] - Total modules in container
- * @returns {{
- *   processed: boolean,
- *   rootDefaultSet: boolean,
- *   flattened: boolean,
- *   namespaced: boolean,
- *   apiAssignments: Record<string, any>
- * }} Processing result
- *
- * @description
- * Unified module processing logic that handles:
- * 1. Function default exports (multi-default, self-referential, traditional root contributor)
- * 2. Object/named exports with flattening decisions
- * 3. Export merging and namespace assignments
- * 4. Function name preference logic
- * 5. Root default function management
- *
- * @example
- * // Internal usage for root-level processing
- * const result = processModuleForAPI({
- *   mod, fileName, apiPathKey, hasMultipleDefaultExports, isSelfReferential, api,
- *   getRootDefault: () => rootDefaultFunction,
- *   setRootDefault: (fn) => { rootDefaultFunction = fn; },
- *   context: { debug: true, mode: "root", totalModules: 3 },
- *   originalAnalysis: { hasDefault: true, namedExportsCount: 2 }
- * });
- */
-export function processModuleForAPI(options: {
-    mod: object;
-    fileName: string;
-    apiPathKey: string;
-    hasMultipleDefaultExports: boolean;
-    isSelfReferential: boolean;
-    api: object;
-    getRootDefault?: Function;
-    setRootDefault?: Function;
-    context?: {
-        debug?: boolean;
-        mode?: string;
-        categoryName?: string;
-        totalModules?: number;
-    };
-}): {
-    processed: boolean;
-    rootDefaultSet: boolean;
-    flattened: boolean;
-    namespaced: boolean;
-    apiAssignments: Record<string, any>;
-};
-/**
- * Centralized category building decisions - contains ALL logic for directory/category processing.
- * This function analyzes a directory and returns decisions about how to structure the API,
- * but doesn't actually build the API (allowing eager/lazy modes to implement differently).
- *
- * @function buildCategoryDecisions
- * @internal
- * @package
- * @param {string} categoryPath - Path to the category directory
- * @param {object} options - Configuration options
- * @param {number} [options.currentDepth=0] - Current nesting depth
- * @param {number} [options.maxDepth=Infinity] - Maximum nesting depth
- * @param {string} [options.mode="eager"] - Loading mode ("eager" or "lazy")
- * @param {Function} [options.subdirHandler] - Handler for subdirectories (lazy mode)
- * @param {object} options.instance - Slothlet instance with _toapiPathKey, _shouldIncludeFile, config
- * @returns {Promise<object>} Category building decisions and data
- *
- * @example
- * // ESM usage
- * import { buildCategoryDecisions } from "@cldmv/slothlet/helpers/api_builder_decisions";
- * const decisions = await buildCategoryDecisions("/path/to/category", {
- *   currentDepth: 1,
- *   instance: slothletInstance
- * });
- *
- * @example
- * // CJS usage
- * const { buildCategoryDecisions } = require("@cldmv/slothlet/helpers/api_builder_decisions");
- * const decisions = await buildCategoryDecisions("/path/to/category", {
- *   currentDepth: 1,
- *   instance: slothletInstance
- * });
- */
-export function buildCategoryDecisions(categoryPath: string, options?: {
-    currentDepth?: number;
-    maxDepth?: number;
-    mode?: string;
-    subdirHandler?: Function;
-    instance: object;
-}): Promise<object>;
-//# sourceMappingURL=decisions.d.mts.map

package/types/dist/lib/helpers/api_builder/decisions.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"decisions.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/decisions.mjs"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,+CAtCG;IAAwB,GAAG,EAAnB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,UAAU,EAA1B,MAAM;IACW,yBAAyB,EAA1C,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACW,gBAAgB,GAAlC,OAAO;IAGU,YAAY,GAA7B,MAAM;IACW,YAAY,GAA7B,MAAM;IACY,KAAK,GAAvB,OAAO;CACf,GAAU;IACR,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf,CAyHH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qDAtBG;IAAwB,GAAG,EAAnB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,eAAe,EAA/B,MAAM;IACY,YAAY;IACZ,KAAK,GAAvB,OAAO;CACf,GAAU;IAAC,gBAAgB,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAC,CA4D7D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,6CAvCG;IAAwB,GAAG,EAAnB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,UAAU,EAA1B,MAAM;IACW,yBAAyB,EAA1C,OAAO;IACU,iBAAiB,EAAlC,OAAO;IACS,GAAG,EAAnB,MAAM;IACa,cAAc;IACd,cAAc;IAChB,OAAO,GAChC;QAAkC,KAAK,GAA/B,OAAO;QACkB,IAAI,GAA7B,MAAM;QACmB,YAAY,GAArC,MAAM;QACmB,YAAY,GAArC,MAAM;KACd;CAAA,GAAU;IACR,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACpC,CAsLH;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qDAzBW,MAAM,YAEd;IAAyB,YAAY,GAA7B,MAAM;IACW,QAAQ,GAAzB,MAAM;IACW,IAAI,GAArB,MAAM;IACa,aAAa;IAChB,QAAQ,EAAxB,MAAM;CACd,GAAU,OAAO,CAAC,MAAM,CAAC,CA2Z3B"}

package/types/dist/lib/helpers/api_builder/metadata.d.mts

@@ -1,99 +0,0 @@
-/**
- *	@Project: @cldmv/slothlet
- *	@Filename: /src/lib/helpers/api_builder/metadata.mjs
- *	@Date: 2025-12-31 00:00:00 -08:00
- *	@Author: Nate Hyson <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2025-12-31 22:30:16 -08:00 (1767249016)
- *	-----
- *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
- */
-/**
- * @fileoverview Metadata management utilities for API functions.
- * @module @cldmv/slothlet/lib/helpers/api_builder/metadata
- * @memberof module:@cldmv/slothlet.lib.helpers.api_builder
- * @internal
- * @private
- *
- * @description
- * Provides utilities for tagging functions with immutable metadata, cleaning stale metadata
- * from cached modules, and creating immutable metadata objects with deep freezing.
- *
- * Key Features:
- * - Immutable metadata with Proxy-based enforcement
- * - Deep freezing of nested objects and arrays
- * - Recursive traversal for tagging/cleaning object trees
- * - CommonJS cache-aware metadata cleanup
- */
-/**
- * Creates an immutable-but-extensible metadata proxy object.
- *
- * @function createImmutableMetadata
- * @param {object} initial - Initial metadata properties
- * @returns {object} Object with immutable existing properties but allows adding new ones
- *
- * @description
- * Creates an object that enforces immutability of existing properties while allowing
- * new properties to be added. This prevents tampering with security-critical metadata
- * while allowing runtime extension of metadata for additional context.
- *
- * Security features:
- * - Existing properties cannot be modified (non-writable, non-configurable after first set)
- * - Properties cannot be deleted
- * - New properties can be added, which then become immutable
- *
- * @example
- * const meta = createImmutableMetadata({ trusted: true, version: "1.0" });
- * meta.author = "Alice"; // OK - new property
- * meta.author = "Bob"; // FAIL - cannot modify after setting
- * meta.trusted = false;  // FAIL - cannot modify existing property
- * delete meta.version;   // FAIL - cannot delete properties
- */
-export function createImmutableMetadata(initial?: object): object;
-/**
- * Removes metadata from all functions in an object tree.
- *
- * @function cleanMetadata
- * @param {object|Function} obj - Object or function to clean
- * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
- * @returns {void}
- *
- * @description
- * Traverses an object/function tree and removes __metadata and __sourceFolder properties.
- * This is needed when reloading CommonJS modules that cache function object references.
- */
-export function cleanMetadata(obj: object | Function, visited?: WeakSet<any>): void;
-/**
- * Recursively tags all functions in an object tree with metadata.
- *
- * @function tagLoadedFunctions
- * @param {object|Function} obj - Object or function to tag
- * @param {object} metadata - Metadata object to attach
- * @param {string} baseDir - Base directory path for relative file tracking
- * @param {WeakSet} [visited] - Visited objects tracker to prevent infinite recursion
- * @returns {void}
- *
- * @description
- * Traverses an object/function tree and attaches immutable metadata to all functions.
- * Also tracks source file information (__sourceFile, __sourceLine) for stack trace
- * matching. Only tags functions that don't already have metadata (non-overwriting).
- *
- * Attached properties:
- * - __metadata: Immutable metadata proxy with all user-provided metadata
- * - __sourceFolder: Absolute path to the folder the module was loaded from
- * - __sourceFile: Absolute file path (for stack trace matching)
- * - __sourceLine: Line number where function is defined (for stack trace matching)
- *
- * @example
- * const modules = { math: { add: (a, b) => a + b } };
- * tagLoadedFunctions(modules, {
- *     trusted: true,
- *     version: "1.0.0",
- *     author: "Alice"
- * }, "/path/to/plugins");
- * // Now modules.math.add.__metadata.trusted === true
- */
-export function tagLoadedFunctions(obj: object | Function, metadata: object, baseDir: string, visited?: WeakSet<any>): void;
-//# sourceMappingURL=metadata.d.mts.map

package/types/dist/lib/helpers/api_builder/metadata.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"metadata.d.mts","sourceRoot":"","sources":["../../../../../dist/lib/helpers/api_builder/metadata.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,kDApBW,MAAM,GACJ,MAAM,CAmJlB;AAED;;;;;;;;;;;GAWG;AACH,mCARW,MAAM,WAAS,2BAEb,IAAI,CAyChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wCA1BW,MAAM,WAAS,YACf,MAAM,WACN,MAAM,2BAEJ,IAAI,CA+EhB"}

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

@@ -1,6 +0,0 @@
-export { addApiFromFolder } from "@cldmv/slothlet/helpers/api_builder/add_api";
-export { isLikelySerializable, analyzeModule, processModuleFromAnalysis, analyzeDirectoryStructure, getCategoryBuildingDecisions } from "@cldmv/slothlet/helpers/api_builder/analysis";
-export { getFlatteningDecision, applyFunctionNamePreference, processModuleForAPI, buildCategoryDecisions } from "@cldmv/slothlet/helpers/api_builder/decisions";
-export { buildCategoryStructure, buildRootAPI, toapiPathKey, shouldIncludeFile } from "@cldmv/slothlet/helpers/api_builder/construction";
-export { safeDefine, deepMerge, mutateLiveBindingFunction } from "@cldmv/slothlet/helpers/utilities";
-//# sourceMappingURL=api_builder.d.mts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/api_builder.mjs"],"names":[],"mappings":""}

package/types/dist/lib/helpers/auto-wrap.d.mts

@@ -1,49 +0,0 @@
-/**
- *	@Project: @cldmv/slothlet
- *	@Filename: /src/lib/helpers/auto-wrap.mjs
- *	@Date: 2025-10-21 13:32:36 -07:00 (1761078756)
- *	@Author: Nate Hyson <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Hyson <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2025-10-22 06:59:17 -07:00 (1761141557)
- *	-----
- *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
- */
-/**
- * @fileoverview Helper for automatically wrapping Node.js EventEmitter instances within API modules.
- * Internal file (not exported in package.json).
- * @module @cldmv/slothlet/src/lib/helpers/auto-wrap
- */
-/**
- * Automatically wrap Node.js EventEmitter constructors when called within slothlet API context.
- * This ensures that EventEmitter instances created inside API modules preserve AsyncLocalStorage context.
- * @function autoWrapEventEmitters
- * @package
- * @param {NetModule} nodeModule - The Node.js module to wrap (e.g., require("node:net"))
- * @returns {NetModule} Wrapped module with auto-wrapping constructors
- *
- * @description
- * Wraps Node.js module functions that return EventEmitter instances so they automatically
- * return wrapped instances when called within slothlet API context.
- *
- * @example
- * // Usage in API modules:
- * import { autoWrapEventEmitters } from "@cldmv/slothlet/src/lib/helpers/auto-wrap";
- * import originalNet from "node:net";
- * const net = autoWrapEventEmitters(originalNet);
- * // Now net.createServer() returns wrapped instances automatically
- */
-export function autoWrapEventEmitters(nodeModule: NetModule): NetModule;
-/**
- * Lazily get the pre-wrapped net module for convenient use in API modules.
- * @function getNet
- * @package
- * @returns {Promise<NetModule>} Promise resolving to the wrapped net module
- * @example
- * const net = await getNet();
- */
-export function getNet(): Promise<NetModule>;
-export type NetModule = typeof import("node:net");
-export type NetServer = import("node:net").Server;
-//# sourceMappingURL=auto-wrap.d.mts.map

package/types/dist/lib/helpers/auto-wrap.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auto-wrap.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/auto-wrap.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAdW,SAAS,GACP,SAAS,CA6CrB;AAED;;;;;;;GAOG;AACH,0BAJa,OAAO,CAAC,SAAS,CAAC,CAO9B;wBAGY,cAAc,UAAU,CAAC;wBACzB,OAAO,UAAU,EAAE,MAAM"}