@cldmv/slothlet 1.0.1 → 2.0.1

package/index.cjs

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview CommonJS entry point for @cldmv/slothlet with automatic source/dist detection and live-binding context.
+ * @module @cldmv/slothlet
+ */
+
+const runtimePromise = import("@cldmv/slothlet/runtime");
+const modPromise = import("@cldmv/slothlet/slothlet");
+
+// Development environment check (must happen before slothlet imports)
+(async () => {
+	try {
+		await import("@cldmv/slothlet/devcheck");
+	} catch {
+		// ignore
+	}
+})();
+
+/**
+ * Creates a slothlet API instance with live-binding context and AsyncLocalStorage support.
+ * Automatically wraps all API functions with context isolation for multi-instance support.
+ * @public
+ * @async
+ *
+ * @param {object} [options={}] - Configuration options for the slothlet instance
+ * @param {string} [options.dir="api"] - Directory to load API modules from
+ * @param {boolean} [options.lazy=false] - Use lazy loading (true) or eager loading (false)
+ * @param {number} [options.apiDepth=Infinity] - Maximum directory depth to scan
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @param {string} [options.mode="singleton"] - Execution mode (singleton, vm, worker, fork)
+ * @param {string} [options.api_mode="auto"] - API structure mode (auto, function, object)
+ * @param {object} [options.context={}] - Context data for live bindings
+ * @param {object} [options.reference={}] - Reference objects to merge into API root
+ * @returns {Promise<function|object>} The bound API object with live-binding context
+ *
+ * @example // CJS
+ * const slothlet = require('@cldmv/slothlet');
+ * const api = await slothlet({ dir: './api', context: { user: 'alice' } });
+ * console.log(api.config.username); // Access configuration
+ */
+async function slothlet(options = {}) {
+	const [runtime, mod] = await Promise.all([runtimePromise, modPromise]);
+	const { makeWrapper } = runtime;
+	const build = mod.slothlet ?? mod.default;
+
+	const api = await build(options);
+
+	// Prefer an explicit instance context the internal attached to the API (api.__ctx),
+	// else fall back to module-level pieces if you expose them.
+	const ctx = api?.__ctx ?? { self: mod.self, context: mod.context, reference: mod.reference };
+
+	// console.log("[DEBUG index.cjs] Context setup:", {
+	// 	hasApiCtx: !!api?.__ctx,
+	// 	ctxSelfType: typeof ctx.self,
+	// 	ctxSelfKeys: Object.keys(ctx.self || {}),
+	// 	ctxContextType: typeof ctx.context,
+	// 	ctxContextKeys: Object.keys(ctx.context || {}),
+	// 	ctxReferenceType: typeof ctx.reference,
+	// 	ctxReferenceKeys: Object.keys(ctx.reference || {}),
+	// 	fallbackToMod: !api?.__ctx
+	// });
+
+	return makeWrapper(ctx)(api);
+}
+
+/**
+ * CommonJS default export of the slothlet function.
+ * @public
+ */
+module.exports = slothlet;
+
+/**
+ * Named export alias for the slothlet function.
+ * Provides the same functionality as the default export.
+ * @public
+ * @type {Function}
+ *
+ * @example // CJS named destructuring
+ * const { slothlet } = require('@cldmv/slothlet');
+ * const api = await slothlet({ dir: './api' });
+ */
+module.exports.slothlet = slothlet; // optional named alias

