@cldmv/slothlet 2.7.1 → 2.9.0

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

@@ -1,449 +1,6 @@
-/**
- * Analyzes a module and returns processing decisions that both eager and lazy modes can use.
- * This centralizes the module loading logic from _loadSingleModule while allowing each mode
- * to handle the results according to their strategy (immediate materialization vs proxy creation).
- * @function analyzeModule
- * @internal
- * @package
- * @param {string} modulePath - Absolute path to the module file
- * @param {object} options - Analysis options
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @param {object} [options.instance] - Slothlet instance for accessing config and methods
- * @returns {Promise<{
- *   rawModule: object,
- *   processedModule: object,
- *   isFunction: boolean,
- *   hasDefault: boolean,
- *   isCjs: boolean,
- *   exports: Array<[string, any]>,
- *   defaultExportType: 'function'|'object'|null,
- *   shouldWrapAsCallable: boolean,
- *   namedExports: object,
- *   metadata: object
- * }>} Module analysis results
- * @example
- * // Analyze a module file
- * const analysis = await analyzeModule("./api/math.mjs", { instance });
- * // Eager mode: use analysis.processedModule directly
- * // Lazy mode: create proxy based on analysis.isFunction, analysis.exports, etc.
- */
-export function analyzeModule(modulePath: string, options?: {
-    debug?: boolean;
-    instance?: object;
-}): Promise<{
-    rawModule: object;
-    processedModule: object;
-    isFunction: boolean;
-    hasDefault: boolean;
-    isCjs: boolean;
-    exports: Array<[string, any]>;
-    defaultExportType: "function" | "object" | null;
-    shouldWrapAsCallable: boolean;
-    namedExports: object;
-    metadata: object;
-}>;
-/**
- * Processes module analysis results into a final module object using slothlet's established patterns.
- * This centralizes the processing logic while allowing both modes to apply the results differently.
- * @function processModuleFromAnalysis
- * @internal
- * @package
- * @param {object} analysis - Results from analyzeModule
- * @param {object} options - Processing options
- * @param {object} [options.instance] - Slothlet instance for accessing _toapiPathKey method
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {object} Processed module ready for API integration
- * @example
- * // Process analyzed module
- * const analysis = await analyzeModule(modulePath, { instance });
- * const processed = processModuleFromAnalysis(analysis, { instance });
- * // Both modes can use 'processed' but integrate it differently
- */
-export function processModuleFromAnalysis(analysis: object, options?: {
-    instance?: object;
-    debug?: boolean;
-}): object;
-/**
- * Analyzes a directory and returns structural decisions that both eager and lazy modes can use.
- * This provides the decision-making logic for directory handling without implementing the actual
- * loading strategy (allowing lazy mode to create proxies while eager mode materializes).
- * @function analyzeDirectoryStructure
- * @internal
- * @package
- * @param {string} categoryPath - Absolute path to the directory
- * @param {object} options - Analysis options
- * @param {object} options.instance - Slothlet instance for accessing config and methods
- * @param {number} [options.currentDepth=0] - Current traversal depth
- * @param {number} [options.maxDepth=Infinity] - Maximum traversal depth
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {Promise<{
- *   isSingleFile: boolean,
- *   shouldAutoFlatten: boolean,
- *   categoryName: string,
- *   moduleFiles: Array<import('fs').Dirent>,
- *   subDirs: Array<import('fs').Dirent>,
- *   multiDefaultAnalysis: object,
- *   processingStrategy: 'single-file'|'multi-file'|'empty',
- *   flatteningHints: object
- * }>} Directory structure analysis
- * @example
- * // Analyze directory structure
- * const analysis = await analyzeDirectoryStructure(categoryPath, { instance });
- * if (analysis.isSingleFile) {
- *   // Both modes: handle as single file (but differently)
- * } else {
- *   // Both modes: handle as multi-file (but differently)
- * }
- */
-export function analyzeDirectoryStructure(categoryPath: string, options?: {
-    instance: object;
-    currentDepth?: number;
-    maxDepth?: number;
-    debug?: boolean;
-}): Promise<{
-    isSingleFile: boolean;
-    shouldAutoFlatten: boolean;
-    categoryName: string;
-    moduleFiles: Array<import("fs").Dirent>;
-    subDirs: Array<import("fs").Dirent>;
-    multiDefaultAnalysis: object;
-    processingStrategy: "single-file" | "multi-file" | "empty";
-    flatteningHints: object;
-}>;
-/**
- * Returns category building decisions and processed modules that both eager and lazy modes can use.
- * This provides all the structural information needed to build a category but lets each mode
- * implement the actual building strategy (materialization vs proxy creation).
- * @function getCategoryBuildingDecisions
- * @internal
- * @package
- * @param {string} categoryPath - Absolute path to the directory
- * @param {object} options - Building options
- * @param {object} options.instance - Slothlet instance for accessing config and methods
- * @param {number} [options.currentDepth=0] - Current traversal depth
- * @param {number} [options.maxDepth=Infinity] - Maximum traversal depth
- * @param {boolean} [options.debug=false] - Enable debug logging
- * @returns {Promise<{
- *   processingStrategy: 'single-file'|'multi-file'|'empty',
- *   categoryName: string,
- *   shouldFlattenSingle: boolean,
- *   processedModules: Array<{file: import('fs').Dirent, moduleName: string, processedModule: any, flattening: object}>,
- *   subDirectories: Array<{dirEntry: import('fs').Dirent, apiPathKey: string}>,
- *   multiDefaultAnalysis: object,
- *   flatteningDecisions: object,
- *   upwardFlatteningCandidate: {shouldFlatten: boolean, apiPathKey: string}
- * }>} Complete category building information
- * @example
- * // Get category building decisions
- * const decisions = await getCategoryBuildingDecisions(categoryPath, { instance });
- * if (decisions.processingStrategy === "single-file") {
- *   // Both modes: handle single file differently
- *   // Eager: return decisions.processedModules[0].processedModule
- *   // Lazy: create proxy based on decisions.processedModules[0].flattening
- * }
- */
-export function getCategoryBuildingDecisions(categoryPath: string, options?: {
-    instance: object;
-    currentDepth?: number;
-    maxDepth?: number;
-    debug?: boolean;
-}): Promise<{
-    processingStrategy: "single-file" | "multi-file" | "empty";
-    categoryName: string;
-    shouldFlattenSingle: boolean;
-    processedModules: Array<{
-        file: import("fs").Dirent;
-        moduleName: string;
-        processedModule: any;
-        flattening: object;
-    }>;
-    subDirectories: Array<{
-        dirEntry: import("fs").Dirent;
-        apiPathKey: string;
-    }>;
-    multiDefaultAnalysis: object;
-    flatteningDecisions: object;
-    upwardFlatteningCandidate: {
-        shouldFlatten: boolean;
-        apiPathKey: string;
-    };
-}>;
-/**
- * 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;
-};
-/**
- * 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>;
-};
-/**
- * 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;
-};
-/**
- * Comprehensive category/directory building function that replaces _buildCategory.
- * Handles complete directory structure processing with all flattening rules.
- * @function buildCategoryStructure
- * @internal
- * @package
- * @async
- * @param {string} categoryPath - Absolute path to the category directory
- * @param {object} options - Building options
- * @param {number} [options.currentDepth=0] - Current recursion depth
- * @param {number} [options.maxDepth=Infinity] - Maximum recursion depth
- * @param {string} [options.mode="eager"] - Loading mode ("eager" or "lazy")
- * @param {function} [options.subdirHandler] - Custom subdirectory handler for lazy mode
- * @param {object} options.instance - Slothlet instance for access to helper methods
- * @returns {Promise<object>} Complete category API structure
- *
- * @description
- * Complete directory structure building pipeline that handles:
- * - Single-file vs multi-file directory processing
- * - Auto-flattening decisions for single files matching directory names
- * - Multi-default export detection and processing
- * - Self-referential export handling
- * - Recursive subdirectory traversal with depth control
- * - Function name preference over sanitized names
- * - All established slothlet flattening rules and conventions
- *
- * @example
- * // Internal usage - build complete category structure
- * const categoryApi = await buildCategoryStructure("/path/to/category", {
- *   currentDepth: 0, maxDepth: 3, mode: "eager", instance: slothletInstance
- * });
- */
-export function buildCategoryStructure(categoryPath: string, options?: {
-    currentDepth?: number;
-    maxDepth?: number;
-    mode?: string;
-    subdirHandler?: Function;
-    instance: object;
-}): Promise<object>;
-/**
- * Comprehensive root API building function that replaces eager/lazy create methods.
- * Handles complete root-level API construction with mode-specific optimizations.
- * @function buildRootAPI
- * @internal
- * @package
- * @async
- * @param {string} dir - Root directory path to build API from
- * @param {object} options - Building options
- * @param {boolean} [options.lazy=false] - Whether to use lazy loading mode
- * @param {number} [options.maxDepth=Infinity] - Maximum recursion depth
- * @param {object} options.instance - Slothlet instance for access to helper methods
- * @returns {Promise<object|function>} Complete root API (object or function with properties)
- *
- * @description
- * Complete root API building pipeline that handles:
- * - Root-level module processing with multi-default detection
- * - Root contributor pattern (default function becomes callable API)
- * - Named export merging and flattening decisions
- * - Recursive directory structure building via buildCategoryStructure
- * - Mode-specific optimizations (eager vs lazy)
- * - All established slothlet API construction patterns
- *
- * @example
- * // Internal usage - build complete root API
- * const rootApi = await buildRootAPI("/path/to/api", {
- *   lazy: false, maxDepth: 3, instance: slothletInstance
- * });
- */
-export function buildRootAPI(dir: string, options?: {
-    lazy?: boolean;
-    maxDepth?: number;
-    instance: object;
-}): Promise<object | Function>;
-/**
- * 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
- * @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";
- * const decisions = await buildCategoryDecisions("/path/to/category", {
- *   currentDepth: 1,
- *   instance: slothletInstance
- * });
- *
- * @example // CJS usage
- * const { buildCategoryDecisions } = require("@cldmv/slothlet/helpers/api_builder");
- * 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>;
+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 +1 @@
-{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/api_builder.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/api_builder.mjs"],"names":[],"mappings":""}

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

@@ -0,0 +1,120 @@
+/**
+ *	@Project: @cldmv/slothlet
+ *	@Filename: /src/lib/helpers/utilities.mjs
+ *	@Date: 2025-12-30 08:44:44 -08:00 (1767113084)
+ *	@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-30 08:54:56 -08:00 (1767113696)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
+ */
+/**
+ * @fileoverview Utility functions for property manipulation and object operations.
+ * @module @cldmv/slothlet/lib/helpers/utilities
+ * @memberof module:@cldmv/slothlet.lib.helpers
+ * @internal
+ * @private
+ *
+ * @description
+ * Provides general-purpose utility functions for safe property definition, deep object merging,
+ * and live-binding variable mutation. These utilities are used throughout slothlet for
+ * object manipulation, property management, and live-binding operations.
+ *
+ * Exported Functions:
+ * - safeDefine: Safe property definition handling non-configurable properties
+ * - deepMerge: Recursive deep merge for object combining
+ * - mutateLiveBindingFunction: Live-binding variable mutation preserving references
+ *
+ * @example
+ * // Internal usage in slothlet
+ * import { safeDefine, deepMerge, mutateLiveBindingFunction } from "./utilities.mjs";
+ *
+ * safeDefine(api, "shutdown", shutdownFunction, false);
+ * const merged = deepMerge(target, source);
+ * mutateLiveBindingFunction(boundapi, newApi);
+ */
+/**
+ * Safely defines a property on an object, handling non-configurable properties.
+ *
+ * @function safeDefine
+ * @memberof module:@cldmv/slothlet.lib.helpers.utilities
+ * @param {object} obj - Target object
+ * @param {string} key - Property key
+ * @param {*} value - Property value
+ * @param {boolean} [enumerable=false] - Whether the property should be enumerable (default: false for management methods)
+ * @param {object} [config=null] - Optional configuration object with debug flag
+ * @package
+ *
+ * @description
+ * Attempts to define a property on an object with the specified configuration.
+ * Handles cases where the property is non-configurable by logging a warning
+ * instead of throwing an error. Used for safely attaching management methods
+ * like shutdown, addApi, and describe to API objects.
+ *
+ * @example
+ * // Internal usage
+ * import { safeDefine } from "./utilities.mjs";
+ *
+ * safeDefine(api, "shutdown", shutdownFunction, false, { debug: true });
+ */
+export function safeDefine(obj: object, key: string, value: any, enumerable?: boolean, config?: object): void;
+/**
+ * Deep merge two objects recursively.
+ *
+ * @function deepMerge
+ * @memberof module:@cldmv/slothlet.lib.helpers.utilities
+ * @param {object} target - Target object to merge into
+ * @param {object} source - Source object to merge from
+ * @returns {object} Merged object (mutates target)
+ * @package
+ *
+ * @description
+ * Performs a recursive deep merge of two objects, combining nested structures.
+ * Arrays are treated as primitive values and replaced rather than merged.
+ * Used for context merging in scope operations.
+ *
+ * **Security Note**: This function explicitly blocks the `__proto__`, `prototype`, and
+ * `constructor` keys to prevent prototype pollution attacks. Any attempt to merge
+ * these dangerous keys will be silently ignored.
+ *
+ * @example
+ * // Internal usage
+ * import { deepMerge } from "./utilities.mjs";
+ *
+ * const target = { a: 1, b: { c: 2 } };
+ * const source = { b: { d: 3 }, e: 4 };
+ * const merged = deepMerge(target, source);
+ * // Result: { a: 1, b: { c: 2, d: 3 }, e: 4 }
+ */
+export function deepMerge(target: object, source: object): object;
+/**
+ * Mutates a live-binding variable (object or function) to match a new value, preserving reference.
+ *
+ * @function mutateLiveBindingFunction
+ * @memberof module:@cldmv/slothlet.lib.helpers.utilities
+ * @param {function|object} target - The variable to mutate (object or function)
+ * @param {function|object} source - The new value to copy from (object or function)
+ * @package
+ *
+ * @description
+ * Mutates an existing live-binding variable to match a new structure while
+ * preserving the original reference. This is critical for maintaining live
+ * bindings in modules that have imported self, context, or reference.
+ *
+ * For functions: Sets _impl to call source, removes old properties (except _impl and __ctx),
+ * and attaches new properties from source.
+ *
+ * For objects: Removes old properties (except _impl and __ctx), attaches new properties,
+ * and manually copies management methods (shutdown, addApi, describe).
+ *
+ * @example
+ * // Internal usage
+ * import { mutateLiveBindingFunction } from "./utilities.mjs";
+ *
+ * mutateLiveBindingFunction(self, newSelf);
+ * mutateLiveBindingFunction(boundapi, newApi);
+ */
+export function mutateLiveBindingFunction(target: Function | object, source: Function | object): void;
+//# sourceMappingURL=utilities.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/utilities.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gCAnBW,MAAM,OACN,MAAM,SACN,GAAC,eACD,OAAO,WACP,MAAM,QAkChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,kCAvBW,MAAM,UACN,MAAM,GACJ,MAAM,CAkDlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,kDAtBW,WAAS,MAAM,UACf,WAAS,MAAM,QAkEzB"}

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

