@cldmv/wisp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CLDMV Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @cldmv/wisp
+
+A Node.js module for version-agnostic JSON importing, providing transparent support for modern and legacy import syntaxes with automatic fallbacks.
+
+## Overview
+
+`@cldmv/wisp` allows you to load JSON files in Node.js without worrying about version-specific import syntax. It automatically tries the most modern import methods first and falls back to reliable file system operations.
+
+## Node.js Version Support
+
+| Node Version | `import ... with { type: 'json' }` | `import ... assert { type: 'json' }` | Fallback |
+| ------------ | ---------------------------------- | ------------------------------------ | -------- |
+| ≥ 22.10      | ✅                                 | ✅                                   | ✅       |
+| ≥ 20.10      | ✅                                 | ✅                                   | ✅       |
+| ≥ 18.20      | ✅                                 | ✅                                   | ✅       |
+| ≥ 16.14      | ❌                                 | ✅                                   | ✅       |
+| < 16.14      | ❌                                 | ❌                                   | ✅       |
+
+## Installation
+
+```bash
+npm install @cldmv/wisp
+```
+
+## Usage
+
+### ESM (Modern)
+
+```javascript
+import { wisp, wispSync } from "@cldmv/wisp";
+
+// Asynchronous loading
+const config = await wisp("./config.json");
+
+// Synchronous loading
+const data = wispSync("./data.json");
+```
+
+### CJS (CommonJS)
+
+```javascript
+const { wisp, wispSync } = require("@cldmv/wisp");
+
+// Asynchronous loading
+wisp("./config.json").then((config) => {
+	console.log(config);
+});
+
+// Synchronous loading
+const data = wispSync("./data.json");
+```
+
+## API Reference
+
+### `wisp(input, options?)`
+
+Asynchronously loads JSON from a file.
+
+#### Parameters
+
+- `input` (string | URL): Path or URL to the JSON file
+- `options` (object, optional):
+  - `base` (string | URL, optional): Base URL for resolving relative paths. Defaults to the caller's file URL.
+  - `validate` (function, optional): Validation function called with the parsed JSON. Throws if validation fails.
+  - `reviver` (function, optional): Reviver function passed to `JSON.parse`.
+
+#### Returns
+
+`Promise<*>`: The parsed JSON value.
+
+#### Example
+
+```javascript
+import { wisp } from "@cldmv/wisp";
+
+const data = await wisp("./config.json", {
+	validate: (json) => {
+		if (!json.requiredField) throw new Error("Missing required field");
+	},
+	reviver: (key, value) => (key === "date" ? new Date(value) : value)
+});
+```
+
+### `wispSync(input, options?)`
+
+Synchronously loads JSON from a file.
+
+#### Parameters
+
+- `input` (string | URL): Path or URL to the JSON file
+- `options` (object, optional): Same as `wisp` options.
+
+#### Returns
+
+`Promise<*>`: The parsed JSON value.
+
+#### Example
+
+```javascript
+import { wispSync } from "@cldmv/wisp";
+
+const data = wispSync("./config.json", {
+	validate: (json) => {
+		if (!json.version) throw new Error("Version required");
+	}
+});
+```
+
+## Options
+
+| Option     | Type       | Description                                                              |
+| ---------- | ---------- | ------------------------------------------------------------------------ |
+| `base`     | string/URL | Base URL for relative path resolution. Defaults to caller's file URL.    |
+| `validate` | function   | Validation function. Receives parsed JSON, should throw on invalid data. |
+| `reviver`  | function   | JSON.parse reviver function for custom parsing.                          |
+
+## Path Resolution
+
+`@cldmv/wisp` uses caller-aware path resolution:
+
+- Relative paths are resolved relative to the file that calls `wisp` or `wispSync`
+- Absolute paths and URLs are used as-is
+- The `base` option overrides the default caller-based resolution
+
+## Fallback Order
+
+The module attempts to load JSON in this order:
+
+1. `import(url, { with: { type: 'json' } })` (Node ≥ 18.20/20.10/22)
+2. `import(url, { assert: { type: 'json' } })` (Node ≥ 16.14)
+3. `fs.readFile` / `fs.readFileSync` (all supported Node versions)
+
+This ensures maximum compatibility across Node.js versions.
+
+## Error Handling
+
+Validation errors are prefixed with `@cldmv/wisp:` for easy identification:
+
+```javascript
+try {
+	await wisp("./invalid.json", {
+		validate: () => {
+			throw new Error("Custom validation failed");
+		}
+	});
+} catch (error) {
+	console.log(error.message); // "@cldmv/wisp: Custom validation failed"
+}
+```
+
+## License
+
+MIT © CLDMV Inc.