package/index.mjs

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview ESM entry point for @cldmv/slothlet with automatic source/dist detection and live-binding context.
+ * @module @cldmv/slothlet
+ */
+
+// Development environment check (must happen before slothlet imports)
+(async () => {
+	try {
+		await import("@cldmv/slothlet/devcheck");
+	} catch {
+		// ignore
+	}
+})();
+
+/**
+ * Creates a slothlet API instance with live-binding context and AsyncLocalStorage support.
+ * Automatically wraps all API functions with context isolation for multi-instance support.
+ * @public
+ * @async
+ *
+ * @param {object} [options={}] - Configuration options for the slothlet instance
+ * @param {string} [options.dir="api"] - Directory to load API modules from
+ * @param {boolean} [options.lazy=false] - Use lazy loading (true) or eager loading (false)
+ * @param {number} [options.apiDepth=Infinity] - Maximum directory depth to scan
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @param {string} [options.mode="singleton"] - Execution mode (singleton, vm, worker, fork)
+ * @param {string} [options.api_mode="auto"] - API structure mode (auto, function, object)
+ * @param {object} [options.context={}] - Context data for live bindings
+ * @param {object} [options.reference={}] - Reference objects to merge into API root
+ * @returns {Promise<function|object>} The bound API object with live-binding context
+ *
+ * @example // ESM
+ * import slothlet from '@cldmv/slothlet';
+ * const api = await slothlet({ dir: './api', lazy: true });
+ * const result = await api.math.add(2, 3); // 5
+ *
+ */
+export default async function slothlet(options = {}) {
+	// Dynamic imports after environment check
+	const [runtime, mod] = await Promise.all([import("@cldmv/slothlet/runtime"), import("@cldmv/slothlet/slothlet")]);
+
+	const { makeWrapper } = runtime;
+	const build = mod.slothlet ?? mod.default;
+
+	const api = await build(options);
+
+	// Prefer an explicit instance context the internal attached to the API (api.__ctx),
+	// else fall back to module-level pieces if you expose them.
+	const ctx = api?.__ctx ?? { self: mod.self, context: mod.context, reference: mod.reference };
+
+	// console.log("[DEBUG index.mjs] Context setup:", {
+	// 	hasApiCtx: !!api?.__ctx,
+	// 	ctxSelfType: typeof ctx.self,
+	// 	ctxSelfKeys: Object.keys(ctx.self || {}),
+	// 	ctxContextType: typeof ctx.context,
+	// 	ctxContextKeys: Object.keys(ctx.context || {}),
+	// 	ctxReferenceType: typeof ctx.reference,
+	// 	ctxReferenceKeys: Object.keys(ctx.reference || {}),
+	// 	fallbackToMod: !api?.__ctx
+	// });
+	// return api;
+	return makeWrapper(ctx)(api);
+}
+
+/**
+ * Named export alias for the default slothlet function.
+ * Provides the same functionality as the default export.
+ * @public
+ * @type {Function}
+ *
+ * @example // ESM named import
+ * import { slothlet } from '@cldmv/slothlet';
+ * const api = await slothlet({ dir: './api' });
+ */
+// Optional named alias
+export { slothlet };

package/package.json

