@crustjs/store 0.0.3 → 0.1.0

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,67 +26,85 @@ 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
 
 `@crustjs/store` provides four path helpers that resolve platform-standard directories for different storage intents. Use the one that matches what you're persisting:
 
-| Helper      | Intent                     | Example Use Case                        |
-| ----------- | -------------------------- | --------------------------------------- |
-| `configDir` | User preferences & config  | Theme, editor settings, API keys        |
-| `dataDir`   | Important app data         | Local databases, downloaded resources   |
-| `stateDir`  | Runtime state              | Window positions, scroll offsets, undo  |
-| `cacheDir`  | Regenerable cached data    | HTTP caches, compiled assets            |
+| Helper      | Intent                    | Example Use Case                       |
+| ----------- | ------------------------- | -------------------------------------- |
+| `configDir` | User preferences & config | Theme, editor settings, API keys       |
+| `dataDir`   | Important app data        | Local databases, downloaded resources  |
+| `stateDir`  | Runtime state             | Window positions, scroll offsets, undo |
+| `cacheDir`  | Regenerable cached data   | HTTP caches, compiled assets           |
 
 ```ts
-import { createStore, configDir, dataDir, stateDir, cacheDir } from "@crustjs/store";
+import {
+  createStore,
+  configDir,
+  dataDir,
+  stateDir,
+  cacheDir,
+} from "@crustjs/store";
 
 // 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: "" },
+  },
 });
 ```
 
