@crustjs/store 0.0.3 → 0.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 DX-first, typed persistence for CLI apps with clear config/data/state/cache separation.
 
-`@crustjs/store` gives your CLI production-ready local persistence with near-zero setup. Provide a defaults object, pick a storage intent, and get a typed store with read/write/update/patch/reset — no manual type annotations needed.
+`@crustjs/store` gives your CLI production-ready local persistence with near-zero setup. Provide a `fields` definition, pick a storage intent, and get a typed store with read/write/update/patch/reset — no manual type annotations needed.
 
 ## Install
 
@@ -26,30 +26,31 @@ import { createStore, configDir } from "@crustjs/store";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
-  defaults: {
-    ui: { theme: "light" as string, fontSize: 14 },
-    verbose: false,
+  fields: {
+    theme: { type: "string", default: "light" },
+    fontSize: { type: "number", default: 14 },
+    verbose: { type: "boolean", default: false },
   },
 });
 
 // Read state (returns defaults when no persisted file exists)
 const state = await store.read();
-// → { ui: { theme: "light", fontSize: 14 }, verbose: false }
+// → { theme: "light", fontSize: 14, verbose: false }
 
 // Write a full state object
-await store.write({ ui: { theme: "dark", fontSize: 16 }, verbose: true });
+await store.write({ theme: "dark", fontSize: 16, verbose: true });
 
 // Update with a function
 await store.update((current) => ({ ...current, verbose: false }));
 
-// Patch only specific nested keys
-await store.patch({ ui: { theme: "solarized" } });
+// Patch only specific keys
+await store.patch({ theme: "solarized" });
 
 // Reset to defaults (removes persisted file)
 await store.reset();
 ```
 
-No explicit generics needed — types are inferred from your `defaults` object.
+No explicit generics needed — types are inferred from your `fields` definition.
 
 ## Storage Intent: Choosing a Directory
 
@@ -68,25 +69,36 @@ import { createStore, configDir, dataDir, stateDir, cacheDir } from "@crustjs/st
 // User preferences → ~/.config/my-cli/config.json
 const config = createStore({
   dirPath: configDir("my-cli"),
-  defaults: { theme: "light" as string, verbose: false },
+  fields: {
+    theme: { type: "string", default: "light" },
+    verbose: { type: "boolean", default: false },
+  },
 });
 
 // App data → ~/.local/share/my-cli/config.json
 const data = createStore({
   dirPath: dataDir("my-cli"),
-  defaults: { bookmarks: [] as string[] },
+  fields: {
+    bookmarks: { type: "array", default: [] },
+  },
 });
 
 // Runtime state → ~/.local/state/my-cli/config.json
 const state = createStore({
   dirPath: stateDir("my-cli"),
-  defaults: { lastOpened: "" as string, scrollY: 0 },
+  fields: {
+    lastOpened: { type: "string", default: "" },
+    scrollY: { type: "number", default: 0 },
+  },
 });
 
 // Cache → ~/.cache/my-cli/config.json
 const cache = createStore({
   dirPath: cacheDir("my-cli"),
-  defaults: { etag: "" as string, payload: "" as string },
+  fields: {
+    etag: { type: "string", default: "" },
+    payload: { type: "string", default: "" },
+  },
 });
 ```
 
@@ -123,13 +135,12 @@ const store = createStore(options);
 | -------------- | -------------------------- | -------- | ------------------------------------------------------------------ |
 | `dirPath`      | `string`                   | Yes      | Absolute directory path where the JSON file is stored.             |
 | `name`         | `string`                   | No       | Store name used as filename (default `"config"` → `config.json`).  |
-| `defaults`     | `T`                        | Yes      | Default values defining the store's data shape and fallbacks.      |
-| `validator`    | `StoreValidator<T>`        | No       | Validation function applied on read, write, update, and patch.     |
+| `fields`       | `FieldsDef`                | Yes      | Field definitions defining the store's data shape, types, defaults, and optional validation. |
 | `pruneUnknown` | `boolean`                  | No       | Drop unknown persisted keys on read (default `true`).              |
 
 ### `store.read()`
 
-Reads the persisted state file. Missing keys are filled from `defaults` via deep merge. When no file exists, returns `defaults`.
+Reads the persisted state file. Missing keys are filled from field `defaults`.
 
 ```ts
 const state = await store.read();
@@ -142,10 +153,10 @@ Always returns a value — never `undefined`. Does not write merged defaults bac
 Atomically persists a full state object. The entire previous state is replaced.
 
 ```ts
-await store.write({ ui: { theme: "dark", fontSize: 14 }, verbose: true });
+await store.write({ theme: "dark", fontSize: 14, verbose: true });
 ```
 
-Calls `validator` (if provided) before writing. Parent directories are created if missing.
+Calls per-field `validate` functions (if provided) before writing. Parent directories are created if missing.
 
 ### `store.update(updater)`
 
@@ -154,21 +165,21 @@ Reads the current effective state, applies the updater function, and atomically
 ```ts
 await store.update((current) => ({
   ...current,
-  ui: { ...current.ui, theme: "dark" },
+  theme: "dark",
 }));
 ```
 
-When no persisted file exists, the updater receives `defaults` as the current value. Calls `validator` before writing.
+When no persisted file exists, the updater receives field `defaults` as the current value. Calls per-field `validate` functions before writing.
 
 ### `store.patch(partial)`
 
-Applies a deep partial update to the current state and persists. Only the provided keys are updated; everything else is preserved.
+Applies a shallow partial update to the current state and persists. Only the provided keys are updated; everything else is preserved.
 
 ```ts