package/index.cjs

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview CJS entry point for @cldmv/wisp, providing version-agnostic JSON importing.
+ * @module @cldmv/wisp
+ * @public
+ *
+ * @description
+ * This module provides CommonJS exports for the wisp and wispSync functions.
+ * It uses createRequire to load the ESM implementation and re-exports it.
+ *
+ * @example
+ * const { wisp, wispSync } = require('@cldmv/wisp');
+ * const data = wispSync('./data.json');
+ */
+
+"use strict";
+
+const { createRequire } = require("module");
+const requireESM = createRequire(__filename);
+const esm = requireESM("./index.mjs");
+
+module.exports = esm.default;
+module.exports.default = esm.default;
+module.exports.wisp = esm.wisp;
+module.exports.wispSync = esm.wispSync;

package/index.mjs

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Main entry point for @cldmv/wisp, providing version-agnostic JSON importing.
+ * @module @cldmv/wisp
+ * @public
+ *
+ * @description
+ * This module exports the wisp and wispSync functions for loading JSON files
+ * with support for different Node.js versions and import syntaxes.
+ *
+ * @example
+ * // ESM
+ * import { wisp, wispSync } from '@cldmv/wisp';
+ * const data = await wisp('./data.json');
+ *
+ * @example
+ * // CJS
+ * const { wisp, wispSync } = require('@cldmv/wisp');
+ * const data = wispSync('./data.json');
+ */
+
+export * from "./src/wisp.mjs";
+export { default } from "./src/wisp.mjs";

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "@cldmv/wisp",
+	"version": "1.0.0",
+	"description": "Version-agnostic JSON importing for Node.js with fallback handling and caller path resolution.",
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./index.mjs",
+			"require": "./index.cjs"
+		}
+	},
+	"scripts": {
+		"test": "mocha --recursive \"test/**/*.mjs\"",
+		"test:watch": "mocha --watch \"test/**/*.mjs\"",
+		"lint": "eslint src/",
+		"build:types": "tsc",
+		"test:types": "tsc --noEmit",
+		"build:ci": "npm run test && npm run build:types && npm run test:types"
+	},
+	"keywords": [
+		"json",
+		"import",
+		"nodejs",
+		"version-agnostic",
+		"fallback",
+		"loader",
+		"esm",
+		"cjs",
+		"wisp",
+		"api"
+	],
+	"author": {
+		"name": "Shinrai",
+		"company": "CLDMV",
+		"email": "git+npm@cldmv.net",
+		"url": "https://cldmv.net"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CLDMV/wisp.git"
+	},
+	"contributors": [
+		{
+			"name": "CLDMV",
+			"url": "https://github.com/CLDMV"
+		}
+	],
+	"bugs": {
+		"url": "https://github.com/CLDMV/wisp/issues"
+	},
+	"homepage": "https://github.com/CLDMV/wisp#readme",
+	"license": "MIT",
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/shinrai"
+	},
+	"files": [
+		"src/",
+		"types/",
+		"index.mjs",
+		"index.cjs",
+		"README.md",
+		"LICENSE",
+		"package.json"
+	],
+	"devDependencies": {
+		"mocha": "^10.2.0",
+		"chai": "^4.3.10",
+		"typescript": "^5.2.0",
+		"@types/node": "^20.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=16.0.0"
+	},
+	"sideEffects": false
+}