@@ -1,28 +1,123 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "1.0.1",
-	"description": "Slothlet: Lazy Modular API Loader for Node.js. Dynamically loads API modules and submodules only when accessed, supporting both lazy and eager loading.",
-	"main": "slothlet.mjs",
-	"exports": {
-		".": "./slothlet.mjs"
+	"version": "2.0.1",
+	"moduleVersions": {
+		"lazy": "1.0.0",
+		"eager": "1.0.0"
 	},
-	"directories": {
-		"test": "tests"
+	"description": "Slothlet: Modular API Loader for Node.js. Lazy mode dynamically loads API modules and submodules only when accessed, supporting both lazy and eager loading.",
+	"main": "./index.cjs",
+	"module": "./index.mjs",
+	"exports": {
+		".": {
+			"types": "./types/index.d.mts",
+			"import": "./index.mjs",
+			"require": "./index.cjs"
+		},
+		"./devcheck": {
+			"types": "./types/devcheck.d.mts",
+			"import": "./devcheck.mjs"
+		},
+		"./slothlet": {
+			"development": {
+				"types": "./types/src/slothlet.d.mts",
+				"import": "./src/slothlet.mjs"
+			},
+			"types": "./types/dist/slothlet.d.mts",
+			"import": "./dist/slothlet.mjs"
+		},
+		"./runtime": {
+			"development": {
+				"types": "./types/src/lib/runtime/runtime.d.mts",
+				"import": "./src/lib/runtime/runtime.mjs"
+			},
+			"types": "./types/dist/lib/runtime/runtime.d.mts",
+			"import": "./dist/lib/runtime/runtime.mjs"
+		},
+		"./helpers/*": {
+			"development": {
+				"types": "./types/src/lib/helpers/*.d.mts",
+				"import": "./src/lib/helpers/*.mjs"
+			},
+			"types": "./types/dist/lib/helpers/*.d.mts",
+			"import": "./dist/lib/helpers/*.mjs"
+		},
+		"./modes/*": {
+			"development": {
+				"types": "./types/src/lib/modes/*.d.mts",
+				"import": "./src/lib/modes/*.mjs"
+			},
+			"types": "./types/dist/lib/modes/*.d.mts",
+			"import": "./dist/lib/modes/*.mjs"
+		}
 	},
+	"types": "./types/index.d.mts",
 	"scripts": {
-		"test": "vitest run",
-		"testjest": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js"
+		"publish:manual": "npm publish --access public",
+		"test": "node tests/test-conditional.mjs",
+		"test:pre-build": "node tests/test-conditional.mjs",
+		"test:post-build": "npm run test:types",
+		"test:complete": "node tests/test-conditional.mjs && npm run test:post-build",
+		"test:unit": "vitest --config .configs/vitest.config.mjs run",
+		"test:node": "node tests/run-all-tests.mjs",
+		"test:all": "node tests/test-conditional.mjs && npm run test:node",
+		"test:types": "node tests/validate-typescript.mjs",
+		"debug": "node tests/debug-slothlet.mjs",
+		"test:entry": "node tests/test-entry-points.mjs",
+		"test:performance": "node tests/performance-benchmark.mjs",
+		"test:performance-aggregated": "node tests/performance-benchmark-aggregated.mjs",
+		"lint": "eslint --config .configs/eslint.config.mjs .",
+		"build": "node tools/build-with-tests.mjs",
+		"build:ci": "npm run build:cleanup && npm run build:dist && npm run build:types && npm run build:exports && npm run test:types && npm run build:prepend-license",
+		"build:unsafe": "npm run build:cleanup && npm run build:dist && npm run build:types && npm run build:exports && npm run test:types && npm run build:prepend-license",
+		"build:cleanup": "shx rm -rf types && shx rm -rf dist",
+		"build:dist": "shx mkdir -p dist && shx cp -r src/* dist/ && shx rm -rf dist/**/*.backup",
+		"build:types": "npx tsc -p .configs/tsconfig.dts.jsonc",
+		"build:docs": "npm run build:docs:slothlet && npm run build:docs:api-tests",
+		"build:docs:slothlet": "jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/helpers.cjs\" --template \"docs/template.hbs\" \"src/{slothlet.mjs,lib/{modes,helpers,runtime}/**/*.mjs}\" > docs/API.md",
+		"build:docs:api-tests": "npm run build:docs:api-test && npm run build:docs:api-test-cjs && npm run build:docs:api-test-mixed",
+		"build:docs:api-test": "shx mkdir -p docs/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/helpers.cjs\" --template \"docs/template.hbs\" \"api_tests/api_test/**/*.mjs\" > docs/api_tests/api_test.md",
+		"build:docs:api-test-cjs": "shx mkdir -p docs/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/helpers.cjs\" --template \"docs/template.hbs\" \"api_tests/api_test_cjs/**/*.{mjs,cjs}\" > docs/api_tests/api_test_cjs.md",
+		"build:docs:api-test-mixed": "shx mkdir -p docs/api_tests && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/helpers.cjs\" --template \"docs/template.hbs\" \"api_tests/api_test_mixed/**/*.{mjs,cjs}\" > docs/api_tests/api_test_mixed.md",
+		"build:docs:tools": "shx mkdir -p docs/tools && jsdoc2md -g grouped -m dl --no-cache --separators -c \".configs/jsdoc.config.json\" --helper \"docs/helpers.cjs\" --template \"docs/template.hbs\" \"tools/**/*.mjs\" > docs/tools/build-tools.md",
+		"build:exports": "node tools/build-exports.mjs",
+		"build:prepend-license": "node tools/prepend-license.mjs dist",
+		"prepublish-check": "npm run build && npm pack && node tools/prepublish-check.mjs"
 	},
 	"keywords": [
 		"api",
+		"api-loader",
+		"api-management",
+		"module-loader",
 		"lazy-loading",
+		"eager-loading",
+		"copy-left-materialization",
+		"proxy",
+		"asynclocalstorage",
+		"live-binding",
+		"context-isolation",
+		"dual-loading",
 		"modular",
+		"performance",
+		"optimization",
+		"startup-performance",
 		"nodejs",
-		"esm"
+		"esm",
+		"cjs",
+		"mixed-modules",
+		"dynamic-import",
+		"deferred-loading",
+		"framework",
+		"typescript",
+		"zero-dependencies"
 	],
+	"engines": {
+		"node": ">=16.4.0"
+	},
 	"author": {
 		"name": "Shinrai",
-		"email": "git@cldmv.net",
+		"company": "CLDMV",
+		"email": "git+npm@cldmv.net",
 		"url": "https://cldmv.net"
 	},
 	"contributors": [
@@ -32,9 +127,28 @@
 		}
 	],
 	"license": "Apache-2.0",
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/shinrai"
+	},
 	"type": "module",
 	"devDependencies": {
-		"jest": "^30.0.5",
+		"@eslint/css": "^0.10.0",
+		"@eslint/js": "^9.33.0",
+		"@eslint/json": "^0.13.1",
+		"@eslint/markdown": "^7.2.0",
+		"@html-eslint/eslint-plugin": "^0.45.0",
+		"@html-eslint/parser": "^0.45.0",
+		"chalk": "^5.6.0",
+		"dmd": "^7.1.1",
+		"eslint": "^9.33.0",
+		"jsdoc": "^4.0.4",
+		"jsdoc-to-markdown": "^9.1.2",
+		"jsdoc2md": "^1.0.0",
+		"jsonc-parser": "^3.3.1",
+		"prettier": "^3.3.3",
+		"shx": "^0.4.0",
+		"typescript": "^5.9.2",
 		"vest": "^5.4.6",
 		"vitest": "^3.2.4"
 	},
