@crustjs/store 0.4.3 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @crustjs/store
 
-DX-first, typed persistence for CLI apps with config/data/state/cache separation
+Typed JSON persistence for CLI config, data, state, and cache files
 
 ## Install
 

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { JsonCompatible } from "@crustjs/utils/json";
 import { BaseValueType, ResolvePrimitive } from "@crustjs/utils/primitive";
 import { InferOutput, StandardSchema } from "@crustjs/utils/schema";
-//#region src/types.d.ts
 /** Supported type literals for store fields. */
 type ValueType = BaseValueType;
 /** Shared fields present on every store field definition. */
@@ -109,8 +108,10 @@ type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayF
 /** Record mapping field names to their definitions. */
 type FieldsDef = Record<string, FieldDef>;
 type JsonCompatibleFields<F extends FieldsDef> = { [K in keyof F]: F[K] extends {
-  schema: StandardSchema<unknown, infer Output>;
-} ? Exclude<Output, undefined> extends JsonCompatible<Exclude<Output, undefined>> ? F[K] : never : F[K]; };
+  schema: infer S extends StandardSchema;
+} ? Exclude<InferOutput<S>, undefined> extends JsonCompatible<Exclude<InferOutput<S>, undefined>> ? F[K] : F[K] & {
+  readonly FIX_JSON_OUTPUT: "store schema output must be JSON-compatible data (no Date, Map, bigint, or functions)";
+} : F[K]; };
 /**
  * Infer the resolved type for a single field definition.
  *
@@ -350,8 +351,6 @@ interface Store<TConfig> {
    */
   reset(): Promise<void>;
 }
-//#endregion
-//#region src/errors.d.ts
 /**
  * Contextual details attached to an `IO` error.
  *
@@ -464,8 +463,6 @@ export declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode>
    */
   is<T extends StoreErrorCode>(code: T): this is CrustStoreError<T>;
 }
-//#endregion
-//#region src/path.d.ts
 /**
  * Encapsulates runtime environment values needed for path resolution.
  *
@@ -584,8 +581,6 @@ export declare function stateDir(appName: string, env?: PlatformEnv): string;
  * ```
  */
 export declare function cacheDir(appName: string, env?: PlatformEnv): string;
-//#endregion
-//#region src/store.d.ts
 /**
  * Creates a typed async config store backed by a local JSON file.
  *
@@ -623,5 +618,4 @@ export declare function cacheDir(appName: string, env?: PlatformEnv): string;
  * ```
  */
 export declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
-//#endregion
 export type { CreateStoreOptions, FieldDef, FieldsDef, InferStoreConfig, PlatformEnv, Store, StoreAccess, StoreErrorCode, StorePermissionBits, StoreUpdater, StoreValidatorIssue, ValidationErrorDetails, ValueType };

package/dist/index.js

@@ -1,12 +1,12 @@
 import { homedir } from "node:os";
-import { dirname, join, win32 } from "node:path";
+import { dirname, join, posix, win32 } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { isJsonObject } from "@crustjs/utils/json";
 import { coerceBooleanString, tryCoerceNumber } from "@crustjs/utils/primitive";
 import { normalizeStandardIssues } from "@crustjs/utils/schema";
 import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { isErrnoException } from "@crustjs/utils/error";