package/src/lib/resolve-from-caller.mjs

@@ -0,0 +1,440 @@
+/**
+ *	@Project: @cldmv/wisp
+ *	@Filename: /src/lib/resolve-from-caller.mjs
+ *	@Date: 2025-09-09 13:22:38 -07:00 (1757449358)
+ *	@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-31 07:31:40 -07:00 (1761921100)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+/**
+ * @fileoverview Path resolution utilities for resolving paths from the caller context. Internal file (not exported in package.json).
+ * @module @cldmv/wisp.helpers.resolve-from-caller
+ * @memberof module:@cldmv/wisp.helpers
+ * @internal
+ * @package
+ *
+ * @description
+ * Advanced path resolution system that uses V8 stack trace analysis to determine caller context.
+ * Provides utilities for resolving relative paths from the caller's directory, implementing
+ * sophisticated caller detection algorithms to handle complex module loading scenarios.
+ *
+ * Key features:
+ * - V8 CallSite-based stack trace analysis
+ * - Primary base file detection with fallback strategies
+ * - Support for both filesystem paths and file:// URLs
+ * - Smart handling of slothlet.mjs and index file patterns
+ * - Existence-based resolution with automatic fallback
+ *
+ * Technical implementation:
+ * - Uses Error.prepareStackTrace to access V8 CallSite objects
+ * - Implements dual-phase resolution (primary + fallback)
+ * - Handles edge cases like node:internal modules and helper directories
+ * - Provides both path and URL resolution variants
+ *
+ *
+ * @example
+ * // ESM (internal)
+ * import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-caller";
+ * // Internal example using package.json exports
+ *
+ * @example
+ * // Relative import (internal)
+ * import { resolvePathFromCaller, resolveUrlFromCaller } from "./resolve-from-caller.mjs";
+ * const configPath = resolvePathFromCaller("../config.json");
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/* ---------- tiny utils ---------- */
+
+/**
+ * @function toFsPath
+ * @package
+ * @internal
+ * @param {any} v - Value to convert (file:// URL, path string, or any other value)
+ * @returns {string|null} Filesystem path if URL conversion successful, original string if already a path, null if input is falsy
+ *
+ * @description
+ * Convert file:// URL to filesystem path, or return string as-is.
+ * Handles URL-to-path conversion for cross-platform compatibility while preserving
+ * non-URL strings unchanged. Provides null-safe operation for invalid inputs.
+ *
+ * @example
+ * // URL conversion
+ * toFsPath("file:///project/config.json"); // "/project/config.json" (Unix) or "C:\\project\\config.json" (Windows)
+ *
+ * @example
+ * // String passthrough
+ * toFsPath("/project/config.json"); // "/project/config.json"
+ * toFsPath("C:\\project\\config.json"); // "C:\\project\\config.json"
+ *
+ * @example
+ * // Null-safe handling
+ * toFsPath(null); // null
+ * toFsPath(undefined); // null
+ * toFsPath(""); // null
+ */
+export const toFsPath = (v) => (v && String(v).startsWith("file://") ? fileURLToPath(String(v)) : v ? String(v) : null);
+
+/**
+ * @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) {
+	const orig = Error.prepareStackTrace;
+	try {
+		Error.prepareStackTrace = (_, s) => s; // V8 CallSite[]
+		const e = new Error("Stack trace");
+		if (skipFn) Error.captureStackTrace(e, skipFn);
+		return /** @type {NodeJS.CallSite[]} */ (/** @type {unknown} */ (e.stack)) || [];
+	} finally {
+		Error.prepareStackTrace = orig;
+	}
+}
+
+const THIS_FILE = fileURLToPath(import.meta.url);
+const THIS_DIR = path.dirname(THIS_FILE);
+
+/* ---------- base selection (shared) ---------- */
+// Rule you specified:
+// 1) Find the LAST frame whose basename is "slothlet.mjs".
+// 2) Take the NEXT frame; if its basename is "index.[mjs|cjs|js]", take the following one.
+// 3) Fallback: first non-helper frame that isn’t slothlet.mjs.
+
+/**
+ * @function pickPrimaryBaseFile
+ * @internal
+ * @private
+ * @returns {string|null} Primary base file path for resolution, null if detection fails
+ *
+ * @description
+ * Find the primary base file using stack trace analysis.
+ * Implements sophisticated caller detection algorithm designed for slothlet's module loading patterns.
+ * Uses a two-phase approach: locate the last slothlet.mjs frame, then find the actual user code.
+ *
+ * Algorithm:
+ * 1. Scan stack trace to find the LAST frame whose basename is "slothlet.mjs"
+ * 2. Take the NEXT frame after slothlet.mjs
+ * 3. If that frame is "index.[mjs|cjs|js]", take the following frame instead
+ * 4. Return null if no suitable frame found (fallback will be used)
+ *
+ * This pattern handles slothlet's loading chain: slothlet.mjs → index.mjs → user-code.mjs
+ *
+ * @example
+ * // Stack trace scenario:
+ * // 0: pickPrimaryBaseFile() [this function]
+ * // 1: resolveWith() [internal helper]
+ * // 2: resolvePathFromCaller() [public API]
+ * // 3: slothlet.mjs [slothlet loader] ← LAST slothlet.mjs
+ * // 4: index.mjs [entry point] ← Skip this
+ * // 5: user-code.mjs [actual caller] ← Return this
+ */
+function pickPrimaryBaseFile() {
+	const files = [];
+	for (const cs of getStack(pickPrimaryBaseFile)) {
+		const f = toFsPath(cs?.getFileName?.());
+		if (!f) continue;
+		if (f.startsWith?.("node:internal")) continue;
+		files.push(f);
+	}
+
+	let iSloth = -1;
+	for (let i = 0; i < files.length; i++) {
+		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") iSloth = i;
+	}
+	if (iSloth !== -1) {
+		const j = iSloth + 1;
+		if (j < files.length) {
+			const b = path.basename(files[j]).toLowerCase();
+			if (/^index\.(mjs|cjs|js)$/.test(b) && j + 1 < files.length) return files[j + 1];
+			return files[j];
+		}
+	}
+	return null;
+}
+
+/**
+ * @function pickFallbackBaseFile
+ * @internal
+ * @private
+ * @returns {string} Fallback base file path, guaranteed to return a valid path
+ *
+ * @description
+ * Find fallback base file when primary detection fails.
+ * Provides robust fallback strategy by finding the first legitimate user code frame.
+ * Filters out internal Node.js modules, helper utilities, and slothlet infrastructure.
+ *
+ * Fallback algorithm:
+ * 1. Iterate through stack frames from top to bottom
+ * 2. Skip node:internal modules (Node.js internals)
+ * 3. Skip this file itself (resolve-from-caller.mjs)
+ * 4. Skip other files in the helpers directory
+ * 5. Skip slothlet.mjs infrastructure files
+ * 6. Return first remaining frame, or THIS_FILE as ultimate fallback
+ *
+ * This ensures we always have a base path for resolution, even in edge cases.
+ *
+ * @example
+ * // Fallback scenarios:
+ * // - Primary detection failed (no slothlet.mjs in stack)
+ * // - Complex loading chain with multiple loaders
+ * // - Edge cases like REPL or test environments
+ * // - Direct API usage without slothlet loader
+ */
+function pickFallbackBaseFile() {
+	for (const cs of getStack(pickFallbackBaseFile)) {
+		const f = toFsPath(cs?.getFileName?.());
+		if (!f) continue;
+		if (f.startsWith?.("node:internal")) continue;
+		if (f === THIS_FILE) continue;
+		if (f.startsWith(THIS_DIR + path.sep)) continue; // helper’s own dir
+		if (path.basename(f).toLowerCase() === "slothlet.mjs") continue;
+		return f;
+	}
+	return THIS_FILE;
+}
+
+/* ---------- generic resolver (shared) ---------- */
+
+/**
+ * @function resolveWith
+ * @internal
+ * @private
+ * @param {string} rel - Relative path to resolve (must be a string)
+ * @param {Function} makePrimary - Function to build primary candidate: (baseFile, rel) => candidate
+ * @param {Function} exists - Existence check function: (candidate) => boolean
+ * @param {Function} makeFallback - Function to build fallback result: (baseFile, rel) => result
+ * @returns {string} Resolved path or URL (type depends on make functions)
+ * @throws {TypeError} When rel parameter is not a string
+ *
+ * @description
+ * Generic resolver that tries primary base file detection with fallback.
+ * Core resolution engine that orchestrates the two-phase detection strategy.
+ * Attempts primary resolution first, then falls back if target doesn't exist.
+ *
+ * Resolution strategy:
+ * 1. Get primary base file using sophisticated stack analysis
+ * 2. Build primary candidate using makePrimary function
+ * 3. Check if primary candidate exists using exists function
+ * 4. If exists, return primary candidate
+ * 5. Otherwise, get fallback base file and build fallback result
+ * 6. Return fallback result (no second existence check)
+ *
+ * This pattern ensures we try the most accurate resolution first, but always
+ * provide a reasonable fallback even if the target doesn't exist yet.
+ *
+ * @example
+ * // Usage pattern for filesystem paths:
+ * resolveWith(
+ *   "../config.json",
+ *   (base, rel) => path.resolve(path.dirname(base), rel), // makePrimary
+ *   (candidate) => fs.existsSync(candidate),              // exists
+ *   (base, rel) => path.resolve(path.dirname(base), rel)  // makeFallback
+ * );
+ *
+ * @example
+ * // Usage pattern for URLs:
+ * resolveWith(
+ *   "../config.json",
+ *   (base, rel) => new URL(rel, pathToFileURL(base)).href, // makePrimary
+ *   (href) => fs.existsSync(fileURLToPath(href)),          // exists
+ *   (base, rel) => new URL(rel, pathToFileURL(base)).href  // makeFallback
+ * );
+ */
+function resolveWith(rel, makePrimary, exists, makeFallback) {
+	if (typeof rel !== "string") throw new TypeError("rel must be a string");
+
+	// absolute / already-URL cases are handled in the public wrappers
+	const primaryBase = pickPrimaryBaseFile() ?? pickFallbackBaseFile();
+	const primary = makePrimary(primaryBase, rel);
+	if (exists(primary)) return primary;
+
+	const fbBase = pickFallbackBaseFile();
+	return makeFallback(fbBase, rel);
+}
+
+/* ---------- public API (thin wrappers) ---------- */
+
+/**
+ * @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) {
+	// short-circuits
+	if (rel.startsWith?.("file://")) return fileURLToPath(rel);
+	if (path.isAbsolute(rel)) return rel;
+
+	return resolveWith(
+		rel,
+		// makePrimary (PATH)
+		(baseFile, r) => path.resolve(path.dirname(baseFile), r),
+		// exists (PATH)
+		(candidate) => fs.existsSync(candidate),
+		// makeFallback (PATH)
+		(baseFile, r) => path.resolve(path.dirname(baseFile), r)
+	);
+}
+
+/**
+ * @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) {
+	// short-circuits
+	if (rel.startsWith?.("file://")) return rel;
+	if (path.isAbsolute(rel)) return pathToFileURL(rel).href;
+
+	return resolveWith(
+		rel,
+		// makePrimary (URL)
+		(baseFile, r) => new URL(r, pathToFileURL(baseFile)).href,
+		// exists (URL→check target path)
+		(href) => fs.existsSync(fileURLToPath(href)),
+		// makeFallback (URL)
+		(baseFile, r) => new URL(r, pathToFileURL(baseFile)).href
+	);
+}
+
+/**
+ * @typedef {object} CallSite
+ * @property {function(): string|undefined} getFileName
+ * @property {function(): number|undefined} getLineNumber
+ * @property {function(): string|undefined} getFunctionName
+ * @property {function(): string|undefined} getTypeName
+ * @property {function(): string|undefined} getMethodName
+ * @property {function(): string|undefined} getScriptNameOrSourceURL
+ * @property {function(): number|undefined} getColumnNumber
+ * @property {function(): boolean|undefined} isNative
+ * @property {function(): boolean|undefined} isEval
+ * @property {function(): boolean|undefined} isConstructor
+ * @property {function(): boolean|undefined} isToplevel
+ * @property {function(): boolean|undefined} isAsync
+ * @property {function(): boolean|undefined} isPromiseAll
+ * @property {function(): number|undefined} getPromiseIndex
+ *
+ * @description
+ * Minimal V8 CallSite object type for stack trace analysis. Only includes methods used in this module.
+ */