@@ -49,8 +163,16 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"prepack": "npm run build:ci",
 	"files": [
+		"index.mjs",
+		"index.cjs",
 		"README.md",
-		"LICENSE"
-	]
+		"LICENSE",
+		"types/dist/",
+		"types/index.d.mts",
+		"types/index.d.mts.map",
+		"dist/"
+	],
+	"sideEffects": false
 }

package/types/dist/lib/engine/slothlet_child.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=slothlet_child.d.mts.map

package/types/dist/lib/engine/slothlet_child.d.mts.map

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

package/types/dist/lib/engine/slothlet_engine.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Sets the shutdown function for the engine.
+ * @param {Function} fn - Shutdown function to set
+ * @returns {Function} Previously set shutdown function
+ * @example
+ * const prev = setShutdown(() => console.log('Shutting down'));
+ */
+export function setShutdown(fn: Function): Function;
+/**
+ * Creates a slothlet engine with the specified mode and options.
+ * @param {object} allOptions - Engine configuration options
+ * @param {string} allOptions.entry - Entry point for the slothlet module
+ * @param {string} [allOptions.mode="vm"] - Engine mode: "vm", "worker", "fork", or "child"
+ * @param {object} [allOptions.context] - Context object for modules
+ * @param {object} [allOptions.reference] - Reference object for modules
+ * @returns {Promise<object>} Engine instance with API and shutdown capabilities
+ * @example
+ * const engine = await createEngine({
+ *   entry: './api/index.mjs',
+ *   mode: 'vm',
+ *   context: { user: 'alice' }
+ * });
+ */
+export function createEngine(allOptions: {
+    entry: string;
+    mode?: string;
+    context?: object;
+    reference?: object;
+}): Promise<object>;
+export function makeFacade2(portal: any): () => void;
+//# sourceMappingURL=slothlet_engine.d.mts.map

package/types/dist/lib/engine/slothlet_engine.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet_engine.d.mts","sourceRoot":"","sources":["../../../../dist/lib/engine/slothlet_engine.mjs"],"names":[],"mappings":"AAoBA;;;;;;GAMG;AACH,oDAIC;AAED;;;;;;;;;;;;;;GAcG;AACH,yCAZG;IAA2B,KAAK,EAAxB,MAAM;IACc,IAAI,GAAxB,MAAM;IACc,OAAO,GAA3B,MAAM;IACc,SAAS,GAA7B,MAAM;CACd,GAAU,OAAO,CAAC,MAAM,CAAC,CAgC3B;AAyRD,qDA4BC"}

