@theholocron/datapad 3.64.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+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,101 @@
+# `@theholocron/datapad`
+
+Generic config-file loading for Holocron. Discover `<name>.config.*`, load
+it (JSON / JS / TS / ESM / CJS — typed configs via [`tsx`](https://tsx.is),
+no build step), layer a dedicated file over a key of a parent file,
+deep-merge, and hand back a plain object.
+
+Holocron-agnostic: no schema, no validation, no defaults. Consumers
+(`@theholocron/cli` for `holocron.config.*`, `@theholocron/astromech` for
+`astromech.config.*`) build those on top.
+
+> A datapad is a handheld device for reading and holding data. This reads
+> and holds config files.
+
+## Installation
+
+```sh
+pnpm add @theholocron/datapad
+```
+
+## Usage
+
+```ts
+import { loadConfigFile, loadLayered, mergeConfig, createDefineConfig } from "@theholocron/datapad";
+
+// one file: holocron.config.{ts,js,mjs,cjs,json}
+const found = await loadConfigFile<MyConfig>({ cwd, name: "holocron" });
+// → { config, filepath } | null
+
+// a dedicated file layered over the `tasks` key of a parent file
+const layered = await loadLayered<TasksConfig>({
+  cwd,
+  name: "astromech",
+  fallback: { file: "holocron", key: "tasks" },
+});
+// → { config, filepath, sources } | null   (dedicated wins on conflict)
+
+const merged = mergeConfig(defaults, layered?.config); // vite-style deep merge
+
+// a typed identity defineConfig for a specific shape
+export const defineConfig = createDefineConfig<TasksConfig>();
+```
+
+## API
+
+### `loadConfigFile<T>({ cwd, name, extensions? })`
+
+Loads the first `<name>.config.<ext>` found in `cwd`. Probe order is
+**TS-first** — `.ts` → `.js` → `.mjs` → `.cjs` → `.json` — overridable via
+`extensions`. Returns `{ config, filepath } | null`. `null` means "no such
+file"; a file that exists but cannot be parsed / loaded / has no default
+export throws `ConfigFileError`.
+
+### `loadLayered<T>({ cwd, name, fallback?, extensions? })`
+
+`<name>.config.*` layered over the `[fallback.key]` of
+`<fallback.file>.config.*`. Either, both, or neither may be present; the
+dedicated file wins on conflict (`vitest`-over-`vite`). Returns
+`{ config, filepath, sources } | null` — `sources` lists the absolute
+paths actually merged, lowest priority first.
+
+### `mergeConfig<T>(base, override)`
+
+Deep-merge, `vite`-style: plain objects merge recursively, arrays
+concatenate (`base` first), `undefined` in `override` is skipped, every
+other `override` value replaces `base`. Neither input is mutated.
+
+### `createDefineConfig<T>()`
+
+Returns a typed identity function — call once per config shape and
+re-export it so config files get autocomplete with zero runtime cost.
+
+### `ConfigFileError`
+
+Thrown when a file is found but unusable. Carries the offending
+`filepath`. "Not found" is `null`, never an error.
+
+## TypeScript configs
+
+`.ts` files load through `tsx`'s ESM loader, registered once per process
+on first use. A single run may load several TS configs (`loadLayered`
+reads a dedicated file _and_ a parent file), so the persistent
+`register()` is used rather than the one-off `tsImport()`.
+
+## Development
+
+| Script               | Description             |
+| -------------------- | ----------------------- |
+| `pnpm build`         | Bundle with tsdown      |
+| `pnpm test`          | Run the vitest suite    |
+| `pnpm test:coverage` | Run tests with coverage |
+| `pnpm typecheck`     | `tsc --noEmit`          |
+| `pnpm lint`          | ESLint                  |
+
+## Releases
+
+Automated via semantic-release. See [CHANGELOG.md](../../CHANGELOG.md).
+
+## Documentation
+
+<https://theholocron.github.io/holocron/>

package/dist/index.d.mts

@@ -0,0 +1,101 @@
+//#region src/define.d.ts
+/**
+ * Build a typed identity `defineConfig` for a specific config shape.
+ *
+ * Each consumer (`@theholocron/cli`, `@theholocron/astromech`) calls this
+ * once with its own config type and re-exports the result, so config
+ * files get autocomplete and type-checking with no runtime cost:
+ *
+ * ```ts
+ * // @theholocron/astromech/config
+ * export const defineConfig = createDefineConfig<TasksConfig>();
+ * ```
+ */
+declare function createDefineConfig<T>(): <C extends T>(config: C) => C;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Thrown when a config file is found but cannot be loaded — malformed
+ * JSON, a syntax error in a `.ts` / `.js` module, or no usable default
+ * export. "Not found" is never an error: {@link loadConfigFile} returns
+ * `null` for that.
+ */
+declare class ConfigFileError extends Error {
+  /** Absolute path of the offending file, when known. */
+  readonly filepath?: string | undefined;
+  name: string;
+  constructor(message: string,
+  /** Absolute path of the offending file, when known. */
+  filepath?: string | undefined);
+}
+//#endregion
+//#region src/load.d.ts
+/**
+ * Discover and load `<name>.config.*` files. Holocron-agnostic — no
+ * schema, no validation, no defaults. Consumers layer those on top.
+ *
+ * Probe order is **TS-first**: `.ts` → `.js` → `.mjs` → `.cjs` → `.json`.
+ * TS is loaded through `tsx`'s `tsImport` (a runtime dependency) so a
+ * typed `defineConfig` file works with no build step.
+ */
+/** Default extension probe order, highest priority first. */
+declare const DEFAULT_EXTENSIONS: readonly ["ts", "js", "mjs", "cjs", "json"];
+interface LoadConfigFileOptions {
+  /** Directory to look in. */
+  cwd: string;
+  /** Base name — `"holocron"` resolves `holocron.config.{ts,js,mjs,cjs,json}`. */
+  name: string;
+  /** Override the extension probe order. */
+  extensions?: readonly string[];
+}
+interface Loaded<T> {
+  config: T;
+  /** Absolute path of the file the value came from. */
+  filepath: string;
+}
+/**
+ * Load the first `<name>.config.<ext>` that exists in `cwd`. Returns
+ * `null` when none is present; throws {@link ConfigFileError} when a file
+ * exists but cannot be loaded.
+ */
+declare function loadConfigFile<T>(opts: LoadConfigFileOptions): Promise<Loaded<T> | null>;
+interface LoadLayeredOptions extends LoadConfigFileOptions {
+  /**
+   * When no dedicated `<name>.config.*` exists — or in addition to it —
+   * read `<file>.config.*` and take its `[key]`. The dedicated file (if
+   * any) is merged on top.
+   */
+  fallback?: {
+    file: string;
+    key: string;
+  };
+}
+interface LayeredResult<T> {
+  config: T;
+  /** The dedicated file path if present, else the fallback file path, else `null`. */
+  filepath: string | null;
+  /** Absolute paths actually merged, lowest priority first. */
+  sources: string[];
+}
+/**
+ * `<name>.config.*` layered over the `[fallback.key]` of
+ * `<fallback.file>.config.*`. Either, both, or neither may be present;
+ * the dedicated file wins on conflict (vitest-over-vite). Returns `null`
+ * when neither source resolves.
+ */
+declare function loadLayered<T>(opts: LoadLayeredOptions): Promise<LayeredResult<T> | null>;
+//#endregion
+//#region src/merge.d.ts
+/**
+ * Deep-merge two config objects, `vite`-style:
+ *
+ * - plain objects merge recursively
+ * - arrays concatenate (`base` first, then `override`)
+ * - an `undefined` value in `override` is skipped (keeps `base`)
+ * - every other `override` value replaces `base`
+ *
+ * Neither input is mutated.
+ */
+declare function mergeConfig<T>(base: T, override: unknown): T;
+//#endregion
+export { ConfigFileError, DEFAULT_EXTENSIONS, type LayeredResult, type LoadConfigFileOptions, type LoadLayeredOptions, type Loaded, createDefineConfig, loadConfigFile, loadLayered, mergeConfig };

package/dist/index.mjs

@@ -0,0 +1,191 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/define.ts
+/**
+* Build a typed identity `defineConfig` for a specific config shape.
+*
+* Each consumer (`@theholocron/cli`, `@theholocron/astromech`) calls this
+* once with its own config type and re-exports the result, so config
+* files get autocomplete and type-checking with no runtime cost:
+*
+* ```ts
+* // @theholocron/astromech/config
+* export const defineConfig = createDefineConfig<TasksConfig>();
+* ```
+*/
+function createDefineConfig() {
+	return (config) => config;
+}
+//#endregion
+//#region src/errors.ts
+/**
+* Thrown when a config file is found but cannot be loaded — malformed
+* JSON, a syntax error in a `.ts` / `.js` module, or no usable default
+* export. "Not found" is never an error: {@link loadConfigFile} returns
+* `null` for that.
+*/
+var ConfigFileError = class extends Error {
+	filepath;
+	name = "ConfigFileError";
+	constructor(message, filepath) {
+		super(message);
+		this.filepath = filepath;
+	}
+};
+//#endregion
+//#region src/merge.ts
+/**
+* Deep-merge two config objects, `vite`-style:
+*
+* - plain objects merge recursively
+* - arrays concatenate (`base` first, then `override`)
+* - an `undefined` value in `override` is skipped (keeps `base`)
+* - every other `override` value replaces `base`
+*
+* Neither input is mutated.
+*/
+function mergeConfig(base, override) {
+	if (!isPlainObject(base) || !isPlainObject(override)) return override === void 0 ? base : override;
+	const out = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		if (value === void 0) continue;
+		const prev = out[key];
+		if (Array.isArray(prev) && Array.isArray(value)) out[key] = [...prev, ...value];
+		else if (isPlainObject(prev) && isPlainObject(value)) out[key] = mergeConfig(prev, value);
+		else out[key] = value;
+	}
+	return out;
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region src/load.ts
+/**
+* Discover and load `<name>.config.*` files. Holocron-agnostic — no
+* schema, no validation, no defaults. Consumers layer those on top.
+*
+* Probe order is **TS-first**: `.ts` → `.js` → `.mjs` → `.cjs` → `.json`.
+* TS is loaded through `tsx`'s `tsImport` (a runtime dependency) so a
+* typed `defineConfig` file works with no build step.
+*/
+/** Default extension probe order, highest priority first. */
+const DEFAULT_EXTENSIONS = [
+	"ts",
+	"js",
+	"mjs",
+	"cjs",
+	"json"
+];
+/**
+* Load the first `<name>.config.<ext>` that exists in `cwd`. Returns
+* `null` when none is present; throws {@link ConfigFileError} when a file
+* exists but cannot be loaded.
+*/
+async function loadConfigFile(opts) {
+	const extensions = opts.extensions ?? DEFAULT_EXTENSIONS;
+	for (const ext of extensions) {
+		const filepath = join(opts.cwd, `${opts.name}.config.${ext}`);
+		if (!await isFile(filepath)) continue;
+		return {
+			config: await loadFile(filepath, ext),
+			filepath
+		};
+	}
+	return null;
+}
+/**
+* `<name>.config.*` layered over the `[fallback.key]` of
+* `<fallback.file>.config.*`. Either, both, or neither may be present;
+* the dedicated file wins on conflict (vitest-over-vite). Returns `null`
+* when neither source resolves.
+*/
+async function loadLayered(opts) {
+	const dedicated = await loadConfigFile(opts);
+	let base;
+	let baseFile = null;
+	if (opts.fallback) {
+		const parent = await loadConfigFile({
+			cwd: opts.cwd,
+			name: opts.fallback.file,
+			extensions: opts.extensions
+		});
+		if (parent && parent.config[opts.fallback.key] !== void 0) {
+			base = parent.config[opts.fallback.key];
+			baseFile = parent.filepath;
+		}
+	}
+	if (!dedicated && base === void 0) return null;
+	const config = mergeConfig(base, dedicated?.config);
+	const sources = [baseFile, dedicated?.filepath ?? null].filter((s) => s !== null);
+	return {
+		config,
+		filepath: dedicated?.filepath ?? baseFile,
+		sources
+	};
+}
+async function loadFile(filepath, ext) {
+	if (ext === "json") return loadJson(filepath);
+	return extractDefault(filepath, ext === "ts" ? await importTs(filepath) : await importModule(filepath));
+}
+async function loadJson(filepath) {
+	const text = await readFile(filepath, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		throw new ConfigFileError(`${filepath} is not valid JSON: ${message(err)}`, filepath);
+	}
+}
+async function importModule(filepath) {
+	try {
+		return await import(pathToFileURL(filepath).href);
+	} catch (err) {
+		throw new ConfigFileError(`could not load ${filepath}: ${message(err)}`, filepath);
+	}
+}
+let tsRegistered;
+async function registerTsx() {
+	const { register } = await import("tsx/esm/api");
+	register();
+}
+/**
+* Load a `.ts` config. `tsx`'s ESM loader is registered once per process
+* (lazily — only when a `.ts` config is actually loaded). `register()` is
+* used over `tsImport()` because a single run may load several TS configs
+* (`loadLayered` reads a dedicated file *and* a parent file) and
+* `tsImport`'s one-off register/unregister cycle is not reentrant.
+*/
+async function importTs(filepath) {
+	tsRegistered ??= registerTsx();
+	await tsRegistered;
+	try {
+		return await import(pathToFileURL(filepath).href);
+	} catch (err) {
+		throw new ConfigFileError(`could not load ${filepath}: ${message(err)}`, filepath);
+	}
+}
+/**
+* Unwrap `export default`. `tsx` CJS-transforms `export default x` into
+* `exports.default = x`, which dynamic import wraps as
+* `{ default: { __esModule: true, default: x } }` — strip the extra layer
+* when present so ESM and CJS outputs both resolve.
+*/
+function extractDefault(filepath, mod) {
+	const outer = mod.default;
+	const raw = outer?.__esModule === true ? outer.default : outer;
+	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`, filepath);
+	return raw;
+}
+async function isFile(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+const message = (err) => err instanceof Error ? err.message : String(err);
+//#endregion
+export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadLayered, mergeConfig };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@theholocron/datapad",
+  "version": "3.64.0",
+  "description": "Generic config-file loading for Holocron — discover, load (JSON/JS/TS/ESM/CJS), and merge <name>.config.* files with a typed defineConfig.",
+  "keywords": [
+    "config",
+    "config-loader",
+    "defineconfig",
+    "holocron",
+    "theholocron",
+    "typescript"
+  ],
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/datapad#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/datapad"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "tsx": "4.23.12"
+  },
+  "devDependencies": {
+    "@theholocron/eslint-config": "^7.32.1",
+    "@theholocron/tsconfig": "^7.32.1",
+    "@theholocron/tsdown-config": "^7.32.1",
+    "@theholocron/vitest-config": "^7.32.1",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.11.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}