-await store.patch({ ui: { theme: "solarized" } });
+await store.patch({ theme: "solarized" });
 ```
 
-Arrays are replaced wholesale (not merged element-by-element). Calls `validator` before writing.
+Calls per-field `validate` functions before writing.
 
 ### `store.reset()`
 
@@ -244,9 +255,10 @@ const dir = configDir("my-cli");
 // Default store → ~/.config/my-cli/config.json
 const settingsStore = createStore({
   dirPath: dir,
-  defaults: {
-    ui: { theme: "light" as string, fontSize: 14 },
-    verbose: false,
+  fields: {
+    theme: { type: "string", default: "light" },
+    fontSize: { type: "number", default: 14 },
+    verbose: { type: "boolean", default: false },
   },
 });
 
@@ -254,7 +266,9 @@ const settingsStore = createStore({
 const authStore = createStore({
   dirPath: dir,
   name: "auth",
-  defaults: { token: "" as string },
+  fields: {
+    token: { type: "string", default: "" },
+  },
 });
 ```
 
@@ -264,27 +278,27 @@ The `name` must not contain path separators or the `.json` extension.
 
 ## Defaults & Merge
 
-When a persisted file exists, `read()` deep-merges defaults for any missing keys:
+When a persisted file exists, `read()` fills missing keys from field `defaults`:
 
 ```ts
 const store = createStore({
   dirPath: configDir("my-cli"),
-  defaults: {
-    ui: { theme: "light", fontSize: 14 },
-    verbose: false,
+  fields: {
+    theme: { type: "string", default: "light" },
+    fontSize: { type: "number", default: 14 },
+    verbose: { type: "boolean", default: false },
   },
 });
 
-// Persisted file contains: { "ui": { "theme": "dark" }, "verbose": true }
+// Persisted file contains: { "theme": "dark", "verbose": true }
 const state = await store.read();
-// → { ui: { theme: "dark", fontSize: 14 }, verbose: true }
+// → { theme: "dark", fontSize: 14, verbose: true }
 ```
 
 ### Merge Rules
 
-- Persisted values override defaults at every nesting level.
-- Missing keys fall back to defaults (recursively for nested objects).
-- Arrays are replaced wholesale — not merged element-by-element.
+- Persisted values override defaults.
+- Missing keys fall back to defaults.
 - Unknown persisted keys are dropped by default (`pruneUnknown: true`). Set `pruneUnknown: false` to preserve them.
 - All values are deep-cloned to prevent shared-reference mutation from defaults.
 - Falsy values (`null`, `0`, `""`, `false`) in the persisted file are preserved — only truly missing keys trigger defaults.
@@ -295,26 +309,27 @@ Merged defaults exist only in memory. The persisted file remains unchanged until
 
 ## Validation
 
-Add schema validation to enforce config integrity on every read, write, update, and patch. When a `validator` is configured, validation is **strict by default** — invalid config fails loudly.
+Add per-field validation to enforce config integrity on every read, write, update, and patch. When a `validate` function is configured on a field, validation is **strict by default** — invalid values fail loudly.
 
 ### Using `@crustjs/validate`
 
-The easiest way to add validation is with store adapters from `@crustjs/validate`:
+The easiest way to add validation is with field adapters from `@crustjs/validate`:
 
 ```ts
 import { z } from "zod";
-import { storeValidator } from "@crustjs/validate/zod";
+import { field } from "@crustjs/validate/zod";
 import { createStore, configDir } from "@crustjs/store";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
-  defaults: { theme: "light" as string, verbose: false },
-  validator: storeValidator(
-    z.object({
-      theme: z.enum(["light", "dark"]),
-      verbose: z.boolean(),
-    }),
-  ),
+  fields: {
+    theme: {
+      type: "string",
+      default: "light",
+      validate: field(z.enum(["light", "dark"])),
+    },
+    verbose: { type: "boolean", default: false },
+  },
 });
 
 // write() validates before persisting
@@ -326,52 +341,64 @@ const config = await store.read();
 // → throws if persisted config is invalid
 ```
 
-`storeValidatorSync()` is also available for synchronous schemas.
+`fieldSync()` is also available for synchronous schemas.
 
 For Effect schemas, wrap with `Schema.standardSchemaV1()`:
 
 ```ts
 import * as Schema from "effect/Schema";
-import { storeValidator } from "@crustjs/validate/effect";
+import { field } from "@crustjs/validate/effect";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
-  defaults: { theme: "light" as string },
-  validator: storeValidator(
-    Schema.standardSchemaV1(
-      Schema.Struct({ theme: Schema.Literal("light", "dark") }),
-    ),
-  ),
+  fields: {
+    theme: {
+      type: "string",
+      default: "light",
+      validate: field(
+        Schema.standardSchemaV1(
+          Schema.Literal("light", "dark"),
+        ),
+      ),
+    },
+  },
 });
 ```
 
 ### Custom validators
 
-You can also provide a validator function directly without `@crustjs/validate`:
+You can also provide a validator function directly on each field:
 
 ```ts
-import type { StoreValidator } from "@crustjs/store";
-
-const validator: StoreValidator<{ theme: string }> = (value) => {
-  const config = value as { theme: string };
-  if (config.theme !== "light" && config.theme !== "dark") {
-    return {
-      ok: false,
-      issues: [{ message: 'Must be "light" or "dark"', path: "theme" }],
-    };
-  }
-  return { ok: true, value: config };
-};
+const store = createStore({
+  dirPath: configDir("my-cli"),
+  fields: {
+    theme: {
+      type: "string",
+      default: "light",
+      validate(value) {
+        const str = value as string;
+        if (str !== "light" && str !== "dark") {
+          return {
+            ok: false,
+            issues: [{ message: 'Must be "light" or "dark"', path: "" }],
+          };
+        }
+        return { ok: true, value: str };
+      },
+    },
+  },
+});
 ```
 