package/types/dist/lib/engine/slothlet_esm.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Minimal custom ESM loader for VM context fallback when SourceTextModule is unavailable.
+ * Parses import/export statements, loads dependencies recursively, and evaluates code in context.
+ * Limitations: Only supports static imports/exports, no top-level await, no dynamic import, no advanced ESM features.
+ * @param {object} context - The VM context.
+ * @param {string} fileUrl - The file URL to load.
+ * @param {Set<string>} [visited] - Tracks loaded modules to prevent cycles.
+ * @returns {Promise<object>} Module namespace object.
+ * @example
+ * const ns = await loadEsmModuleFallback(context, 'file:///path/to/mod.mjs');
+ */
+export function loadEsmModuleFallback(context: object, fileUrl: string, visited?: Set<string>): Promise<object>;
+/**
+ * Detects if a file is ESM based on extension or code content.
+ * @param {string} fileUrl
+ * @returns {Promise<boolean>}
+ */
+export function isEsmFile(fileUrl: string): Promise<boolean>;
+//# sourceMappingURL=slothlet_esm.d.mts.map

package/types/dist/lib/engine/slothlet_esm.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet_esm.d.mts","sourceRoot":"","sources":["../../../../dist/lib/engine/slothlet_esm.mjs"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,+CAPW,MAAM,WACN,MAAM,YACN,GAAG,CAAC,MAAM,CAAC,GACT,OAAO,CAAC,MAAM,CAAC,CAkM3B;AAED;;;;GAIG;AACH,mCAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAW5B"}

package/types/dist/lib/engine/slothlet_helpers.d.mts

@@ -0,0 +1,24 @@
+export function normalizeContext(ctx: any): any;
+export function installGlobalsInCurrentRealm(contextMap: any): void;
+export function extendSelfWithReference(self: any, reference: any): void;
+export function installPortalForSelf(): void;
+export function asUrl(p: any): any;
+export function isPlainObject(o: any): boolean;
+export function guessName(v: any): any;
+export function makeNodeishContext(): any;
+/**
+ * Loads a module into a VM context, supporting ESM (mjs), CJS (cjs), or auto-detection.
+ * @param {object} context - The VM context.
+ * @param {string} fileUrl - The file URL to load.
+ * @param {string} [mode='auto'] - 'auto', 'mjs', or 'cjs'.
+ * @returns {Promise<object>} Module namespace or SourceTextModule.
+ */
+export function loadEsmInVm2(context: object, fileUrl: string, mode?: string, ...args: any[]): Promise<object>;
+export function loadEsmInVm(context: any, fileUrl: any): Promise<any>;
+export function installContextGlobalsVM(context: any, userContext: any): void;
+export function bootSlothletVM(context: any, entryUrl: any, loadConfig: any, ctxRef: any): Promise<void>;
+export function marshalArgsReplaceFunctions(value: any, registerCb: any): any;
+export function reviveArgsReplaceTokens(value: any, invokeCb: any): any;
+export function containsFunction(value: any): boolean;
+export const HAS_STM: boolean;
+//# sourceMappingURL=slothlet_helpers.d.mts.map

package/types/dist/lib/engine/slothlet_helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slothlet_helpers.d.mts","sourceRoot":"","sources":["../../../../dist/lib/engine/slothlet_helpers.mjs"],"names":[],"mappings":"AAWA,gDAwBC;AAED,oEAGC;AAED,yEAYC;AAED,6CA6BC;AAED,mCAEC;AAED,+CAEC;AAED,uCAOC;AAQD,0CAyBC;AAED;;;;;;GAMG;AACH,sCALW,MAAM,WACN,MAAM,SACN,MAAM,mBACJ,OAAO,CAAC,MAAM,CAAC,CA2L3B;AAGD,sEAsDC;AAED,8EAYC;AAED,yGAmDC;AAID,8EAaC;AAED,wEAaC;AAED,sDAKC;AAhYD,8BAAiE"}