package/src/types/lib/resolve-from-caller.d.mts

@@ -0,0 +1,148 @@
+/**
+ * @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;
+};

package/src/types/wisp.d.mts

@@ -0,0 +1,54 @@
+/**
+ * Asynchronously loads JSON from a file, trying modern import with 'with', then 'assert', then fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {Function} [options.validate] - Validation function for the parsed JSON.
+ * @param {Function} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {Promise<*>} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON asynchronously with version-agnostic support.
+ * Attempts modern import syntax first, falls back to legacy assert, then fs.readFile.
+ *
+ * @example
+ * import { wisp } from '@cldmv/wisp';
+ * const data = await wisp('./config.json');
+ */
+export function wisp(input: string | URL, options?: {
+    base?: string | URL;
+    validate?: Function;
+    reviver?: Function;
+    type?: string;
+    fallback?: string | URL;
+}): Promise<any>;
+/**
+ * Synchronously loads JSON from a file using fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {Function} [options.validate] - Validation function for the parsed JSON.
+ * @param {Function} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {*} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON synchronously using fs.readFileSync.
+ *
+ * @example
+ * import { wispSync } from '@cldmv/wisp';
+ * const data = wispSync('./config.json');
+ */
+export function wispSync(input: string | URL, options?: {
+    base?: string | URL;
+    validate?: Function;
+    reviver?: Function;
+    type?: string;
+    fallback?: string | URL;
+}): any;
+export default wisp;