-The `StoreValidator<T>` contract is `(value: unknown) => StoreValidatorResult<T> | Promise<StoreValidatorResult<T>>`, where `StoreValidatorResult<T>` is `{ ok: true, value: T } | { ok: false, issues: StoreValidatorIssue[] }`.
+The per-field `validate` function follows the `StoreValidator<T>` contract: `(value: unknown) => StoreValidatorResult<T> | Promise<StoreValidatorResult<T>>`, where `StoreValidatorResult<T>` is `{ ok: true, value: T } | { ok: false, issues: StoreValidatorIssue[] }`.
 
 ### Validation behavior
 
-- **Write**: Validates before persisting. If the validator transforms the value, the transformed result is persisted.
-- **Read**: Validates after applying defaults. Invalid persisted config fails loudly — no silent fallback to defaults.
-- **Update**: Reads raw config (no validation), applies updater, validates the result, then persists.
-- **Patch**: Reads raw config, applies deep partial merge, validates the result, then persists.
+- **Write**: Validates each field before persisting. If a validator transforms the value, the transformed result is persisted.
+- **Read**: Validates each field after applying defaults. Invalid persisted config fails loudly — no silent fallback to defaults.
+- **Update**: Reads raw config (no validation), applies updater, validates each field, then persists.
+- **Patch**: Reads raw config, applies shallow partial merge, validates each field, then persists.
 - **Reset**: No validation — just removes the persisted file.
 
 ### Catching validation errors