package/types/dist/lib/engine/slothlet_worker.d.mts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=slothlet_worker.d.mts.map

package/types/dist/lib/engine/slothlet_worker.d.mts.map

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

package/types/dist/lib/helpers/resolve-from-caller.d.mts

@@ -0,0 +1,149 @@
+/**
+ * @function getStack
+ * @package
+ * @internal
+ * @param {Function} [skipFn] - Function to skip in stack trace via Error.captureStackTrace
+ * @returns {Array<CallSite>} Array of V8 CallSite objects with methods like getFileName(), getLineNumber(), etc.
+ *
+ * @description
+ * Get V8 stack trace as CallSite array for debugging and caller detection.
+ * Temporarily overrides Error.prepareStackTrace to access raw V8 CallSite objects
+ * instead of formatted string stack traces. Provides safe restoration of original handler.
+ *
+ * @example
+ * // Get current call stack for debugging
+ * const stack = getStack();
+ * console.log(stack[0]?.getFileName?.()); // Current file path
+ * console.log(stack[0]?.getLineNumber?.()); // Current line number
+ *
+ * @example
+ * // Skip current function from stack trace
+ * function myFunction() {
+ *   return getStack(myFunction); // Stack starts from caller of myFunction
+ * }
+ * const callerStack = myFunction();
+ *
+ * @example
+ * // Stack analysis for caller detection
+ * function findCaller() {
+ *   const stack = getStack(findCaller);
+ *   for (const frame of stack) {
+ *     const filename = frame?.getFileName?.();
+ *     if (filename && !filename.includes('node_modules')) {
+ *       return filename; // First non-dependency file
+ *     }
+ *   }
+ * }
+ */
+export function getStack(skipFn?: Function): Array<CallSite>;
+/**
+ * @function resolvePathFromCaller
+ * @package
+ * @internal
+ * @param {string} rel - Relative path to resolve (e.g., '../config.json', './data/file.txt')
+ * @returns {string} Absolute filesystem path with platform-specific separators
+ * @throws {TypeError} When rel parameter is not a string
+ *
+ * @description
+ * Resolve a relative path from the caller's context to an absolute filesystem path.
+ * Primary public API for filesystem path resolution with intelligent caller detection.
+ * Uses sophisticated stack trace analysis to determine the appropriate base directory.
+ *
+ * Resolution behavior:
+ * - file:// URLs: Converted to filesystem paths via fileURLToPath()
+ * - Absolute paths: Returned unchanged (already absolute)
+ * - Relative paths: Resolved using caller detection algorithm
+ *
+ * Caller detection process:
+ * 1. Primary: Use sophisticated slothlet.mjs-aware stack analysis
+ * 2. Fallback: Use first non-helper frame if primary fails
+ * 3. Existence check: Prefer primary if target exists, otherwise use fallback
+ *
+ * @example
+ * // From a file at /project/src/modules/math.mjs
+ * const configPath = resolvePathFromCaller('../config.json');
+ * // Returns: /project/config.json (absolute filesystem path)
+ *
+ * @example
+ * // Short-circuit cases
+ * resolvePathFromCaller('file:///absolute/path.txt');
+ * // Returns: /absolute/path.txt (converted from URL)
+ *
+ * resolvePathFromCaller('/already/absolute/path.txt');
+ * // Returns: /already/absolute/path.txt (unchanged)
+ *
+ * @example
+ * // Relative resolution from different contexts
+ * // If called from /project/src/lib/utils.mjs:
+ * resolvePathFromCaller('./helpers/format.js');
+ * // Returns: /project/src/lib/helpers/format.js
+ *
+ * resolvePathFromCaller('../../config/settings.json');
+ * // Returns: /project/config/settings.json
+ */
+export function resolvePathFromCaller(rel: string): string;
+/**
+ * @function resolveUrlFromCaller
+ * @package
+ * @internal
+ * @param {string} rel - Relative path to resolve (e.g., '../config.json', './data/file.txt')
+ * @returns {string} Absolute file:// URL suitable for dynamic imports and URL operations
+ * @throws {TypeError} When rel parameter is not a string
+ *
+ * @description
+ * Resolve a relative path from the caller's context to a file:// URL.
+ * Companion API to resolvePathFromCaller that returns file:// URLs instead of filesystem paths.
+ * Uses identical caller detection algorithm but outputs URL format for ESM imports.
+ *
+ * Resolution behavior:
+ * - file:// URLs: Returned unchanged (already in URL format)
+ * - Absolute paths: Converted to file:// URLs via pathToFileURL()
+ * - Relative paths: Resolved using caller detection, then converted to URL
+ *
+ * Caller detection uses the same sophisticated algorithm as resolvePathFromCaller,
+ * but the final result is converted to a file:// URL for compatibility with
+ * ESM dynamic imports and other URL-based operations.
+ *
+ * @example
+ * // From a file at /project/src/modules/math.mjs
+ * const configUrl = resolveUrlFromCaller('../config.json');
+ * // Returns: file:///project/config.json (absolute file:// URL)
+ *
+ * @example
+ * // Short-circuit cases
+ * resolveUrlFromCaller('file:///absolute/path.txt');
+ * // Returns: file:///absolute/path.txt (unchanged)
+ *
+ * resolveUrlFromCaller('/already/absolute/path.txt');
+ * // Returns: file:///already/absolute/path.txt (converted to URL)
+ *
+ * @example
+ * // Dynamic ESM import usage
+ * const modulePath = resolveUrlFromCaller('./dynamic-module.mjs');
+ * const dynamicModule = await import(modulePath);
+ * // Works seamlessly with ESM import() which expects URLs
+ *
+ * @example
+ * // Cross-platform URL handling
+ * // Unix: resolveUrlFromCaller('../config.json') → file:///project/config.json
+ * // Windows: resolveUrlFromCaller('../config.json') → file:///C:/project/config.json
+ */
+export function resolveUrlFromCaller(rel: string): string;
+export function toFsPath(v: any): string | null;
+export type CallSite = {
+    getFileName: () => string | undefined;
+    getLineNumber: () => number | undefined;
+    getFunctionName: () => string | undefined;
+    getTypeName: () => string | undefined;
+    getMethodName: () => string | undefined;
+    getScriptNameOrSourceURL: () => string | undefined;
+    getColumnNumber: () => number | undefined;
+    isNative: () => boolean | undefined;
+    isEval: () => boolean | undefined;
+    isConstructor: () => boolean | undefined;
+    isToplevel: () => boolean | undefined;
+    isAsync: () => boolean | undefined;
+    isPromiseAll: () => boolean | undefined;
+    getPromiseIndex: () => number | undefined;
+};
+//# sourceMappingURL=resolve-from-caller.d.mts.map

