@crustjs/store 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ DX-first, typed persistence for CLI apps with config/data/state/cache separation
 ## Install
 
 ```sh
-bun add @crustjs/store
+npm install @crustjs/store
 ```
 
 ## Documentation

package/dist/index.d.ts

@@ -101,7 +101,7 @@ interface FieldDefBase<V> {
    *   persistence and is re-validated once to catch read-unstable
    *   transforms. Outputs outside the declared type are rejected with
    *   `VALIDATION`. On `read`, the transformed value is discarded —
-   *   reads always return the on-disk value verbatim.
+   *   core fields return their defaulted, type-coerced input value.
    * - Throwing an error — the value is rejected; the error message is
    *   captured as a validation issue with the field name as `path`.
    *
@@ -315,11 +315,11 @@ interface CreateStoreOptions<F extends FieldsDef> {
   access?: StoreAccess;
 }
 /**
- * Receives the current config with defaults and core coercion applied,
- * but without full field validation, and returns an updated config.
- * Persisted values may not yet satisfy their declared types or validators.
+ * Receives the validated current config, including defaults, core coercion,
+ * and schema output, and returns an updated config. Invalid current state
+ * rejects before this callback runs; use `write` or `patch` to initialize or repair it.
  *
- * Used by {@link Store.update}, which validates the result before persistence.
+ * Used by {@link Store.update}, which also validates the result before persistence.
  *
  * @example
  * ```ts
@@ -360,7 +360,8 @@ type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
  */
 interface Store<TConfig> {
   /**
-   * Reads the persisted config, applying field defaults for missing keys.
+   * Reads the persisted config, applying field defaults for missing keys and
+   * returning successful schema output (including transforms) without writing.
    *
    * Always returns a value — fields with defaults are guaranteed present,
    * fields without defaults may be `undefined`.
@@ -387,8 +388,9 @@ interface Store<TConfig> {
    */
   write(config: NoInfer<TConfig>): Promise<TConfig>;
   /**
-   * Reads current config with defaults and core coercion applied, without
-   * full field validation. Applies the updater, validates the result, and persists.
+   * Reads and validates current config before calling the updater. Applies
+   * the updater, validates the result, and persists. Invalid current state
+   * rejects before the callback runs; use `write` or `patch` to initialize or repair.
    *
    * The final file replacement is atomic, but the read-modify-write sequence
    * is not serialized, even within one process. Await mutations sequentially
@@ -405,9 +407,11 @@ interface Store<TConfig> {
    * Applies a partial update to the current config and persists.
    *
    * Only the provided keys are updated; everything else is preserved.
-   * Like {@link Store.update}, the current config has defaults and core coercion
-   * applied but has not undergone full field validation. The merged result is
-   * validated before persistence. Await mutations sequentially to avoid lost updates.
+   * Unlike {@link Store.update}, the current config has core defaults and coercion
+   * applied but has not undergone full field validation, allowing repairs. The
+   * merged result is validated before persistence. Explicit `undefined` is rejected
+   * for defaulted core fields; optional core fields and schema-owned optionality
+   * remain supported. Await mutations sequentially to avoid lost updates.
    *
    * @param partial - A partial subset of the config to merge in.
    * @returns The persisted config, including schema transformations.

package/dist/index.js

@@ -602,7 +602,13 @@ function createStore(options) {
 		const issues = [];
 		for (const [key, def] of Object.entries(fields)) {
 			const value = mutableState[key];
-			if (value === void 0 && def.schema === void 0) continue;
+			if (value === void 0 && def.schema === void 0) {
+				if (def.default !== void 0) issues.push({
+					message: expectedTypeMessage(def),
+					path: key
+				});
+				continue;
+			}
 			if (value !== void 0 && def.schema === void 0 && !matchesDeclaredType(def, value)) {
 				issues.push({
 					message: expectedTypeMessage(def),
@@ -627,7 +633,7 @@ function createStore(options) {
 			if (isFieldValueResult(result)) {
 				const transformed = result.value;
 				if (operation === "read") {
-					if (value === void 0) mutableState[key] = transformed;
+					if (def.schema !== void 0) mutableState[key] = transformed;
 					continue;
 				}
 				if (def.schema === void 0 && !matchesDeclaredType(def, transformed)) {
@@ -662,8 +668,11 @@ function createStore(options) {
 		}
 		if (operation !== "read") for (const [key, value] of Object.entries(mutableState)) {
 			if (value === void 0) continue;
-			if (!isDeepStrictEqual(JSON.parse(JSON.stringify(value)), value)) issues.push({
-				message: "value does not survive JSON serialization (NaN, Infinity, -0, sparse arrays, or undefined properties)",
+			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
 			});
 		}
@@ -672,45 +681,34 @@ function createStore(options) {
 			issues
 		});
 	}
-	async function readRaw(materializeSchemaDefaults = false) {
+	async function readRaw() {
 		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 });
-		const merged = applyFieldDefaults(persistedObject, fields, shouldPrune);
-		if (materializeSchemaDefaults) for (const [key, def] of Object.entries(fields)) {
-			if (merged[key] !== void 0 || def.schema === void 0) continue;
-			try {
-				const result = await validators.get(key)?.(void 0);
-				if (result !== void 0 && isFieldValueResult(result)) merged[key] = result.value;
-			} catch {}
-		}
-		return normalizeStateTypes(merged);
+		return normalizeStateTypes(applyFieldDefaults(persistedObject, fields, shouldPrune));
 	}
 	async function read() {
 		const document = await readRaw();
 		await runFieldValidators(document, "read");
 		return document;
 	}
-	async function write(config) {
-		const normalized = normalizeStateTypes({ ...config });
-		await runFieldValidators(normalized, "write");
+	async function persist(document, operation) {
+		const normalized = normalizeStateTypes(document);
+		await runFieldValidators(normalized, operation);
 		await writeJson(filePath, normalized, writeOptions);
 		return normalized;
 	}
+	async function write(config) {
+		return persist({ ...config }, "write");
+	}
 	async function update(updater) {
-		const normalized = normalizeStateTypes({ ...updater(await readRaw(true)) });
-		await runFieldValidators(normalized, "update");
-		await writeJson(filePath, normalized, writeOptions);
-		return normalized;
+		return persist({ ...updater(await read()) }, "update");
 	}
 	async function patch(partial) {
-		const normalized = normalizeStateTypes({
-			...await readRaw(true),
+		return persist({
+			...await readRaw(),
 			...partial
-		});
-		await runFieldValidators(normalized, "patch");
-		await writeJson(filePath, normalized, writeOptions);
-		return normalized;
+		}, "patch");
 	}
 	async function reset() {
 		await deleteJson(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/store",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"sideEffects": false,
@@ -62,7 +62,7 @@
 		}
 	},
 	"engines": {
-		"bun": ">=1.3.14",
+		"bun": ">=1.4.0",
 		"node": ">=22",
 		"deno": ">=2.8"
 	}