@@ -5,6 +5,13 @@
  * @public
  */
 export const sharedALS: AsyncLocalStorageType;
+/**
+ * Per-request AsyncLocalStorage instance for request-scoped context.
+ * Stores temporary context data that merges with instance context.
+ * @type {AsyncLocalStorageType}
+ * @public
+ */
+export const requestALS: AsyncLocalStorageType;
 export function runWithCtx(ctx: object, fn: Function, thisArg: any, args: any[]): any;
 export function getCtx(): object | null;
 export function makeWrapper(ctx: object): Function;

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-asynclocalstorage.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-asynclocalstorage.mjs"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,wBAHU,qBAAqB,CAGkB;AAsB1C,gCAdI,MAAM,yBAEN,GAAG,gBAED,GAAG,CAoGf;AAiBM,0BAZM,MAAM,GAAC,IAAI,CAY0B;AAkN3C,iCAjBI,MAAM,YAiJhB;AAuSD;;;;;;;;;;;;;GAaG;AACH,mBATU,WAAS,MAAM,CAS6B;AAEtD;;;;;;;;;;;;;GAaG;AACH,sBATU,MAAM,CAS4C;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBATU,MAAM,CASgD;;kCApzB9B,kBAAkB"}
+{"version":3,"file":"runtime-asynclocalstorage.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-asynclocalstorage.mjs"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,wBAHU,qBAAqB,CAGkB;AAEjD;;;;;GAKG;AACH,yBAHU,qBAAqB,CAGmB;AAsB3C,gCAdI,MAAM,yBAEN,GAAG,gBAED,GAAG,CAwGf;AAiBM,0BAZM,MAAM,GAAC,IAAI,CAY0B;AAkN3C,iCAjBI,MAAM,YAiJhB;AA2TD;;;;;;;;;;;;;GAaG;AACH,mBATU,WAAS,MAAM,CAS6B;AAEtD;;;;;;;;;;;;;GAaG;AACH,sBATU,MAAM,CAS4C;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBATU,MAAM,CASgD;;kCAp1B9B,kBAAkB"}

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

@@ -23,6 +23,13 @@ export function makeWrapper(ctx: object): Function;
  */
 export function getContext(): any;
 export function setContext(newContext: any): void;
+/**
+ * Per-request AsyncLocalStorage instance for request-scoped context.
+ * Works alongside live bindings to provide per-request context isolation.
+ * @type {AsyncLocalStorage}
+ * @public
+ */
+export const requestALS: AsyncLocalStorage<any>;
 /**
  * Live-binding reference to the current API instance.
  * Automatically resolves to the appropriate instance based on calling context.
@@ -56,4 +63,5 @@ export namespace contextManager {
     export { setContext as set };
     export { runWithCtx };
 }
+import { AsyncLocalStorage } from "node:async_hooks";
 //# sourceMappingURL=runtime-livebindings.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-livebindings.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-livebindings.mjs"],"names":[],"mappings":"AA2RA;;;;;;;;;GASG;AACH,gCANW,MAAM,yBAEN,GAAG,gBAED,GAAG,CAoFf;AAED;;;;;;GAMG;AACH,iCAHW,MAAM,YAiEhB;AAID;;;GAGG;AAEH,kCAEC;AAED,kDASC;AAhYD;;;;;GAKG;AACH,mBAHU,MAAM,CAmDd;AAEF;;;;;GAKG;AACH,sBAHU,MAAM,CA+Cd;AAEF;;;;;GAKG;AACH,wBAHU,MAAM,CA+Cd;AAEF;;;;;GAKG;AACH,yBAHU,MAAM,CAkCd"}
+{"version":3,"file":"runtime-livebindings.d.mts","sourceRoot":"","sources":["../../../../dist/lib/runtime/runtime-livebindings.mjs"],"names":[],"mappings":"AA+SA;;;;;;;;;GASG;AACH,gCANW,MAAM,yBAEN,GAAG,gBAED,GAAG,CAoFf;AAED;;;;;;GAMG;AACH,iCAHW,MAAM,YAiEhB;AAID;;;GAGG;AAEH,kCAEC;AAED,kDASC;AA/bD;;;;;GAKG;AACH,gDAAkD;AA8ClD;;;;;GAKG;AACH,mBAHU,MAAM,CAmDd;AAEF;;;;;GAKG;AACH,sBAHU,MAAM,CA0Dd;AAEF;;;;;GAKG;AACH,wBAHU,MAAM,CA+Cd;AAEF;;;;;GAKG;AACH,yBAHU,MAAM,CAkCd;;;;;;kCA5QgC,kBAAkB"}