@@ -94,12 +112,12 @@ const cache = createStore({
 
 All four helpers follow XDG conventions on Linux and macOS, and Windows-native conventions on Windows:
 
-| Helper      | Linux / macOS                       | Windows                                     | Env Override         |
-| ----------- | ----------------------------------- | ------------------------------------------- | -------------------- |
-| `configDir` | `~/.config/<app>`                   | `%APPDATA%\<app>`                           | `$XDG_CONFIG_HOME`   |
-| `dataDir`   | `~/.local/share/<app>`              | `%LOCALAPPDATA%\<app>\Data`                 | `$XDG_DATA_HOME`     |
-| `stateDir`  | `~/.local/state/<app>`              | `%LOCALAPPDATA%\<app>\State`                | `$XDG_STATE_HOME`    |
-| `cacheDir`  | `~/.cache/<app>`                    | `%LOCALAPPDATA%\<app>\Cache`                | `$XDG_CACHE_HOME`    |
+| Helper      | Linux / macOS          | Windows                      | Env Override       |
+| ----------- | ---------------------- | ---------------------------- | ------------------ |
+| `configDir` | `~/.config/<app>`      | `%APPDATA%\<app>`            | `$XDG_CONFIG_HOME` |
+| `dataDir`   | `~/.local/share/<app>` | `%LOCALAPPDATA%\<app>\Data`  | `$XDG_DATA_HOME`   |
+| `stateDir`  | `~/.local/state/<app>` | `%LOCALAPPDATA%\<app>\State` | `$XDG_STATE_HOME`  |
+| `cacheDir`  | `~/.cache/<app>`       | `%LOCALAPPDATA%\<app>\Cache` | `$XDG_CACHE_HOME`  |
 
 macOS uses XDG conventions (same as Linux) for a unified Unix mental model.
 
@@ -119,17 +137,16 @@ const store = createStore(options);
 
 #### Options
 
-| Option         | Type                       | Required | Description                                                        |
-| -------------- | -------------------------- | -------- | ------------------------------------------------------------------ |
-| `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.     |
-| `pruneUnknown` | `boolean`                  | No       | Drop unknown persisted keys on read (default `true`).              |
+| Option         | Type        | Required | Description                                                                                  |
+| -------------- | ----------- | -------- | -------------------------------------------------------------------------------------------- |
+| `dirPath`      | `string`    | Yes      | Absolute directory path where the JSON file is stored.                                       |
+| `name`         | `string`    | No       | Store name used as filename (default `"config"` → `config.json`).                            |
+| `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 +159,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 +171,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 +261,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 +272,9 @@ const settingsStore = createStore({
 const authStore = createStore({
   dirPath: dir,
   name: "auth",
-  defaults: { token: "" as string },
+  fields: {
+    token: { type: "string", default: "" },
+  },
 });
 ```
 
@@ -264,27 +284,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 +315,24 @@ 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`
+### Schema-driven validation
 
-The easiest way to add validation is with store adapters from `@crustjs/validate`:
+The easiest way to add validation is with the built-in `field()` factory.
+It builds a complete `FieldDef` from any Standard Schema — type, default,
+description, and the per-field validator are all derived in one call:
 
 ```ts
 import { z } from "zod";
-import { storeValidator } from "@crustjs/validate/zod";
-import { createStore, configDir } from "@crustjs/store";
+import { createStore, configDir, field } 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: field(z.enum(["light", "dark"]).default("light")),
+    verbose: { type: "boolean", default: false },
+  },
 });
 
 // write() validates before persisting
@@ -326,52 +344,102 @@ const config = await store.read();
 // → throws if persisted config is invalid
 ```
 
-`storeValidatorSync()` is also available for synchronous schemas.
-
-For Effect schemas, wrap with `Schema.standardSchemaV1()`:
+For Effect schemas, wrap once with `Schema.standardSchemaV1()`:
 
 ```ts
 import * as Schema from "effect/Schema";
-import { storeValidator } from "@crustjs/validate/effect";
+import { createStore, configDir, field } from "@crustjs/store";
 
 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: field(Schema.standardSchemaV1(Schema.Literal("light", "dark"))),
+  },
 });
 ```
 
+#### Schema-derived defaults and TypeScript
+
+Standard Schema v1 has no spec-portable type-level access to schema
+defaults. As a result:
+
+- `field(z.string().default("x"))` populates `default: "x"` at runtime,
+  but the inferred config type is `string | undefined` (NOT narrowed).
+- `field(z.string(), { default: "x" })` populates `default: "x"` AND
+  narrows the inferred config type to `string`.
+
+Prefer the explicit form when the field is required to always have a
+value at use sites.
+
+#### `field()` throws on invalid input
+
+`field()` throws `CrustStoreError("DEFINITION")` when handed a
+non-Standard-Schema value, or when the runtime CLI type cannot be
+inferred from the schema and `opts.type` was not supplied. The thrown
+error's `details.vendor` field carries the schema's vendor name (when
+available) to help locate the offending call site.
+
+> **Effect ≥ 3.14.2 required.** Effect 3.14.2 made `standardSchemaV1(...)`
+> wrappers expose `.ast`, which is what the validate registry walks. On
+> Effect 3.14.0 / 3.14.1 the wrapper is a plain object and introspection
+> silently fails. See
+> [`@crustjs/validate` Effect setup](https://crustjs.com/docs/modules/validate#quick-start--effect)
+> for the floor and a workaround.
+
 ### Custom validators
 
-You can also provide a validator function directly without `@crustjs/validate`:
+You can also provide a validator function directly on each field. Validators
+return `void` on success and **throw** on failure — the thrown `Error`'s
+`message` is captured as the issue text and the field name is used as the
+issue path.
 
 ```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) {
+        if (value !== "light" && value !== "dark") {
+          throw new Error('Must be "light" or "dark"');
+        }
+      },
+    },
+  },
+});
 ```
 
-The `StoreValidator<T>` contract is `(value: unknown) => StoreValidatorResult<T> | Promise<StoreValidatorResult<T>>`, where `StoreValidatorResult<T>` is `{ ok: true, value: T } | { ok: false, issues: StoreValidatorIssue[] }`.
+Hand-rolled `validate` callbacks are `(value: V) => void | Promise<void>`.
+Return `void` (or `Promise<void>`) to accept; throw an `Error` to reject.
+These remain validation-only — they cannot transform the persisted value.
+
+Fields built via the `field()` factory carry a Standard Schema and DO
+persist transforms on `write` / `update` / `patch` (e.g.
+`field(z.string().transform(s => s.trim()))` writes the trimmed value to
+disk). On `read`, the schema still validates the persisted value but its
+transform output is discarded — the on-disk value is returned unchanged.
+Existing on-disk values survive unchanged across upgrades; the first
+subsequent write canonicalizes them through the transform.
+
+A write-time **read-stability guard** rejects cross-type transforms whose
+output would fail the schema's own re-validation. For example,
+`field(z.string().transform(Number))` (string in, number out) is rejected
+with `CrustStoreError("VALIDATION")` and an issue message tagged
+`read-unstable transform`. No on-disk write occurs.
 
 ### 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. Schema-driven
+  transforms (via `field()`) replace the input value with the transformed
+  output; hand-rolled validators cannot transform.
+- **Read**: Validates each field after applying defaults. Invalid persisted
+  config fails loudly — no silent fallback to defaults. Schema transform
+  output is discarded on read; the returned value matches what is on disk.
+- **Update**: Reads raw config (no validation), applies updater, validates
+  each field (persisting any schema-transformed outputs), then persists.
+- **Patch**: Reads raw config, applies shallow partial merge, validates each
+  field (persisting any schema-transformed outputs), then persists.
 - **Reset**: No validation — just removes the persisted file.
 
 ### Catching validation errors
@@ -383,7 +451,7 @@ try {
   await store.read();
 } catch (err) {
   if (err instanceof CrustStoreError && err.is("VALIDATION")) {
-    // err.details is { operation: "read" | "write" | "update" | "patch", issues: StoreValidationIssue[] }
+    // err.details is { operation: "read" | "write" | "update" | "patch", issues: StoreValidatorIssue[] }
     console.error(`Validation failed during ${err.details.operation}:`);
     for (const issue of err.details.issues) {
       console.error(`  ${issue.path || "(root)"}: ${issue.message}`);
@@ -396,12 +464,12 @@ try {
 
 All errors thrown by `@crustjs/store` are instances of `CrustStoreError` with a typed `code` property:
 
-| Code         | When                                                            | Details                     |
-| ------------ | --------------------------------------------------------------- | --------------------------- |
-| `PATH`       | Invalid `dirPath`, invalid `name`, unsupported platform         | `{ path: string }`         |
-| `PARSE`      | Malformed JSON in persisted config file                         | `{ path: string }`         |
-| `IO`         | Filesystem read, write, or delete failure                       | `{ path, operation }`      |
-| `VALIDATION` | Config fails validator on read, write, update, or patch         | `{ operation, issues }`    |
+| Code         | When                                                    | Details                 |
+| ------------ | ------------------------------------------------------- | ----------------------- |
+| `PATH`       | Invalid `dirPath`, invalid `name`, unsupported platform | `{ path: string }`      |
+| `PARSE`      | Malformed JSON in persisted config file                 | `{ path: string }`      |
+| `IO`         | Filesystem read, write, or delete failure               | `{ path, operation }`   |
+| `VALIDATION` | Config fails validator on read, write, update, or patch | `{ operation, issues }` |
 
 ### Catching errors by code
 
@@ -459,10 +527,11 @@ import type {
   CreateStoreOptions,
   Store,
   StoreUpdater,
+  FieldDef,
+  FieldsDef,
+  InferStoreConfig,
   StoreValidator,
   StoreValidatorResult,
-  StoreValidatorSuccess,
-  StoreValidatorFailure,
   StoreValidatorIssue,
   StoreErrorCode,
   StoreValidationIssue,
@@ -471,21 +540,22 @@ import type {
 } from "@crustjs/store";
 ```
 
-| Type                      | Description                                                             |
-| ------------------------- | ----------------------------------------------------------------------- |
-| `CreateStoreOptions`      | Options object for `createStore()`.                                     |
-| `Store`                   | Store instance with `read`, `write`, `update`, `patch`, `reset`.        |
-| `StoreUpdater`            | Updater function type `(current: T) => T`.                              |
-| `StoreValidator`          | Validator function contract `(value: unknown) => StoreValidatorResult`. |
-| `StoreValidatorResult`    | Discriminated union: `StoreValidatorSuccess \| StoreValidatorFailure`.  |
-| `StoreValidatorSuccess`   | `{ ok: true, value: T }`.                                              |
-| `StoreValidatorFailure`   | `{ ok: false, issues: StoreValidatorIssue[] }`.                        |
-| `StoreValidatorIssue`     | `{ message: string, path: string }`.                                   |
-| `StoreValidationIssue`    | Validation issue in error details payload.                              |
-| `ValidationErrorDetails`  | Error details for `VALIDATION` code: `{ operation, issues }`.          |
-| `StoreErrorCode`          | Union of error codes: `"PATH" \| "PARSE" \| "IO" \| "VALIDATION"`.    |
-| `PlatformEnv`             | Injectable platform environment for testing path helpers.               |
-| `CrustStoreError`         | Typed error class with `code`, `details`, and `cause`.                  |
+| Type                     | Description                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `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: `{ 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 }`.                                  |
+| `StoreErrorCode`         | Union of error codes: `"PATH" \| "PARSE" \| "IO" \| "VALIDATION"`.                             |
+| `PlatformEnv`            | Injectable platform environment for testing path helpers.                                      |
+| `CrustStoreError`        | Typed error class with `code`, `details`, and `cause`.                                         |
 
 ## Scope & Non-Goals
 

package/dist/index.d.ts

@@ -1,94 +1,172 @@
+/** 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`).
+	*
+	* Return shapes:
+	* - `void` (or `Promise<void>`) — validation-only; the input value is
+	*   persisted as-is. This is the contract for hand-rolled validators.
+	* - `{ value }` (or `Promise<{ value }>`) — the schema (or transform)
+	*   produced an output value (typed as `unknown` because schema
+	*   transforms may emit a value of a different runtime type than
+	*   `V`; the read-stability guard enforces shape correctness at
+	*   write time). On `write` / `update` / `patch`, the transformed
+	*   value replaces the input before persistence and is re-validated
+	*   once to catch read-unstable transforms (cross-type transforms
+	*   whose output would fail the schema on the next read). On `read`,
+	*   the transformed value is discarded — reads always return the
+	*   on-disk value verbatim.
+	* - Throwing an error — the value is rejected; the error message is
+	*   captured as a validation issue with the field name as `path`.
+	*
+	* @param value - The field value to validate.
+	*/
+	validate?: (value: V) => void | Promise<void> | {
+		value: unknown;
+	} | Promise<{
+		value: unknown;
+	}>;
+}
+/** 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 +185,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.
-	*
-	* 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";
+	* Field definitions that declare the store's config schema.
 	*
-	* 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 +200,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 +208,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.
@@ -287,6 +335,18 @@ interface ValidationErrorDetails {
 	issues: readonly StoreValidatorIssue[];
 }
 /**
+* Contextual details attached to a `DEFINITION` error.
+*
+* Returned when a `field()` call cannot produce a valid `FieldDef` from the
+* provided schema and options — e.g. the input is not a Standard Schema v1
+* object, or the schema is of an unknown vendor and `opts.type` was not
+* supplied so the runtime CLI type cannot be inferred.
+*/
+interface DefinitionErrorDetails {
+	/** The schema vendor name, when the failing input was a Standard Schema. */
+	vendor?: string;
+}
+/**
 * Maps each {@link StoreErrorCode} to its structured details type.
 *
 * Used internally for conditional constructor parameters and type narrowing.
@@ -296,6 +356,7 @@ interface StoreErrorDetailsMap {
 	PARSE: ParseErrorDetails;
 	IO: IOErrorDetails;
 	VALIDATION: ValidationErrorDetails;
+	DEFINITION: DefinitionErrorDetails;
 }
 /**
 * All possible error codes emitted by `@crustjs/store`.
@@ -304,6 +365,7 @@ interface StoreErrorDetailsMap {
 * - `PARSE` — Malformed JSON in persisted config file
 * - `IO` — Filesystem read, write, or delete failure
 * - `VALIDATION` — Config object rejected by a store validator
+* - `DEFINITION` — `field()` cannot produce a valid `FieldDef` from the given schema/options
 *
 * @example
 * ```ts
@@ -391,6 +453,178 @@ declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends
 	*/
 	withCause(cause: unknown): this;
 }
+import { InferOutput, StandardSchema } from "@crustjs/schema-utils";
+/**
+* Optional overrides for the introspected `FieldDef` shape produced by
+* {@link field}.
+*
+* Every key is optional. When automatic introspection covers a field
+* (`type`, `description`, `default`, `array`), explicit values override
+* the introspection silently. For schemas with unknown vendors (e.g.
+* Valibot, ArkType), `type` MUST be supplied explicitly because no
+* inference is available.
+*
+* No `validate` key — validation flows exclusively through the schema.
+* If extra checks are needed, refine the schema with `.refine(...)`
+* (Zod), `Schema.filter(...)` (Effect), etc.
+*
+* @typeParam T - The schema's output value type. Used to type-tighten the
+*               `default` key when the user wants a non-`undefined` field.
+*/
+interface FieldOptions<T = unknown> {
+	type?: "string" | "number" | "boolean";
+	description?: string;
+	/**
+	* Default value for this field when the persisted state does not contain
+	* a value for it. Passing `default` explicitly here narrows the inferred
+	* config type from `T | undefined` to `T`. Schema-derived defaults
+	* (e.g. `z.string().default("x")`) populate the runtime default but do
+	* NOT narrow the TypeScript type — pass it explicitly here for tight
+	* typing.
+	*/
+	default?: T;
+	/** Mark this field as an array (collects values into an array). */
+	array?: true;
+}
+type ValueType2 = "string" | "number" | "boolean";
+type StripUndefined<T> = Exclude<T, undefined>;
+type PrimitiveToValueType<T> = [T] extends [string] ? "string" : [T] extends [number] ? "number" : [T] extends [boolean] ? "boolean" : ValueType2;
+/**
+* Resolve the runtime CLI value-type from a Standard Schema's output type.
+*
+* Array schemas are detected via `IsArrayOutput`; their element type drives
+* the value-type literal so `field(z.array(z.string()))` resolves to
+* `{ type: "string"; array: true }`.
+*/
+type IsArrayOutput<S> = S extends StandardSchema<infer _I, infer Out> ? StripUndefined<Out> extends readonly unknown[] ? true : false : false;
+type ArrayElementOutput<S> = S extends StandardSchema<infer _I, infer Out> ? StripUndefined<Out> extends readonly (infer E)[] ? E : never : never;
+type ResolveScalarType<S> = S extends StandardSchema<infer _I, infer Out> ? PrimitiveToValueType<StripUndefined<Out>> : ValueType2;
+/** A scalar `FieldDef` with no narrowed default. */
+type ScalarFieldDef<T extends ValueType2> = {
+	readonly type: T;
+	readonly description?: string;
+	readonly validate: (value: unknown) => Promise<{
+		value: unknown;
+	}>;
+};
+/** A scalar `FieldDef` with a narrowed default. */
+type ScalarFieldDefWithDefault<
+	T extends ValueType2,
+	D
+> = {
+	readonly type: T;
+	readonly description?: string;
+	readonly default: D;
+	readonly validate: (value: unknown) => Promise<{
+		value: unknown;
+	}>;
+};
+/** An array `FieldDef` with no narrowed default. */
+type ArrayFieldDef<T extends ValueType2> = {
+	readonly type: T;
+	readonly array: true;
+	readonly description?: string;
+	readonly validate: (value: unknown) => Promise<{
+		value: unknown;
+	}>;
+};
+/** An array `FieldDef` with a narrowed default. */
+type ArrayFieldDefWithDefault<
+	T extends ValueType2,
+	D
+> = {
+	readonly type: T;
+	readonly array: true;
+	readonly description?: string;
+	readonly default: D;
+	readonly validate: (value: unknown) => Promise<{
+		value: unknown;
+	}>;
+};
+/**
+* `FieldDef` inferred from a Standard Schema, with no narrowed default.
+*
+* Schema-derived defaults are populated at runtime but do NOT narrow the
+* TypeScript type — Standard Schema v1 has no spec-portable type-level
+* access to defaults. Pass `field(schema, { default: x })` explicitly to
+* narrow.
+*/
+type SchemaFieldDef<S extends StandardSchema> = IsArrayOutput<S> extends true ? ArrayFieldDef<PrimitiveToValueType<StripUndefined<ArrayElementOutput<S>>>> : ScalarFieldDef<ResolveScalarType<S>>;
+/**
+* `FieldDef` inferred from a Standard Schema, with the explicit `opts.default`
+* narrowed into the type.
+*/
+type SchemaFieldDefWithDefault<
+	S extends StandardSchema,
+	D
+> = IsArrayOutput<S> extends true ? ArrayFieldDefWithDefault<PrimitiveToValueType<StripUndefined<ArrayElementOutput<S>>>, D> : ScalarFieldDefWithDefault<ResolveScalarType<S>, D>;
+/**
+* Define a `@crustjs/store` field from any Standard Schema v1.
+*
+* Returns a value that satisfies store's `FieldDef` discriminated union.
+* Auto-derives `type`, `array`, `description`, and `default` from the
+* schema (Zod and Effect natively; Valibot/ArkType via the
+* `validate(undefined)` fallback for defaults). Pass `opts` to override
+* any key explicitly — explicit values win silently.
+*
+* The returned `validate` is an async function that throws an `Error` with
+* the schema's normalized issue messages on failure (matches store's
+* `FieldDef.validate` contract).
+*
+* **Type-level defaults**: schema-derived defaults populate at runtime but
+* do NOT narrow the inferred config type. For tight typing of
+* default-bearing fields, pass `default` via `opts`:
+*
+* ```ts
+* field(z.string().default("x"))                       // state: string | undefined
+* field(z.string(), { default: "x" })                  // state: string
+* ```
+*
+* @param schema - Any Standard Schema v1 object (Zod schemas natively;
+*                 Effect schemas wrapped via `Schema.standardSchemaV1`;
+*                 Valibot/ArkType/Sury/etc. as-is)
+* @param opts - Optional store-field metadata; explicit keys override
+*                   the introspected values silently
+* @throws {CrustStoreError} With code `"DEFINITION"` when the input is not
+*         a Standard Schema, or when the runtime CLI type cannot be inferred
+*         and `opts.type` was not supplied.
+*
+* @example Zod
+* ```ts
+* import { z } from "zod";
+* import { createStore, configDir, field } from "@crustjs/store";
+*
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   fields: {
+*     theme: field(z.enum(["light", "dark"]).default("light")),
+*     verbose: field(z.boolean().default(false)),
+*     tags: field(z.array(z.string()).default([])),
+*   },
+* });
+* ```
+*
+* @example Effect
+* ```ts
+* import * as Schema from "effect/Schema";
+* import { createStore, configDir, field } from "@crustjs/store";
+*
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   fields: {
+*     theme: field(Schema.standardSchemaV1(Schema.Literal("light", "dark"))),
+*   },
+* });
+* ```
+*/
+declare function field<S extends StandardSchema>(schema: S): SchemaFieldDef<S>;
+declare function field<
+	S extends StandardSchema,
+	D extends InferOutput<S>
+>(schema: S, opts: FieldOptions<InferOutput<S>> & {
+	default: D;
+}): SchemaFieldDefWithDefault<S, D>;
+declare function field<S extends StandardSchema>(schema: S, opts: FieldOptions<InferOutput<S>>): SchemaFieldDef<S>;
 /**
 * Encapsulates runtime environment values needed for path resolution.
 *
@@ -510,13 +744,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 +762,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, field, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldOptions, FieldDef, DefinitionErrorDetails, 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 W extends Error{code;details;cause;constructor(q,H,G){super(H);this.name="CrustStoreError",this.code=q,this.details=G}is(q){return this.code===q}withCause(q){return this.cause=q,this}}import{extractDefault as m,inferOptions as d,isStandardSchema as p,normalizeStandardIssues as o}from"@crustjs/schema-utils";function n(q){return async(H)=>{let G=await q["~standard"].validate(H);if(G.issues){let L=o(G.issues).map((Q)=>Q.path?`${Q.path}: ${Q.message}`:Q.message);throw Error(L.join("; "))}return{value:G.value}}}function i(q,H){if(!p(q))throw new W("DEFINITION",`field(): argument must be a Standard Schema v1 object (got ${typeof q})`,{});let G=q["~standard"]?.vendor??"unknown",K=`field (vendor: "${G}")`,L=d(q,"field",K),Q=H?.type??L.type;if(!Q)throw new W("DEFINITION",`${K}: unable to infer field type from schema. Pass an explicit { type: "string" | "number" | "boolean" } in options. If this is an Effect schema, wrap it with Schema.standardSchemaV1(...) before passing it here.`,{vendor:G});let J=H?.array===!0||L.multiple===!0,V=H?.description??L.description,x=H&&"default"in H?{ok:!0,value:H.default}:m(q),T=n(q),O={type:Q,validate:T};if(J)O.array=!0;if(V!==void 0)O.description=V;if(x.ok)O.default=x.value;return O}import{homedir as l}from"os";import{join as B}from"path";var s="config";function U(){return{platform:process.platform,env:process.env,homedir:l()}}function j(q){if(!q||q.trim().length===0)throw new W("PATH","appName must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new W("PATH","appName must not contain path separators",{path:q})}function t(q){if(!q||q.trim().length===0)throw new W("PATH","name must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new W("PATH","name must not contain path separators",{path:q});if(q.endsWith(".json"))throw new W("PATH","name must not include the .json extension",{path:q})}function r(q){if(!q||q.trim().length===0)throw new W("PATH","dirPath must be a non-empty string",{path:q??""});if(!(q.startsWith("/")||/^[A-Za-z]:[/\\]/.test(q)))throw new W("PATH","dirPath must be an absolute path",{path:q});if(q.endsWith(".json"))throw new W("PATH","dirPath must be a directory path, not a file path (should not end with .json)",{path:q})}function C(q,H,G,K){let L=q.env[H],Q=L&&L.trim().length>0?L:B(q.homedir,...G);return B(Q,K)}function D(q){throw new W("PATH",`Unsupported platform: ${q}`,{path:q})}function a(q,H){j(q);let G=H??U();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_CONFIG_HOME",[".config"],q);case"win32":{let K=G.env.APPDATA,L=K&&K.trim().length>0?K:B(G.homedir,"AppData","Roaming");return B(L,q)}default:D(G.platform)}}function e(q,H){j(q);let G=H??U();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_DATA_HOME",[".local","share"],q);case"win32":{let K=G.env.LOCALAPPDATA,L=K&&K.trim().length>0?K:B(G.homedir,"AppData","Local");return B(L,q,"Data")}default:D(G.platform)}}function qq(q,H){j(q);let G=H??U();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_STATE_HOME",[".local","state"],q);case"win32":{let K=G.env.LOCALAPPDATA,L=K&&K.trim().length>0?K:B(G.homedir,"AppData","Local");return B(L,q,"State")}default:D(G.platform)}}function Gq(q,H){j(q);let G=H??U();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_CACHE_HOME",[".cache"],q);case"win32":{let K=G.env.LOCALAPPDATA,L=K&&K.trim().length>0?K:B(G.homedir,"AppData","Local");return B(L,q,"Cache")}default:D(G.platform)}}function S(q,H){r(q);let G=H??s;if(H!==void 0)t(H);return B(q,`${G}.json`)}function w(q,H,G=!0){let K={};for(let[L,Q]of Object.entries(H))if(q&&L in q){let J=q[L];K[L]=Array.isArray(J)?[...J]:J}else if("default"in Q&&Q.default!==void 0)K[L]=Array.isArray(Q.default)?[...Q.default]:Q.default;if(!G&&q!==void 0){for(let[L,Q]of Object.entries(q))if(!(L in H))K[L]=Array.isArray(Q)?[...Q]:Q}return K}import{randomUUID as Hq}from"crypto";import{mkdir as Kq,readFile as Lq,rename as Qq,rm as Wq,unlink as Xq,writeFile as Yq}from"fs/promises";import{dirname as Zq,join as $q}from"path";async function y(q){let H;try{H=await Lq(q,"utf-8")}catch(G){if(E(G))return;throw new W("IO",`Failed to read config file: ${q}`,{path:q,operation:"read"}).withCause(G)}try{return JSON.parse(H)}catch(G){throw new W("PARSE",`Malformed JSON in config file: ${q}`,{path:q}).withCause(G)}}async function z(q,H){let G=Zq(q),K=$q(G,`.config-${Hq()}.tmp`);try{await Kq(G,{recursive:!0})}catch(L){throw new W("IO",`Failed to create config directory: ${G}`,{path:q,operation:"write"}).withCause(L)}try{let L=JSON.stringify(H,null,"\t");await Yq(K,L,"utf-8")}catch(L){throw await g(K),new W("IO",`Failed to write config file: ${q}`,{path:q,operation:"write"}).withCause(L)}try{await Qq(K,q)}catch(L){throw await g(K),new W("IO",`Failed to finalize config file: ${q}`,{path:q,operation:"write"}).withCause(L)}}async function k(q){try{await Xq(q)}catch(H){if(E(H))return;throw new W("IO",`Failed to delete config file: ${q}`,{path:q,operation:"delete"}).withCause(H)}}function E(q){return q!==null&&typeof q==="object"&&"code"in q&&q.code==="ENOENT"}async function g(q){try{await Wq(q,{force:!0})}catch{}}function N(q){return typeof q==="object"&&q!==null&&"value"in q&&!("ok"in q)}function Mq(q){let{dirPath:H,name:G,fields:K,pruneUnknown:L}=q,Q=S(H,G),J=L??!0;function V(X,Z){if(Z==="number"&&typeof X==="string"){let Y=Number(X);return Number.isNaN(Y)?X:Y}if(Z==="boolean"&&typeof X==="string")return X==="true"||X==="1";return X}function x(X){let Y={...X};for(let[$,M]of Object.entries(K)){if(!($ in Y))continue;let I=Y[$];if(M.array===!0&&Array.isArray(I)){Y[$]=I.map((_)=>V(_,M.type));continue}Y[$]=V(I,M.type)}return Y}async function T(X,Z){let Y=[],$=X;for(let[M,I]of Object.entries(K)){if(!I.validate)continue;let _=$[M];if(_===void 0)continue;let R;try{R=await I.validate(_)}catch(F){let b=F instanceof Error?F.message:"Validation failed";Y.push({message:b,path:M});continue}if(R===void 0)continue;if(N(R)){let F=R.value;if(Z==="read")continue;if(!Bun.deepEquals(F,_)){let b;try{b=await I.validate(F)}catch(A){let u=A instanceof Error?A.message:"re-validation failed";Y.push({message:`read-unstable transform: ${u}`,path:M});continue}if(b!==void 0&&(!N(b)||!Bun.deepEquals(b.value,F))){Y.push({message:"read-unstable transform: output would be transformed again on re-read",path:M});continue}$[M]=F}continue}throw TypeError("FieldDef.validate must return void or { value } (see @crustjs/store validation docs).")}if(Y.length>0){let M=Y.map((_)=>`  - ${_.path}: ${_.message}`),I=`Store validation failed (${Z})
+${M.join(`
+`)}`;throw new W("VALIDATION",I,{operation:Z,issues:Y})}}async function O(){let X=await y(Q),Z=w(X,K,J);return x(Z)}async function P(){let X=await O();return await T(X,"read"),X}async function c(X){let Z=x(X);await T(Z,"write"),await z(Q,Z)}async function f(X){let Z=await O(),Y=X(Z),$=x(Y);await T($,"update"),await z(Q,$)}async function h(X){let Y={...await O(),...X},$=x(Y);await T($,"patch"),await z(Q,$)}async function v(){await k(Q)}return{read:P,write:c,update:f,patch:h,reset:v}}export{qq as stateDir,i as field,e as dataDir,Mq as createStore,a as configDir,Gq as cacheDir,W as CrustStoreError};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/store",
-	"version": "0.0.3",
+	"version": "0.1.0",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"license": "MIT",
@@ -42,13 +42,19 @@
 		"build": "bunup",
 		"dev": "bunup --watch",
 		"check:types": "tsc --noEmit",
-		"test": "bun test"
+		"test": "bun test",
+		"publish": "bun publish --no-git-checks || true"
 	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
-		"bunup": "^0.16.29"
+		"bunup": "^0.16.31",
+		"effect": "3.14.2",
+		"zod": "^4.0.0"
 	},
 	"peerDependencies": {
-		"typescript": "^5"
+		"typescript": "^6.0.3"
+	},
+	"dependencies": {
+		"@crustjs/schema-utils": "0.0.1"
 	}
 }