package/src/wisp.mjs

@@ -0,0 +1,187 @@
+/**
+ *	@Project: @cldmv/wisp
+ *	@Filename: /src/wisp.mjs
+ *	@Date: 2025-10-30 14:12:05 -07:00 (1761858725)
+ *	@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-30 14:59:15 -07:00 (1761861555)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2025 Catalyzed Motivation Inc. All rights reserved.
+ */
+
+/**
+ * @fileoverview Internal implementation of @cldmv/wisp. Not exported in package.json.
+ * @module @cldmv/wisp.src.wisp
+ * @internal
+ * @private
+ *
+ * @description
+ * This module provides the core implementation for version-agnostic JSON importing in Node.js.
+ * It includes functions to load JSON asynchronously and synchronously, with fallbacks for different Node versions.
+ *
+ * @example
+ * // Internal usage example
+ * import { wisp } from './src/wisp.mjs';
+ * const data = await wisp('./data.json');
+ */
+
+import fs from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveUrlFromCaller } from "./lib/resolve-from-caller.mjs";
+
+/**
+ * Deep clones a value using structuredClone if available, otherwise JSON.parse/stringify.
+ * @private
+ * @param {*} v - The value to clone.
+ * @returns {*} The cloned value.
+ */
+/**
+ * Deep clones a value using structuredClone if available, otherwise JSON.parse/stringify.
+ * @private
+ * @param {*} v - The value to clone.
+ * @returns {*} The cloned value.
+ */
+function deepClone(v) {
+	return typeof globalThis.structuredClone === "function" ? globalThis.structuredClone(v) : JSON.parse(JSON.stringify(v));
+}
+
+/**
+ * Asynchronously loads JSON from a file, trying modern import with 'with', then 'assert', then fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {(val: any) => void} [options.validate] - Validation function for the parsed JSON.
+ * @param {(this: any, key: string, value: any) => any} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {Promise<*>} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON asynchronously with version-agnostic support.
+ * Attempts modern import syntax first, falls back to legacy assert, then fs.readFile.
+ *
+ * @example
+ * import { wisp } from '@cldmv/wisp';
+ * const data = await wisp('./config.json');
+ */
+export async function wisp(input, options = {}) {
+	const { base, validate, reviver, type = "json", fallback } = options;
+	let url;
+	if (input instanceof URL) url = input;
+	else {
+		const s = String(input);
+		if (s.startsWith("file://")) url = new URL(s);
+		else if (path.isAbsolute(s)) url = pathToFileURL(s);
+		else if (base) url = new URL(s, new URL(base));
+		else url = new URL(resolveUrlFromCaller(s));
+	}
+
+	try {
+		const mod = await import(url.href, { with: { type } });
+		if (!reviver && !validate) return mod?.default ?? mod;
+		let val = deepClone(mod?.default ?? mod);
+		if (reviver) val = JSON.parse(JSON.stringify(val), reviver);
+		if (validate) {
+			try {
+				validate(val);
+			} catch (e) {
+				throw new Error(`@cldmv/wisp: ${e?.message ?? e}`);
+			}
+		}
+		return val;
+	} catch {}
+
+	try {
+		const mod = await import(url.href, { assert: { type } });
+		if (!reviver && !validate) return mod?.default ?? mod;
+		let val = deepClone(mod?.default ?? mod);
+		if (reviver) val = JSON.parse(JSON.stringify(val), reviver);
+		if (validate) {
+			try {
+				validate(val);
+			} catch (e) {
+				throw new Error(`@cldmv/wisp: ${e?.message ?? e}`);
+			}
+		}
+		return val;
+	} catch {}
+
+	if (type === "json") {
+		try {
+			const txt = await readFile(url, "utf8");
+			const val = deepClone(JSON.parse(txt, reviver));
+			if (validate) {
+				try {
+					validate(val);
+				} catch (e) {
+					throw new Error(`@cldmv/wisp: ${e?.message ?? e}`);
+				}
+			}
+			return val;
+		} catch (e) {
+			if (fallback) {
+				return wisp(fallback, options);
+			}
+			throw new Error(`@cldmv/wisp: Failed to load JSON file at ${url.href}: ${e.message}`);
+		}
+	}
+
+	throw new Error(`@cldmv/wisp: Unsupported type '${type}' or failed to load module at ${url.href}`);
+}
+
+/**
+ * Synchronously loads JSON from a file using fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {(val: any) => void} [options.validate] - Validation function for the parsed JSON.
+ * @param {(this: any, key: string, value: any) => any} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {*} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON synchronously using fs.readFileSync.
+ *
+ * @example
+ * import { wispSync } from '@cldmv/wisp';
+ * const data = wispSync('./config.json');
+ */
+export function wispSync(input, options = {}) {
+	const { base, validate, reviver, type = "json", fallback } = options;
+	let url;
+	if (input instanceof URL) url = input;
+	else {
+		const s = String(input);
+		if (s.startsWith("file://")) url = new URL(s);
+		else if (path.isAbsolute(s)) url = pathToFileURL(s);
+		else if (base) url = new URL(s, new URL(base));
+		else url = new URL(resolveUrlFromCaller(s));
+	}
+
+	try {
+		const txt = fs.readFileSync(url, "utf8");
+		const val = deepClone(JSON.parse(txt, reviver));
+		if (validate) {
+			try {
+				validate(val);
+			} catch (e) {
+				throw new Error(`@cldmv/wisp: ${e?.message ?? e}`);
+			}
+		}
+		return val;
+	} catch (e) {
+		if (fallback) {
+			return wispSync(fallback, options);
+		}
+		throw new Error(`@cldmv/wisp: Failed to load JSON file at ${url.href}: ${e.message}`);
+	}
+}
+
+export default wisp;