package/types/dist/lib/helpers/resolve-from-caller.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-from-caller.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/resolve-from-caller.mjs"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,6CAhCa,KAAK,CAAC,QAAQ,CAAC,CA0C3B;AAqKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,2CAzCW,MAAM,GACJ,MAAM,CAsDlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,0CA1CW,MAAM,GACJ,MAAM,CAuDlB;AA/UM,4BAvBI,GAAG,GACD,MAAM,GAAC,IAAI,CAsB+F;;iBAmVzG,MAAY,MAAM,GAAC,SAAS;mBAC5B,MAAY,MAAM,GAAC,SAAS;qBAC5B,MAAY,MAAM,GAAC,SAAS;iBAC5B,MAAY,MAAM,GAAC,SAAS;mBAC5B,MAAY,MAAM,GAAC,SAAS;8BAC5B,MAAY,MAAM,GAAC,SAAS;qBAC5B,MAAY,MAAM,GAAC,SAAS;cAC5B,MAAY,OAAO,GAAC,SAAS;YAC7B,MAAY,OAAO,GAAC,SAAS;mBAC7B,MAAY,OAAO,GAAC,SAAS;gBAC7B,MAAY,OAAO,GAAC,SAAS;aAC7B,MAAY,OAAO,GAAC,SAAS;kBAC7B,MAAY,OAAO,GAAC,SAAS;qBAC7B,MAAY,MAAM,GAAC,SAAS"}