@crustjs/store 0.3.1 → 0.4.1

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

@@ -1,84 +1,6 @@
-//#region ../utils/src/json.d.ts
-/** Any value representable in a JSON document. */
-type JsonValue = string | number | boolean | null | readonly JsonValue[] | JsonObject;
-interface JsonObject {
-  [key: string]: JsonValue;
-}
-/** Preserve a type when all of its properties are recursively JSON-compatible. */
-type JsonCompatible<T> = T extends JsonValue ? T : T extends ((...arguments_: never[]) => void) ? never : T extends readonly unknown[] ? { [K in keyof T]: JsonCompatible<T[K]>; } : T extends object ? { [K in keyof T]: JsonCompatible<T[K]>; } : never;
-//#endregion
-//#region ../utils/src/primitive.d.ts
-/** Supported primitive type literals shared by Crust packages. */
-type BaseValueType = "string" | "number" | "boolean";
-/**
- * Resolves a primitive type literal to its corresponding TypeScript type.
- *
- * @example
- * ```ts
- * type Port = ResolvePrimitive<"number">;
- * //   ^? number
- * ```
- */
-type ResolvePrimitive<T extends BaseValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
-//#endregion
-//#region ../utils/src/schema.d.ts
-/** The Standard Typed types interface. */
-interface StandardSchemaTypes<Input = unknown, Output = Input> {
-  /** The input type of the schema. */
-  readonly input: Input;
-  /** The output type of the schema. */
-  readonly output: Output;
-}
-/** The result interface if validation succeeds. */
-interface StandardSchemaSuccessResult<Output> {
-  /** The typed output value. */
-  readonly value: Output;
-  /** A falsy value for `issues` indicates success. */
-  readonly issues?: undefined;
-}
-/** The result interface if validation fails. */
-interface StandardSchemaFailureResult {
-  /** The issues of failed validation. */
-  readonly issues: ReadonlyArray<StandardSchemaIssue>;
-}
-/** The result interface of the validate function. */
-type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
-/** The issue interface of the failure output. */
-interface StandardSchemaIssue {
-  /** The error message of the issue. */
-  readonly message: string;
-  /** The path of the issue, if any. */
-  readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
-}
-/** The path segment interface of the issue. */
-interface StandardSchemaPathSegment {
-  /** The key representing a path segment. */
-  readonly key: PropertyKey;
-}
-/** The Standard Schema properties interface. */
-interface StandardSchemaProps<Input = unknown, Output = Input> {
-  /** The version number of the standard. */
-  readonly version: 1;
-  /** The vendor name of the schema library. */
-  readonly vendor: string;
-  /** Inferred types associated with the schema. */
-  readonly types?: StandardSchemaTypes<Input, Output> | undefined;
-  /** Validates unknown input values. */
-  readonly validate: (value: StandardSchemaTypes["input"]) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-}
-/**
- * A Standard Schema-compatible schema object.
- *
- * Any schema library implementing the Standard Schema v1 spec
- * (Zod, Effect, Valibot, ArkType, etc.) produces objects matching this type.
- */
-type StandardSchema<Input = unknown, Output = Input> = {
-  /** The Standard Schema properties. */
-  readonly "~standard": StandardSchemaProps<Input, Output>;
-};
-/** Infer the output type produced by a Standard Schema on success. */
-type InferOutput<S extends StandardSchema> = NonNullable<S["~standard"]["types"]>["output"];
-//#endregion
+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;
@@ -101,7 +23,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 +237,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 +282,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 +310,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 +329,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