package/types/lib/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/lib/resolve-from-caller.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-from-caller.d.mts","sourceRoot":"","sources":["../../src/lib/resolve-from-caller.mjs"],"names":[],"mappings":"AAqFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/types/wisp.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Asynchronously loads JSON from a file, trying modern import with 'with', then 'assert', then fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {(val: any) => void} [options.validate] - Validation function for the parsed JSON.
+ * @param {(this: any, key: string, value: any) => any} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {Promise<*>} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON asynchronously with version-agnostic support.
+ * Attempts modern import syntax first, falls back to legacy assert, then fs.readFile.
+ *
+ * @example
+ * import { wisp } from '@cldmv/wisp';
+ * const data = await wisp('./config.json');
+ */
+export function wisp(input: string | URL, options?: {
+    base?: string | URL;
+    validate?: (val: any) => void;
+    reviver?: (this: any, key: string, value: any) => any;
+    type?: string;
+    fallback?: string | URL;
+}): Promise<any>;
+/**
+ * Synchronously loads JSON from a file using fs.
+ * @public
+ * @param {string|URL} input - The path or URL to the JSON file.
+ * @param {Object} [options] - Options object.
+ * @param {string|URL} [options.base] - Base URL for relative paths.
+ * @param {(val: any) => void} [options.validate] - Validation function for the parsed JSON.
+ * @param {(this: any, key: string, value: any) => any} [options.reviver] - Reviver function for JSON.parse.
+ * @param {string} [options.type='json'] - The type of the file being imported. Defaults to 'json'.
+ * @param {string|URL} [options.fallback] - Fallback path or URL if the primary file is missing.
+ * @returns {*} The parsed JSON value.
+ *
+ * @description
+ * Loads JSON synchronously using fs.readFileSync.
+ *
+ * @example
+ * import { wispSync } from '@cldmv/wisp';
+ * const data = wispSync('./config.json');
+ */
+export function wispSync(input: string | URL, options?: {
+    base?: string | URL;
+    validate?: (val: any) => void;
+    reviver?: (this: any, key: string, value: any) => any;
+    type?: string;
+    fallback?: string | URL;
+}): any;
+export default wisp;
+//# sourceMappingURL=wisp.d.mts.map

package/types/wisp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wisp.d.mts","sourceRoot":"","sources":["../src/wisp.mjs"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4BAjBW,MAAM,GAAC,GAAG,YAElB;IAA6B,IAAI,GAAzB,MAAM,GAAC,GAAG;IACmB,QAAQ,GAArC,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI;IACoC,OAAO,GAA7D,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG;IAC1B,IAAI,GAArB,MAAM;IACe,QAAQ,GAA7B,MAAM,GAAC,GAAG;CAClB,GAAU,OAAO,CAAC,GAAC,CAAC,CAyEtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,gCAhBW,MAAM,GAAC,GAAG,YAElB;IAA6B,IAAI,GAAzB,MAAM,GAAC,GAAG;IACmB,QAAQ,GAArC,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI;IACoC,OAAO,GAA7D,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG;IAC1B,IAAI,GAArB,MAAM;IACe,QAAQ,GAA7B,MAAM,GAAC,GAAG;CAClB,GAAU,GAAC,CAsCb"}