-//#region src/errors.ts
+// src/errors.ts
 /**
 * A typed error thrown by `@crustjs/store` for path, parse, IO, and validation failures.
 *
@@ -56,8 +56,7 @@ var CrustStoreError = class extends Error {
 		return Object.is(this.code, code);
 	}
 };
-//#endregion
-//#region src/path.ts
+// src/path.ts
 /**
 * Returns the current runtime environment for path resolution.
 *
@@ -70,13 +69,19 @@ function getRuntimeEnv() {
 		homedir: homedir()
 	};
 }
-/** Validates a path input according to its role. */
-function validatePath(value, field) {
+function validateNonEmpty(value, field) {
 	if (!value.trim()) throw new CrustStoreError("PATH", `${field} must be a non-empty string`, { path: value });
-	if (field !== "dirPath" && (value.includes("/") || value.includes("\\"))) throw new CrustStoreError("PATH", `${field} must not contain path separators`, { path: value });
-	if (field === "dirPath" && !win32.isAbsolute(value)) throw new CrustStoreError("PATH", "dirPath must be an absolute path", { path: value });
+}
+/** Validates a single path segment: `appName` or the store `name`. */
+function validateSegment(value, field) {
+	validateNonEmpty(value, field);
+	if (value.includes("/") || value.includes("\\")) throw new CrustStoreError("PATH", `${field} must not contain path separators`, { path: value });
 	if (field === "name" && value.endsWith(".json")) throw new CrustStoreError("PATH", "name must not include the .json extension", { path: value });
-	if (field === "dirPath" && value.endsWith(".json")) throw new CrustStoreError("PATH", "dirPath must be a directory path, not a file path (should not end with .json)", { path: value });
+}
+function validateDirPath(value) {
+	validateNonEmpty(value, "dirPath");
+	if (!win32.isAbsolute(value)) throw new CrustStoreError("PATH", "dirPath must be an absolute path", { path: value });
+	if (value.endsWith(".json")) throw new CrustStoreError("PATH", "dirPath must be a directory path, not a file path (should not end with .json)", { path: value });
 }
 const DIRECTORY_CONFIG = {
 	config: {
@@ -109,11 +114,11 @@ const DIRECTORY_CONFIG = {
 	}
 };
 function resolvePlatformDir(kind, appName, env = getRuntimeEnv()) {
-	validatePath(appName, "appName");
+	validateSegment(appName, "appName");
 	const config = DIRECTORY_CONFIG[kind];
 	if (env.platform === "linux" || env.platform === "darwin") {
 		const configured = env.env[config.xdg];
-		const base = configured?.trim() ? configured : join(env.homedir, ...config.unixFallback);
+		const base = configured && posix.isAbsolute(configured) ? configured : join(env.homedir, ...config.unixFallback);
 		return join(base, appName);
 	}
 	if (env.platform === "win32") {
@@ -248,12 +253,11 @@ function cacheDir(appName, env) {
 * @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
 */
 function resolveStorePath(dirPath, name) {
-	validatePath(dirPath, "dirPath");
-	validatePath(name, "name");
+	validateDirPath(dirPath);
+	validateSegment(name, "name");
 	return join(dirPath, `${name}.json`);
 }
-//#endregion
-//#region src/merge.ts
+// src/merge.ts
 /**
 * Sets an own enumerable data property. Plain assignment would invoke the
 * inherited `__proto__` setter instead of storing a `__proto__` field.
@@ -287,14 +291,13 @@ function setDocumentValue(document, key, value) {
 function applyFieldDefaults(persisted, fields, pruneUnknown = true) {
 	const result = {};
 	for (const [key, def] of Object.entries(fields)) if (persisted && Object.hasOwn(persisted, key)) setDocumentValue(result, key, persisted[key]);
-	else if ("default" in def && def.default !== void 0) setDocumentValue(result, key, structuredClone(def.default));
+	else if (def.default !== void 0) setDocumentValue(result, key, structuredClone(def.default));
 	if (!pruneUnknown && persisted !== void 0) {
 		for (const [key, value] of Object.entries(persisted)) if (!Object.hasOwn(fields, key)) setDocumentValue(result, key, value);
 	}
 	return result;
 }
-//#endregion
-//#region src/persistence.ts
+// src/persistence.ts
 /**
 * Reads and parses a JSON config file from disk.
 *
@@ -312,7 +315,7 @@ async function readJson(filePath) {
 	try {
 		raw = await readFile(filePath, "utf-8");
 	} catch (err) {
-		if (isEnoent(err)) return;
+		if (isErrnoException(err) && err.code === "ENOENT") return;
 		throw new CrustStoreError("IO", `Failed to read config file: ${filePath}`, {
 			path: filePath,
 			operation: "read"
@@ -409,14 +412,7 @@ async function deleteJson(filePath) {
 		}, err);
 	}
 }
-/**
-* Checks whether a thrown error is a filesystem "file not found" error.
-*/
-function isEnoent(cause) {
-	return isErrnoException(cause) && cause.code === "ENOENT";
-}
-//#endregion
-//#region src/store.ts
+// src/store.ts
 function makeSchemaValidator(schema) {
 	return async (value) => {
 		const result = await schema["~standard"].validate(value);
@@ -440,6 +436,46 @@ function matchesDeclaredType(def, value) {
 function expectedTypeMessage(def) {
 	return `Expected ${def.type}${def.array === true ? "[]" : ""}`;
 }
+function coerceByType(value, type) {
+	if (type === "number" && typeof value === "string") return tryCoerceNumber(value) ?? value;
+	if (type === "boolean" && typeof value === "string") return coerceBooleanString(value);
+	return value;
+}
+/**
+* Re-validates a changed transform output once. This catches cross-type
+* transforms like `z.string().transform(Number)` whose output would fail the
+* schema on the next read.
+*
+* @returns The issue message when the next read would see a different value.
+*/
+async function readUnstableTransformMessage(validator, transformed) {
+	let recheck;
+	try {
+		recheck = await validator(transformed);
+	} catch (cause) {
+		return `read-unstable transform: ${cause instanceof Error ? cause.message : "re-validation failed"}`;
+	}
+	if (recheck !== void 0 && (!isFieldValueResult(recheck) || !isDeepStrictEqual(recheck.value, transformed))) return "read-unstable transform: output would be transformed again on re-read";
+}
+/**
+* Mutations promise to return exactly what the next read() sees, so any
+* value JSON serialization would alter (NaN/Infinity → null, -0 → 0,
+* array holes → null, dropped undefined object properties) is rejected.
+*/
+function jsonInstabilityIssues(document) {
+	const issues = [];
+	for (const [key, value] of Object.entries(document)) {
+		if (value === void 0) continue;
+		try {
+			if (isDeepStrictEqual(JSON.parse(JSON.stringify(value)), value)) continue;
+		} catch {}
+		issues.push({
+			message: "value does not survive JSON serialization (cycles, NaN, Infinity, -0, sparse arrays, or undefined properties)",
+			path: key
+		});
+	}
+	return issues;
+}
 /**
 * Creates a typed async config store backed by a local JSON file.
 *
@@ -484,7 +520,6 @@ function createStore(options) {
 		validators.set(key, makeSchemaValidator(def.schema));
 	} else if (def.validate !== void 0) validators.set(key, def.validate);
 	const filePath = resolveStorePath(dirPath, name);
-	const shouldPrune = pruneUnknown ?? true;
 	const writeOptions = access === "private" ? {
 		fileMode: 384,
 		directoryMode: 448
@@ -492,11 +527,6 @@ function createStore(options) {
 		fileMode: access.file,
 		directoryMode: access.directory
 	};
-	function coerceByType(value, type) {
-		if (type === "number" && typeof value === "string") return tryCoerceNumber(value) ?? value;
-		if (type === "boolean" && typeof value === "string") return coerceBooleanString(value);
-		return value;
-	}
 	function normalizeStateTypes(state) {
 		const normalized = { ...state };
 		for (const [key, def] of Object.entries(fields)) {
@@ -561,20 +591,10 @@ function createStore(options) {
 					continue;
 				}
 				if (!isDeepStrictEqual(transformed, value)) {
-					let recheck;
-					try {
-						recheck = await validator(transformed);
-					} catch (cause) {
-						const message = cause instanceof Error ? cause.message : "re-validation failed";
+					const unstable = await readUnstableTransformMessage(validator, transformed);
+					if (unstable !== void 0) {
 						issues.push({
-							message: `read-unstable transform: ${message}`,
-							path: key
-						});
-						continue;
-					}
-					if (recheck !== void 0 && (!isFieldValueResult(recheck) || !isDeepStrictEqual(recheck.value, transformed))) {
-						issues.push({
-							message: `read-unstable transform: output would be transformed again on re-read`,
+							message: unstable,
 							path: key
 						});
 						continue;
@@ -583,16 +603,7 @@ function createStore(options) {
 				}
 			}
 		}
-		if (operation !== "read") for (const [key, value] of Object.entries(mutableState)) {
-			if (value === void 0) continue;
-			try {
-				if (isDeepStrictEqual(JSON.parse(JSON.stringify(value)), value)) continue;
-			} catch {}
-			issues.push({
-				message: "value does not survive JSON serialization (cycles, NaN, Infinity, -0, sparse arrays, or undefined properties)",
-				path: key
-			});
-		}
+		if (operation !== "read") issues.push(...jsonInstabilityIssues(mutableState));
 		if (issues.length > 0) throw new CrustStoreError("VALIDATION", `Store validation failed (${operation})\n${issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`, {
 			operation,
 			issues
@@ -602,7 +613,7 @@ function createStore(options) {
 		const persisted = await readJson(filePath);
 		const persistedObject = persisted !== void 0 && isJsonObject(persisted) ? persisted : void 0;
 		if (persisted !== void 0 && persistedObject === void 0) throw new CrustStoreError("PARSE", `Expected a JSON object in config file: ${filePath}`, { path: filePath });
-		return normalizeStateTypes(applyFieldDefaults(persistedObject, fields, shouldPrune));
+		return normalizeStateTypes(applyFieldDefaults(persistedObject, fields, pruneUnknown));
 	}
 	async function read() {
 		const document = await readRaw();
@@ -638,5 +649,4 @@ function createStore(options) {
 		reset
 	};
 }
-//#endregion
 export { CrustStoreError, cacheDir, configDir, createStore, dataDir, stateDir };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crustjs/store",
-  "version": "0.4.3",
-  "description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
+  "version": "0.5.0",
+  "description": "Typed JSON persistence for CLI config, data, state, and cache files",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -40,12 +40,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@crustjs/utils": "^0.2.1"
+    "@crustjs/utils": "^0.3.0"
   },
   "devDependencies": {
     "@crustjs/config": "0.0.0",
-    "zod": "^4.6.5",
-    "vite-plus": "1.0.0"
+    "zod": "^4.6.7",
+    "vite-plus": "1.4.0"
   },
   "peerDependencies": {
     "typescript": "^7.0.0"
@@ -57,8 +57,7 @@
   },
   "engines": {
     "bun": ">=1.4.0",
-    "node": ">=24",
-    "deno": ">=2.8"
+    "node": ">=24"
   },
   "scripts": {
     "build": "vp run build:task",