@@ -1,7 +1,11 @@
 import { homedir } from "node:os";
 import { dirname, join, 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
 /**
 * A typed error thrown by `@crustjs/store` for path, parse, IO, and validation failures.
@@ -249,103 +253,6 @@ function resolveStorePath(dirPath, name) {
 	return join(dirPath, `${name}.json`);
 }
 //#endregion
-//#region ../utils/src/json.ts
-/** Narrow a JSON document root to an object (not array/scalar/null). */
-function isJsonObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region ../utils/src/primitive.ts
-/**
-* Attempts to coerce a string to a number, returning `undefined` only when the
-* result is `NaN`. Callers decide whether `undefined` means throw or fallback.
-*
-* @example
-* ```ts
-* tryCoerceNumber("42"); // 42
-* tryCoerceNumber("abc"); // undefined
-* tryCoerceNumber(""); // 0
-* ```
-*/
-function tryCoerceNumber(raw) {
-	const num = Number(raw);
-	return Number.isNaN(num) ? void 0 : num;
-}
-/**
-* Coerces Crust boolean strings using the existing strict truthy spellings.
-*
-* @example
-* ```ts
-* coerceBooleanString("true"); // true
-* coerceBooleanString("1"); // true
-* coerceBooleanString("false"); // false
-* ```
-*/
-function coerceBooleanString(raw) {
-	return raw === "true" || raw === "1";
-}
-//#endregion
-//#region ../utils/src/schema.ts
-/**
-* Format an issue path into a dot-path string.
-*
-* - Numeric keys (array indexes) are rendered with bracket notation: `items[0]`
-* - String/symbol keys are joined with dots: `flags.verbose`
-* - An empty path array produces an empty string (root-level issue)
-*
-* @example
-* ```ts
-* formatPath(["flags", "verbose"]);
-* // => "flags.verbose"
-*
-* formatPath(["args", 0]);
-* // => "args[0]"
-*
-* formatPath([]);
-* // => ""
-* ```
-*/
-function isNumericPathSegment(segment) {
-	return typeof segment === "number";
-}
-function formatPath(path) {
-	return path.map((segment, index) => isNumericPathSegment(segment) ? `[${segment}]` : index > 0 ? `.${String(segment)}` : String(segment)).join("");
-}
-/**
-* Normalize a Standard Schema issue path to an array of `PropertyKey`.
-*
-* Standard Schema paths contain either bare `PropertyKey` values or
-* `{ key: PropertyKey }` segment objects; both forms are flattened to
-* plain `PropertyKey`. Returns an empty array for a root-level issue
-* (`undefined`).
-*/
-function isStandardPathSegment(segment) {
-	return typeof segment === "object" && segment !== null && "key" in segment;
-}
-function normalizeStandardPath(path) {
-	if (!path) return [];
-	return path.map((segment) => isStandardPathSegment(segment) ? segment.key : segment);
-}
-/**
-* Normalize Standard Schema issues into canonical `ValidationIssue` objects.
-*
-* Applies an optional prefix (e.g. `["flags", "verbose"]`) to each issue
-* path, then formats each path to its canonical dot-path string.
-*
-* @param issues — Raw Standard Schema issues from a failed validation
-* @param prefix — Optional path segments prepended to each issue path
-*/
-function normalizeStandardIssues(issues, prefix = []) {
-	return issues.map((issue) => {
-		const resolvedPath = normalizeStandardPath(issue.path);
-		const fullPath = [...prefix, ...resolvedPath];
-		return {
-			message: issue.message,
-			path: formatPath(fullPath)
-		};
-	});
-}
-//#endregion
 //#region src/merge.ts
 /**
 * Applies field defaults to a persisted config object.
@@ -375,12 +282,6 @@ function applyFieldDefaults(persisted, fields, pruneUnknown = true) {
 	return result;
 }
 //#endregion
-//#region ../utils/src/error.ts
-/** Narrows a caught Node.js system error to its stable errno contract. */
-function isErrnoException(error) {
-	return error instanceof Error && "code" in error && typeof error.code === "string";
-}
-//#endregion
 //#region src/persistence.ts
 /**
 * Reads and parses a JSON config file from disk.
@@ -602,7 +503,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 +534,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 +569,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 +582,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.1",
+	"version": "0.4.1",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"sideEffects": false,
@@ -47,10 +47,12 @@
 		"prepack": "cp ../../LICENSE LICENSE",
 		"postpack": "rm -f LICENSE"
 	},
+	"dependencies": {
+		"@crustjs/utils": "^0.1.0"
+	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
 		"zod": "^4.5.4",
-		"@crustjs/utils": "0.0.0",
 		"tsdown": "^0.23.0"
 	},
 	"peerDependencies": {