@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

npm install @cldmv/wisp

Usage

ESM (Modern)

import { wisp, wispSync } from "@cldmv/wisp";

// Asynchronous loading
const config = await wisp("./config.json");

// Synchronous loading
const data = wispSync("./data.json");

CJS (CommonJS)

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

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

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:

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.