@@ -459,10 +486,11 @@ import type {
   CreateStoreOptions,
   Store,
   StoreUpdater,
+  FieldDef,
+  FieldsDef,
+  InferStoreConfig,
   StoreValidator,
   StoreValidatorResult,
-  StoreValidatorSuccess,
-  StoreValidatorFailure,
   StoreValidatorIssue,
   StoreErrorCode,
   StoreValidationIssue,
@@ -476,10 +504,11 @@ import type {
 | `CreateStoreOptions`      | Options object for `createStore()`.                                     |
 | `Store`                   | Store instance with `read`, `write`, `update`, `patch`, `reset`.        |
 | `StoreUpdater`            | Updater function type `(current: T) => T`.                              |
+| `FieldDef`                | Single field definition with `type`, optional `default`, and optional `validate`. |
+| `FieldsDef`               | Record of field names to `FieldDef` definitions.                        |
+| `InferStoreConfig`        | Inferred store state type from a `FieldsDef` definition.                |
 | `StoreValidator`          | Validator function contract `(value: unknown) => StoreValidatorResult`. |
-| `StoreValidatorResult`    | Discriminated union: `StoreValidatorSuccess \| StoreValidatorFailure`.  |
-| `StoreValidatorSuccess`   | `{ ok: true, value: T }`.                                              |
-| `StoreValidatorFailure`   | `{ ok: false, issues: StoreValidatorIssue[] }`.                        |
+| `StoreValidatorResult`    | Discriminated union: `{ ok: true, value: T } \| { ok: false, issues: StoreValidatorIssue[] }`. |
 | `StoreValidatorIssue`     | `{ message: string, path: string }`.                                   |
 | `StoreValidationIssue`    | Validation issue in error details payload.                              |
 | `ValidationErrorDetails`  | Error details for `VALIDATION` code: `{ operation, issues }`.          |

package/dist/index.d.ts

@@ -1,94 +1,155 @@
+/** Supported type literals for store fields. */
+type ValueType = "string" | "number" | "boolean";
 /**
-* Recursively makes all properties of `T` optional.
+* Resolves a type literal to its corresponding TypeScript primitive type.
 *
-* - Plain objects are recursed into — each nested key becomes optional.
-* - Arrays are left as-is (replaced wholesale, not partially updated).
-* - Primitives pass through unchanged.
+* - `"string"` → `string`
+* - `"number"` → `number`
+* - `"boolean"` → `boolean`
+*/
+type ResolvePrimitive<T extends ValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+/** Shared fields present on every store field definition. */
+interface FieldDefBase<V> {
+	/** Human-readable description for documentation and tooling. */
+	description?: string;
+	/**
+	* Optional per-field validation function.
+	*
+	* Called during `read`, `write`, `update`, and `patch` operations when
+	* the field has a value (not `undefined`). Throw an error to reject the
+	* value.
+	*
+	* @param value - The field value to validate.
+	* @throws When the value is invalid — the error message is captured as a
+	*   validation issue with the field name as `path`.
+	*/
+	validate?: (value: V) => void | Promise<void>;
+}
+/** Base for scalar (non-array) fields — `array` must be omitted. */
+interface ScalarFieldBase<V> extends FieldDefBase<V> {
+	/** Must be omitted for scalar fields — set to `true` for array fields. */
+	array?: never;
+}
+/** A scalar string field. */
+interface StringFieldDef extends ScalarFieldBase<string> {
+	type: "string";
+	/** Default string value when the field is not persisted. */
+	default?: string;
+}
+/** A scalar number field. */
+interface NumberFieldDef extends ScalarFieldBase<number> {
+	type: "number";
+	/** Default number value when the field is not persisted. */
+	default?: number;
+}
+/** A scalar boolean field. */
+interface BooleanFieldDef extends ScalarFieldBase<boolean> {
+	type: "boolean";
+	/** Default boolean value when the field is not persisted. */
+	default?: boolean;
+}
+/** Base for array fields — `array` is required as `true`. */
+interface ArrayFieldBase<V> extends FieldDefBase<V> {
+	/** Collect values into an array. */
+	array: true;
+}
+/** An array of strings field. */
+interface StringArrayFieldDef extends ArrayFieldBase<string[]> {
+	type: "string";
+	/** Default string array value when the field is not persisted. */
+	default?: readonly string[];
+}
+/** An array of numbers field. */
+interface NumberArrayFieldDef extends ArrayFieldBase<number[]> {
+	type: "number";
+	/** Default number array value when the field is not persisted. */
+	default?: readonly number[];
+}
+/** An array of booleans field. */
+interface BooleanArrayFieldDef extends ArrayFieldBase<boolean[]> {
+	type: "boolean";
+	/** Default boolean array value when the field is not persisted. */
+	default?: readonly boolean[];
+}
+/**
+* Defines a single field in a store's config schema.
 *
-* Used by {@link Store.patch} for deep partial updates.
+* Discriminated by `type` and `array` for type-safe `default` values.
+* Each field can optionally include a `validate` function for per-field
+* validation and a `default` value for fallback behavior.
 *
 * @example
 * ```ts
-* type Config = { ui: { theme: string; fontSize: number }; verbose: boolean };
-* type Partial = DeepPartial<Config>;
-* // → { ui?: { theme?: string; fontSize?: number }; verbose?: boolean }
+* const fields = {
+*   theme: { type: "string", default: "light" },
+*   verbose: { type: "boolean", default: false },
+*   tags: { type: "string", array: true, default: [] },
+*   token: { type: "string" },  // optional — no default
+*   port: {
+*     type: "number",
+*     default: 3000,
+*     validate: (v) => { if (v < 1 || v > 65535) throw new Error("invalid port"); },
+*   },
+* } satisfies FieldsDef;
 * ```
 */
-type DeepPartial<T> = T extends readonly unknown[] ? T : T extends Record<string, unknown> ? { [K in keyof T]? : DeepPartial<T[K]> } : T;
+type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef;
+/** Record mapping field names to their definitions. */
+type FieldsDef = Record<string, FieldDef>;
 /**
-* Result returned by a {@link StoreValidator} when validation succeeds.
+* Infer the resolved type for a single field definition.
 *
-* Carries the (possibly transformed) config value from the schema.
+* - **array** → `primitive[]` (or `primitive[] | undefined` if no default)
+* - **has default** → `primitive` (guaranteed present)
+* - **no default** → `primitive | undefined` (optional)
 */
-interface StoreValidatorSuccess<T> {
-	readonly ok: true;
-	readonly value: T;
-}
+type InferFieldValue<F extends FieldDef> = F extends {
+	array: true;
+} ? F extends {
+	default: readonly ResolvePrimitive<F["type"]>[];
+} ? ResolvePrimitive<F["type"]>[] : ResolvePrimitive<F["type"]>[] | undefined : F extends {
+	default: ResolvePrimitive<F["type"]>;
+} ? ResolvePrimitive<F["type"]> : ResolvePrimitive<F["type"]> | undefined;
 /**
-* A single validation issue reported by a {@link StoreValidator}.
+* Maps a full {@link FieldsDef} record to the inferred config object type.
 *
-* Compatible with the canonical `ValidationIssue` shape used across the Crust
-* validation platform.
+* @example
+* ```ts
+* type Config = InferStoreConfig<{
+*   theme: { type: "string"; default: "light" };
+*   verbose: { type: "boolean" };
+* }>;
+* // → { theme: string; verbose: boolean | undefined }
+* ```
+*/
+type InferStoreConfig<F extends FieldsDef> = { [K in keyof F] : InferFieldValue<F[K]> };
+/**
+* A single validation issue reported during store operations.
 */
 interface StoreValidatorIssue {
 	/** Human-readable description of the validation failure. */
 	message: string;
-	/** Dot-path to the invalid field, or empty string for root-level issues. */
+	/** Field name where the issue occurred. */
 	path: string;
 }
 /**
-* Result returned by a {@link StoreValidator} when validation fails.
-*
-* Carries structured issues for programmatic handling and error rendering.
-*/
-interface StoreValidatorFailure {
-	readonly ok: false;
-	readonly issues: readonly StoreValidatorIssue[];
-}
-/**
-* Discriminated union result from a {@link StoreValidator}.
-*/
-type StoreValidatorResult<T> = StoreValidatorSuccess<T> | StoreValidatorFailure;
-/**
-* A provider-agnostic validator function for full config objects.
-*
-* Accepts a config value and returns a discriminated result indicating
-* success (with a possibly-transformed value) or failure (with structured issues).
-*
-* Store adapters in `@crustjs/validate` produce functions matching this contract
-* from Standard Schema, Zod, or Effect schemas.
-*
-* @typeParam T - The expected config type.
-*
-* @example
-* ```ts
-* const validator: StoreValidator<Config> = (config) => {
-*   if (typeof config.theme !== "string") {
-*     return { ok: false, issues: [{ message: "Expected string", path: "theme" }] };
-*   }
-*   return { ok: true, value: config };
-* };
-* ```
-*/
-type StoreValidator<T> = (value: unknown) => StoreValidatorResult<T> | Promise<StoreValidatorResult<T>>;
-/**
 * Options for {@link createStore}.
 *
-* @typeParam T - The store data shape, inferred from `defaults`.
+* @typeParam F - The field definitions record (inferred via `const` generic).
 *
 * @example
 * ```ts
 * const store = createStore({
 *   dirPath: configDir("my-cli"),
-*   defaults: {
-*     ui: { theme: "light", fontSize: 14 },
-*     verbose: false,
-*     tags: ["default"],
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
+*     token: { type: "string" },
 *   },
 * });
 * ```
 */
-interface CreateStoreOptions<T extends Record<string, unknown>> {
+interface CreateStoreOptions<F extends FieldsDef> {
 	/**
 	* Absolute directory path where the store JSON file is persisted.
 	*
@@ -107,38 +168,14 @@ interface CreateStoreOptions<T extends Record<string, unknown>> {
 	*/
 	name?: string;
 	/**
-	* Default values for the store. Defines the data shape and provides
-	* fallback values when no persisted file exists or keys are missing.
-	*
-	* The TypeScript type of `defaults` determines the store's `T` parameter.
-	*/
-	defaults: T;
-	/**
-	* Optional validator function applied to config objects during read, write,
-	* update, and patch operations.
-	*
-	* When provided, validation is **strict by default**: invalid config will
-	* cause a `CrustStoreError` with `VALIDATION` code to be thrown on both
-	* persistence (write/update/patch) and load (read) paths.
+	* Field definitions that declare the store's config schema.
 	*
-	* Use store adapters from `@crustjs/validate/standard`, `@crustjs/validate/zod`,
-	* or `@crustjs/validate/effect` to create validators from schema definitions.
-	*
-	* @example
-	* ```ts
-	* import { storeValidator } from "@crustjs/validate/zod";
-	* import { z } from "zod";
-	*
-	* const store = createStore({
-	*   dirPath: configDir("my-cli"),
-	*   defaults: { theme: "light", verbose: false },
-	*   validator: storeValidator(z.object({ theme: z.enum(["light", "dark"]) })),
-	* });
-	* ```
+	* Each key maps to a {@link FieldDef} with a `type` discriminant and optional
+	* `default` and `validate`. Fields without a `default` are optional (`T | undefined`).
 	*/
-	validator?: StoreValidator<T>;
+	fields: F;
 	/**
-	* When `true` (the default), persisted keys not present in `defaults`
+	* When `true` (the default), persisted keys not present in `fields`
 	* are dropped on read. Set to `false` to preserve unknown keys.
 	*
 	* @default true
@@ -146,7 +183,7 @@ interface CreateStoreOptions<T extends Record<string, unknown>> {
 	pruneUnknown?: boolean;
 }
 /**
-* Receives the current effective state and returns an updated state.
+* Receives the current effective config and returns an updated config.
 *
 * Used by {@link Store.update} to apply mutations atomically.
 *
@@ -154,91 +191,85 @@ interface CreateStoreOptions<T extends Record<string, unknown>> {
 * ```ts
 * await store.update((current) => ({
 *   ...current,
-*   ui: { ...current.ui, theme: "dark" },
+*   theme: "dark",
 * }));
 * ```
 */
-type StoreUpdater<T> = (current: T) => NoInfer<T>;
+type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
 /**
-* A typed async store returned by {@link createStore}.
+* A typed async config store returned by {@link createStore}.
 *
 * Provides `read`, `write`, `update`, `patch`, and `reset` operations for a
-* typed state object persisted as JSON on the local filesystem.
+* single typed config object persisted as JSON on the local filesystem.
 *
-* @typeParam T - The store data shape, inferred from `defaults`.
+* @typeParam TConfig - The inferred config shape from field definitions.
 *
 * @example
 * ```ts
 * const store = createStore({
 *   dirPath: configDir("my-cli"),
-*   defaults: {
-*     ui: { theme: "light", fontSize: 14 },
-*     verbose: false,
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
 *   },
 * });
 *
-* const state = await store.read();
-* await store.write({ ui: { theme: "dark", fontSize: 14 }, verbose: true });
-* await store.update((s) => ({ ...s, verbose: false }));
-* await store.patch({ ui: { theme: "dark" } });
+* const config = await store.read();
+* await store.write({ theme: "dark", verbose: true });
+* await store.update((c) => ({ ...c, theme: "dark" }));
+* await store.patch({ theme: "dark" });
 * await store.reset();
 * ```
 */
-interface Store<T> {
+interface Store<TConfig> {
 	/**
-	* Reads the persisted state, merging defaults for missing keys.
+	* Reads the persisted config, applying field defaults for missing keys.
 	*
-	* Always returns a complete `T` — missing persisted keys are filled
-	* from `defaults`.
+	* Always returns a value — fields with defaults are guaranteed present,
+	* fields without defaults may be `undefined`.
 	*
-	* When a validator is configured, the merged config is validated after
-	* defaults are applied. Invalid persisted config fails loudly.
+	* When fields have `validate` functions, the merged config is validated
+	* after defaults are applied. Invalid persisted config fails loudly.
 	*
-	* @returns The effective config value (possibly transformed by the validator).
+	* @returns The effective config value.
 	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
-	* @throws {CrustStoreError} `VALIDATION` if the config fails validation.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `IO` on filesystem read failures.
 	*/
-	read(): Promise<T>;
+	read(): Promise<TConfig>;
 	/**
-	* Atomically persists the full state object.
+	* Atomically persists the full config object.
 	*
-	* When a validator is configured, the config is validated before persistence.
+	* When fields have `validate` functions, the config is validated before
+	* persistence.
 	*
-	* @param state - The complete state to persist.
-	* @throws {CrustStoreError} `VALIDATION` if the config fails validation.
+	* @param config - The complete config to persist.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `IO` on filesystem write failures.
 	*/
-	write(state: NoInfer<T>): Promise<void>;
+	write(config: NoInfer<TConfig>): Promise<void>;
 	/**
-	* Reads current effective state, applies the updater, and persists.
-	*
-	* When a validator is configured, the updated config is validated before
-	* persistence. The read step during update does **not** validate separately
-	* to avoid double-validation overhead — the `current` value passed to the
-	* updater may not have been validated (e.g. if the persisted file was
-	* manually edited).
+	* Reads current effective config, applies the updater, and persists.
 	*
-	* @param updater - Function receiving current state and returning updated state.
+	* @param updater - Function receiving current config and returning updated config.
 	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
-	* @throws {CrustStoreError} `VALIDATION` if the updated config fails validation.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `IO` on filesystem failures.
 	*/
-	update(updater: StoreUpdater<T>): Promise<void>;
+	update(updater: StoreUpdater<TConfig>): Promise<void>;
 	/**
-	* Applies a deep partial update to the current state and persists.
+	* Applies a partial update to the current config and persists.
 	*
 	* Only the provided keys are updated; everything else is preserved.
-	* Arrays are replaced wholesale (not merged element-by-element).
 	*
-	* @param partial - A deep-partial subset of the state to merge in.
-	* @throws {CrustStoreError} `VALIDATION` if the merged config fails validation.
+	* @param partial - A partial subset of the config to merge in.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
 	* @throws {CrustStoreError} `IO` on filesystem failures.
 	*/
-	patch(partial: DeepPartial<NoInfer<T>>): Promise<void>;
+	patch(partial: Partial<NoInfer<TConfig>>): Promise<void>;
 	/**
-	* Removes the persisted state file, returning the store to
+	* Removes the persisted config file, returning the store to
 	* defaults-on-read behavior.
 	*
 	* @throws {CrustStoreError} `IO` on filesystem deletion failures.
@@ -510,13 +541,14 @@ declare function stateDir(appName: string, env?: PlatformEnv): string;
 */
 declare function cacheDir(appName: string, env?: PlatformEnv): string;
 /**
-* Creates a typed async store backed by a local JSON file.
+* Creates a typed async config store backed by a local JSON file.
 *
 * The store resolves its file path once at creation time from `dirPath` and
-* optional `name`. The `defaults` object declares the data shape — its
-* TypeScript type determines the store's type parameter `T`.
+* optional `name`. Field definitions declare the config schema — each field's
+* `type` determines its TypeScript type, and the presence of `default`
+* determines whether the field is guaranteed or optional (`T | undefined`).
 *
-* @typeParam T - The store data shape (inferred from `defaults`).
+* @typeParam F - Field definitions record (inferred via `const` generic).
 * @param options - Store configuration options.
 * @returns A {@link Store} instance with `read`, `write`, `update`, `patch`, and `reset` methods.
 * @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
@@ -527,20 +559,21 @@ declare function cacheDir(appName: string, env?: PlatformEnv): string;
 *
 * const store = createStore({
 *   dirPath: configDir("my-cli"),
-*   defaults: {
-*     ui: { theme: "light", fontSize: 14 },
-*     verbose: false,
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
+*     token: { type: "string" },
 *   },
 * });
 *
-* const state = await store.read();
-* // → { ui: { theme: "light", fontSize: 14 }, verbose: false }
+* const config = await store.read();
+* // → { theme: "light", verbose: false, token: undefined }
 *
-* await store.write({ ui: { theme: "dark", fontSize: 14 }, verbose: true });
-* await store.update((s) => ({ ...s, verbose: false }));
-* await store.patch({ ui: { theme: "dark" } });
+* await store.write({ theme: "dark", verbose: true, token: "abc" });
+* await store.update((c) => ({ ...c, theme: "light" }));
+* await store.patch({ theme: "solarized" });
 * await store.reset();
 * ```
 */
-declare function createStore<const T extends Record<string, unknown>>(options: CreateStoreOptions<T>): Store<T>;
-export { stateDir, dataDir, createStore, configDir, cacheDir, ValidationErrorDetails, StoreValidatorSuccess, StoreValidatorResult, StoreValidatorIssue, StoreValidatorFailure, StoreValidator, StoreUpdater, StoreErrorCode, Store, PlatformEnv, CrustStoreError, CreateStoreOptions };
+declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
+export { stateDir, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
 // @bun
-class K extends Error{code;details;cause;constructor(q,B,z){super(B);this.name="CrustStoreError",this.code=q,this.details=z}is(q){return this.code===q}withCause(q){return this.cause=q,this}}import{homedir as f}from"os";import{join as Q}from"path";var P="config";function _(){return{platform:process.platform,env:process.env,homedir:f()}}function T(q){if(!q||q.trim().length===0)throw new K("PATH","appName must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new K("PATH","appName must not contain path separators",{path:q})}function h(q){if(!q||q.trim().length===0)throw new K("PATH","name must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new K("PATH","name must not contain path separators",{path:q});if(q.endsWith(".json"))throw new K("PATH","name must not include the .json extension",{path:q})}function v(q){if(!q||q.trim().length===0)throw new K("PATH","dirPath must be a non-empty string",{path:q??""});if(!(q.startsWith("/")||/^[A-Za-z]:[/\\]/.test(q)))throw new K("PATH","dirPath must be an absolute path",{path:q});if(q.endsWith(".json"))throw new K("PATH","dirPath must be a directory path, not a file path (should not end with .json)",{path:q})}function F(q,B,z,G){let H=q.env[B],W=H&&H.trim().length>0?H:Q(q.homedir,...z);return Q(W,G)}function O(q){throw new K("PATH",`Unsupported platform: ${q}`,{path:q})}function m(q,B){T(q);let z=B??_();switch(z.platform){case"linux":case"darwin":return F(z,"XDG_CONFIG_HOME",[".config"],q);case"win32":{let G=z.env.APPDATA,H=G&&G.trim().length>0?G:Q(z.homedir,"AppData","Roaming");return Q(H,q)}default:O(z.platform)}}function u(q,B){T(q);let z=B??_();switch(z.platform){case"linux":case"darwin":return F(z,"XDG_DATA_HOME",[".local","share"],q);case"win32":{let G=z.env.LOCALAPPDATA,H=G&&G.trim().length>0?G:Q(z.homedir,"AppData","Local");return Q(H,q,"Data")}default:O(z.platform)}}function d(q,B){T(q);let z=B??_();switch(z.platform){case"linux":case"darwin":return F(z,"XDG_STATE_HOME",[".local","state"],q);case"win32":{let G=z.env.LOCALAPPDATA,H=G&&G.trim().length>0?G:Q(z.homedir,"AppData","Local");return Q(H,q,"State")}default:O(z.platform)}}function o(q,B){T(q);let z=B??_();switch(z.platform){case"linux":case"darwin":return F(z,"XDG_CACHE_HOME",[".cache"],q);case"win32":{let G=z.env.LOCALAPPDATA,H=G&&G.trim().length>0?G:Q(z.homedir,"AppData","Local");return Q(H,q,"Cache")}default:O(z.platform)}}function b(q,B){v(q);let z=B??P;if(B!==void 0)h(B);return Q(q,`${z}.json`)}function V(q){return q!==null&&typeof q==="object"&&!Array.isArray(q)}function x(q){if(Array.isArray(q))return[...q];if(V(q)){let B={};for(let[z,G]of Object.entries(q))B[z]=x(G);return B}return q}function J(q,B,z=!0){let G={};for(let[H,W]of Object.entries(B))if(q!==void 0&&H in q){let X=q[H];if(V(W)&&V(X))G[H]=J(X,W,z);else G[H]=x(X)}else G[H]=x(W);if(!z&&q!==void 0){for(let[H,W]of Object.entries(q))if(!(H in B))G[H]=x(W)}return G}import{randomUUID as s}from"crypto";import{mkdir as i,readFile as p,rename as n,rm as l,unlink as t,writeFile as r}from"fs/promises";import{dirname as a,join as e}from"path";async function j(q){let B;try{B=await p(q,"utf-8")}catch(z){if(D(z))return;throw new K("IO",`Failed to read config file: ${q}`,{path:q,operation:"read"}).withCause(z)}try{return JSON.parse(B)}catch(z){throw new K("PARSE",`Malformed JSON in config file: ${q}`,{path:q}).withCause(z)}}async function R(q,B){let z=a(q),G=e(z,`.config-${s()}.tmp`);try{await i(z,{recursive:!0})}catch(H){throw new K("IO",`Failed to create config directory: ${z}`,{path:q,operation:"write"}).withCause(H)}try{let H=JSON.stringify(B,null,"\t");await r(G,H,"utf-8")}catch(H){throw await U(G),new K("IO",`Failed to write config file: ${q}`,{path:q,operation:"write"}).withCause(H)}try{await n(G,q)}catch(H){throw await U(G),new K("IO",`Failed to finalize config file: ${q}`,{path:q,operation:"write"}).withCause(H)}}async function A(q){try{await t(q)}catch(B){if(D(B))return;throw new K("IO",`Failed to delete config file: ${q}`,{path:q,operation:"delete"}).withCause(B)}}function D(q){return q!==null&&typeof q==="object"&&"code"in q&&q.code==="ENOENT"}async function U(q){try{await l(q,{force:!0})}catch{}}function qq(q){let{dirPath:B,name:z,defaults:G,validator:H,pruneUnknown:W}=q,X=b(B,z),C=W??!0;async function M(L,Y){if(!H)return L;let Z=await H(L);if(Z.ok)return Z.value;let I=Z.issues.map(($)=>({message:$.message,path:$.path})),y=I.map(($)=>$.path?`  - ${$.path}: ${$.message}`:`  - ${$.message}`),N=y.length>0?`Store validation failed (${Y})
-${y.join(`
-`)}`:`Store validation failed (${Y})`;throw new K("VALIDATION",N,{operation:Y,issues:I})}async function S(){let L=await j(X);return J(L,G,C)}async function k(){let L=await S();return M(L,"read")}async function g(L){let Y=await M(L,"write");await R(X,Y)}async function c(L){let Y=await S(),Z=L(Y),I=await M(Z,"update");await R(X,I)}async function w(L){let Y=await S(),Z=J(L,Y,!1),I=await M(Z,"patch");await R(X,I)}async function E(){await A(X)}return{read:k,write:g,update:c,patch:w,reset:E}}export{d as stateDir,u as dataDir,qq as createStore,m as configDir,o as cacheDir,K as CrustStoreError};
+class Q extends Error{code;details;cause;constructor(q,I,G){super(I);this.name="CrustStoreError",this.code=q,this.details=G}is(q){return this.code===q}withCause(q){return this.cause=q,this}}import{homedir as P}from"os";import{join as $}from"path";var h="config";function V(){return{platform:process.platform,env:process.env,homedir:P()}}function F(q){if(!q||q.trim().length===0)throw new Q("PATH","appName must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new Q("PATH","appName must not contain path separators",{path:q})}function u(q){if(!q||q.trim().length===0)throw new Q("PATH","name must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new Q("PATH","name must not contain path separators",{path:q});if(q.endsWith(".json"))throw new Q("PATH","name must not include the .json extension",{path:q})}function v(q){if(!q||q.trim().length===0)throw new Q("PATH","dirPath must be a non-empty string",{path:q??""});if(!(q.startsWith("/")||/^[A-Za-z]:[/\\]/.test(q)))throw new Q("PATH","dirPath must be an absolute path",{path:q});if(q.endsWith(".json"))throw new Q("PATH","dirPath must be a directory path, not a file path (should not end with .json)",{path:q})}function T(q,I,G,H){let K=q.env[I],W=K&&K.trim().length>0?K:$(q.homedir,...G);return $(W,H)}function b(q){throw new Q("PATH",`Unsupported platform: ${q}`,{path:q})}function m(q,I){F(q);let G=I??V();switch(G.platform){case"linux":case"darwin":return T(G,"XDG_CONFIG_HOME",[".config"],q);case"win32":{let H=G.env.APPDATA,K=H&&H.trim().length>0?H:$(G.homedir,"AppData","Roaming");return $(K,q)}default:b(G.platform)}}function d(q,I){F(q);let G=I??V();switch(G.platform){case"linux":case"darwin":return T(G,"XDG_DATA_HOME",[".local","share"],q);case"win32":{let H=G.env.LOCALAPPDATA,K=H&&H.trim().length>0?H:$(G.homedir,"AppData","Local");return $(K,q,"Data")}default:b(G.platform)}}function o(q,I){F(q);let G=I??V();switch(G.platform){case"linux":case"darwin":return T(G,"XDG_STATE_HOME",[".local","state"],q);case"win32":{let H=G.env.LOCALAPPDATA,K=H&&H.trim().length>0?H:$(G.homedir,"AppData","Local");return $(K,q,"State")}default:b(G.platform)}}function s(q,I){F(q);let G=I??V();switch(G.platform){case"linux":case"darwin":return T(G,"XDG_CACHE_HOME",[".cache"],q);case"win32":{let H=G.env.LOCALAPPDATA,K=H&&H.trim().length>0?H:$(G.homedir,"AppData","Local");return $(K,q,"Cache")}default:b(G.platform)}}function U(q,I){v(q);let G=I??h;if(I!==void 0)u(I);return $(q,`${G}.json`)}function z(q,I,G=!0){let H={};for(let[K,W]of Object.entries(I))if(q&&K in q){let _=q[K];H[K]=Array.isArray(_)?[..._]:_}else if("default"in W&&W.default!==void 0)H[K]=Array.isArray(W.default)?[...W.default]:W.default;if(!G&&q!==void 0){for(let[K,W]of Object.entries(q))if(!(K in I))H[K]=Array.isArray(W)?[...W]:W}return H}import{randomUUID as p}from"crypto";import{mkdir as n,readFile as i,rename as l,rm as t,unlink as r,writeFile as a}from"fs/promises";import{dirname as e,join as qq}from"path";async function S(q){let I;try{I=await i(q,"utf-8")}catch(G){if(y(G))return;throw new Q("IO",`Failed to read config file: ${q}`,{path:q,operation:"read"}).withCause(G)}try{return JSON.parse(I)}catch(G){throw new Q("PARSE",`Malformed JSON in config file: ${q}`,{path:q}).withCause(G)}}async function R(q,I){let G=e(q),H=qq(G,`.config-${p()}.tmp`);try{await n(G,{recursive:!0})}catch(K){throw new Q("IO",`Failed to create config directory: ${G}`,{path:q,operation:"write"}).withCause(K)}try{let K=JSON.stringify(I,null,"\t");await a(H,K,"utf-8")}catch(K){throw await A(H),new Q("IO",`Failed to write config file: ${q}`,{path:q,operation:"write"}).withCause(K)}try{await l(H,q)}catch(K){throw await A(H),new Q("IO",`Failed to finalize config file: ${q}`,{path:q,operation:"write"}).withCause(K)}}async function k(q){try{await r(q)}catch(I){if(y(I))return;throw new Q("IO",`Failed to delete config file: ${q}`,{path:q,operation:"delete"}).withCause(I)}}function y(q){return q!==null&&typeof q==="object"&&"code"in q&&q.code==="ENOENT"}async function A(q){try{await t(q,{force:!0})}catch{}}function Gq(q){let{dirPath:I,name:G,fields:H,pruneUnknown:K}=q,W=U(I,G),_=K??!0;function C(L,Y){if(Y==="number"&&typeof L==="string"){let X=Number(L);return Number.isNaN(X)?L:X}if(Y==="boolean"&&typeof L==="string")return L==="true"||L==="1";return L}function x(L){let X={...L};for(let[Z,M]of Object.entries(H)){if(!(Z in X))continue;let O=X[Z];if(M.array===!0&&Array.isArray(O)){X[Z]=O.map((B)=>C(B,M.type));continue}X[Z]=C(O,M.type)}return X}async function J(L,Y){let X=[],Z=L;for(let[M,O]of Object.entries(H)){if(!O.validate)continue;let B=Z[M];if(B===void 0)continue;try{await O.validate(B)}catch(D){let f=D instanceof Error?D.message:"Validation failed";X.push({message:f,path:M})}}if(X.length>0){let M=X.map((B)=>`  - ${B.path}: ${B.message}`),O=`Store validation failed (${Y})
+${M.join(`
+`)}`;throw new Q("VALIDATION",O,{operation:Y,issues:X})}}async function j(){let L=await S(W),Y=z(L,H,_);return x(Y)}async function g(){let L=await j();return await J(L,"read"),L}async function w(L){let Y=x(L);await J(Y,"write"),await R(W,Y)}async function c(L){let Y=await j(),X=L(Y),Z=x(X);await J(Z,"update"),await R(W,Z)}async function E(L){let X={...await j(),...L},Z=x(X);await J(Z,"patch"),await R(W,Z)}async function N(){await k(W)}return{read:g,write:w,update:c,patch:E,reset:N}}export{o as stateDir,d as dataDir,Gq as createStore,m as configDir,s as cacheDir,Q as CrustStoreError};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/store",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"license": "MIT",