@crustjs/store 0.4.2 → 0.4.4

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.js

@@ -70,13 +70,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,7 +115,7 @@ 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];
@@ -248,8 +254,8 @@ 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
@@ -287,7 +293,7 @@ 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);
 	}
@@ -312,7 +318,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,12 +415,6 @@ 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
 function makeSchemaValidator(schema) {
@@ -440,6 +440,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 +524,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 +531,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 +595,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 +607,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 +617,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();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crustjs/store",
-  "version": "0.4.2",
-  "description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
+  "version": "0.4.4",
+  "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.0"
+    "@crustjs/utils": "^0.2.2"
   },
   "devDependencies": {
     "@crustjs/config": "0.0.0",
-    "zod": "^4.5.4",
-    "vite-plus": "1.0.0-rc.0"
+    "zod": "^4.6.5",
+    "vite-plus": "1.0.0"
   },
   "peerDependencies": {
     "typescript": "^7.0.0"
@@ -57,7 +57,7 @@
   },
   "engines": {
     "bun": ">=1.4.0",
-    "node": ">=22",
+    "node": ">=24",
     "deno": ">=2.8"
   },
   "scripts": {