@crustjs/store 0.0.2 → 0.0.3

package/README.md

@@ -1,8 +1,8 @@
 # @crustjs/store
 
-Minimal, DX-first, type-safe config persistence for CLI apps.
+DX-first, typed persistence for CLI apps with clear config/data/state/cache separation.
 
-`@crustjs/store` gives your CLI a production-ready config store with near-zero setup. Declare your fields, get full type inference, and let the store handle path resolution, file IO, defaults, and error mapping.
+`@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.
 
 ## Install
 
@@ -26,156 +26,213 @@ import { createStore, configDir } from "@crustjs/store";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
-  fields: {
-    theme: { type: "string", default: "light" },
-    verbose: { type: "boolean", default: false },
-    token: { type: "string" }, // optional — no default
+  defaults: {
+    ui: { theme: "light" as string, fontSize: 14 },
+    verbose: false,
   },
 });
 
-// Read config (returns defaults when no persisted file exists)
-const config = await store.read();
-// → { theme: "light", verbose: false, token: undefined }
+// Read state (returns defaults when no persisted file exists)
+const state = await store.read();
+// → { ui: { theme: "light", fontSize: 14 }, verbose: false }
 
-// Write a full config object
-await store.write({ theme: "dark", verbose: true, token: "abc123" });
+// Write a full state object
+await store.write({ ui: { theme: "dark", fontSize: 16 }, verbose: true });
 
-// Update a single field
+// Update with a function
 await store.update((current) => ({ ...current, verbose: false }));
 
+// Patch only specific nested keys
+await store.patch({ ui: { theme: "solarized" } });
+
 // Reset to defaults (removes persisted file)
 await store.reset();
 ```
 
-No explicit generics needed — types are inferred from your field definitions.
+No explicit generics needed — types are inferred from your `defaults` object.
+
+## 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            |
+
+```ts
+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 },
+});
+
+// App data → ~/.local/share/my-cli/config.json
+const data = createStore({
+  dirPath: dataDir("my-cli"),
+  defaults: { bookmarks: [] as string[] },
+});
+
+// Runtime state → ~/.local/state/my-cli/config.json
+const state = createStore({
+  dirPath: stateDir("my-cli"),
+  defaults: { lastOpened: "" as string, scrollY: 0 },
+});
+
+// Cache → ~/.cache/my-cli/config.json
+const cache = createStore({
+  dirPath: cacheDir("my-cli"),
+  defaults: { etag: "" as string, payload: "" as string },
+});
+```
+
+### Platform Paths
+
+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`    |
+
+macOS uses XDG conventions (same as Linux) for a unified Unix mental model.
 
 ## API
 
 ### `createStore(options)`
 
-Creates a typed async config store backed by a local JSON file. The file path is resolved once at creation time.
+Creates a typed async store backed by a local JSON file. The file path is resolved once at creation time.
 
 ```ts
 const store = createStore(options);
 ```
 
-**Returns:** A `Store<TConfig>` with `read()`, `write()`, `update()`, and `reset()` methods.
+**Returns:** A `Store<T>` with `read()`, `write()`, `update()`, `patch()`, and `reset()` methods.
 
 **Throws:** `CrustStoreError` with `PATH` code if `dirPath` or `name` is invalid.
 
 #### 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`).  |
-| `fields`  | `FieldsDef`| Yes      | Field definitions that declare the config schema.                  |
+| 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`).              |
 
-### `configDir(appName, env?)`
+### `store.read()`
 
-Resolves the platform-standard config directory for the given app name.
+Reads the persisted state file. Missing keys are filled from `defaults` via deep merge. When no file exists, returns `defaults`.
 
 ```ts
-import { configDir } from "@crustjs/store";
-
-const dir = configDir("my-cli");
-// → "/home/user/.config/my-cli"       (Linux)
-// → "/Users/user/Library/Application Support/my-cli"  (macOS)
-// → "C:\\Users\\user\\AppData\\Roaming\\my-cli"       (Windows)
+const state = await store.read();
 ```
 
-Use it with `dirPath`:
+Always returns a value — never `undefined`. Does not write merged defaults back to disk.
+
+### `store.write(state)`
+
+Atomically persists a full state object. The entire previous state is replaced.
 
 ```ts
-const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: { /* ... */ },
-});
+await store.write({ ui: { theme: "dark", fontSize: 14 }, verbose: true });
 ```
 
-### Field Definitions
+Calls `validator` (if provided) before writing. Parent directories are created if missing.
 
-Each field in the `fields` record is a `FieldDef` with a `type` discriminant:
+### `store.update(updater)`
 
-| Property      | Type                                    | Required | Description                                         |
-| ------------- | --------------------------------------- | -------- | --------------------------------------------------- |
-| `type`        | `"string" \| "number" \| "boolean"`    | Yes      | The value type.                                     |
-| `default`     | Matches `type`                          | No       | Default value when the field is not persisted.       |
-| `array`       | `true`                                  | No       | Collect values into an array.                        |
-| `description` | `string`                                | No       | Human-readable description for tooling.              |
+Reads the current effective state, applies the updater function, and atomically persists the result.
 
-Type inference rules:
+```ts
+await store.update((current) => ({
+  ...current,
+  ui: { ...current.ui, theme: "dark" },
+}));
+```
 
-- **Has `default`** → field is guaranteed present (e.g., `string`)
-- **No `default`** → field is optional (e.g., `string | undefined`)
-- **`array: true`** → wraps the type in an array (e.g., `string[]`)
+When no persisted file exists, the updater receives `defaults` as the current value. Calls `validator` 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.
 
 ```ts
-const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme:   { type: "string", default: "light" },       // → string
-    verbose: { type: "boolean", default: false },         // → boolean
-    retries: { type: "number", default: 3 },              // → number
-    token:   { type: "string" },                          // → string | undefined
-    tags:    { type: "string", array: true, default: [] },// → string[]
-    ids:     { type: "number", array: true },             // → number[] | undefined
-  },
-});
+await store.patch({ ui: { theme: "solarized" } });
 ```
 
-### `store.read()`
+Arrays are replaced wholesale (not merged element-by-element). Calls `validator` before writing.
 
-Reads the persisted config file. Missing fields are filled from their `default` values. Fields without defaults are `undefined` when not persisted.
+### `store.reset()`
+
+Removes the persisted state file. After reset, `read()` returns `defaults`.
 
 ```ts
-const config = await store.read();
+await store.reset();
 ```
 
-Always returns a value — never `undefined`.
+Reset is idempotent — calling it when no file exists is a no-op.
+
+### Path Helpers
 
-### `store.write(config)`
+#### `configDir(appName, env?)`
 
-Atomically persists a full config object. The entire previous config is replaced.
+Resolves the platform-standard config directory for the given app name.
 
 ```ts
-await store.write({ theme: "dark", verbose: true, token: "abc123" });
+import { configDir } from "@crustjs/store";
+
+const dir = configDir("my-cli");
+// → "/home/user/.config/my-cli"       (Linux / macOS)
+// → "C:\\Users\\user\\AppData\\Roaming\\my-cli"       (Windows)
 ```
 
-### `store.update(updater)`
+#### `dataDir(appName, env?)`
 
-Reads the current effective config, applies the updater function, and atomically persists the result.
+Resolves the platform-standard data directory.
 
 ```ts
-await store.update((current) => ({
-  ...current,
-  theme: "dark",
-}));
-```
+import { dataDir } from "@crustjs/store";
 
-When no persisted file exists, the updater receives field defaults as the current value.
+const dir = dataDir("my-cli");
+// → "/home/user/.local/share/my-cli"   (Linux / macOS)
+// → "C:\\Users\\user\\AppData\\Local\\my-cli\\Data"    (Windows)
+```
 
-### `store.reset()`
+#### `stateDir(appName, env?)`
 
-Removes the persisted config file. After reset, `read()` returns field defaults.
+Resolves the platform-standard state directory.
 
 ```ts
-await store.reset();
+import { stateDir } from "@crustjs/store";
+
+const dir = stateDir("my-cli");
+// → "/home/user/.local/state/my-cli"   (Linux / macOS)
+// → "C:\\Users\\user\\AppData\\Local\\my-cli\\State"   (Windows)
 ```
 
-Reset is idempotent — calling it when no file exists is a no-op.
+#### `cacheDir(appName, env?)`
 
-## Config File Path
+Resolves the platform-standard cache directory.
 
-`configDir()` resolves the platform-standard config directory. The `name` option defaults to `"config"`, producing `config.json`:
+```ts
+import { cacheDir } from "@crustjs/store";
 
-| Platform | Default Path                                            | Env Override       |
-| -------- | ------------------------------------------------------- | ------------------ |
-| Linux    | `~/.config/<appName>/<name>.json`                       | `$XDG_CONFIG_HOME` |
-| macOS    | `~/Library/Application Support/<appName>/<name>.json`   | —                  |
-| Windows  | `%APPDATA%\<appName>\<name>.json`                       | `%APPDATA%`        |
+const dir = cacheDir("my-cli");
+// → "/home/user/.cache/my-cli"         (Linux / macOS)
+// → "C:\\Users\\user\\AppData\\Local\\my-cli\\Cache"   (Windows)
+```
+
+All path helpers accept an optional `PlatformEnv` parameter for deterministic testing without mutating `process.env`.
 
-### Multiple Stores
+## Multiple Stores
 
 Use the `name` option to create multiple stores under the same directory:
 
@@ -185,11 +242,11 @@ import { createStore, configDir } from "@crustjs/store";
 const dir = configDir("my-cli");
 
 // Default store → ~/.config/my-cli/config.json
-const configStore = createStore({
+const settingsStore = createStore({
   dirPath: dir,
-  fields: {
-    theme: { type: "string", default: "light" },
-    verbose: { type: "boolean", default: false },
+  defaults: {
+    ui: { theme: "light" as string, fontSize: 14 },
+    verbose: false,
   },
 });
 
@@ -197,9 +254,7 @@ const configStore = createStore({
 const authStore = createStore({
   dirPath: dir,
   name: "auth",
-  fields: {
-    token: { type: "string" },
-  },
+  defaults: { token: "" as string },
 });
 ```
 
@@ -209,45 +264,144 @@ The `name` must not contain path separators or the `.json` extension.
 
 ## Defaults & Merge
 
-When a persisted file exists, `read()` applies field defaults for any missing keys:
+When a persisted file exists, `read()` deep-merges defaults for any missing keys:
 
 ```ts
 const store = createStore({
   dirPath: configDir("my-cli"),
-  fields: {
-    theme: { type: "string", default: "light" },
-    verbose: { type: "boolean", default: false },
-    retries: { type: "number", default: 3 },
+  defaults: {
+    ui: { theme: "light", fontSize: 14 },
+    verbose: false,
   },
 });
 
-// Persisted file contains: { "theme": "dark" }
-const config = await store.read();
-// → { theme: "dark", verbose: false, retries: 3 }
+// Persisted file contains: { "ui": { "theme": "dark" }, "verbose": true }
+const state = await store.read();
+// → { ui: { theme: "dark", fontSize: 14 }, verbose: true }
 ```
 
-### Merge rules
+### Merge Rules
 
-- Fields present in the persisted file use the persisted value.
-- Missing fields with a `default` use the default value.
-- Missing fields without a `default` are omitted (typed as `T | undefined`).
-- Extra keys in the persisted file that are not defined in `fields` are dropped.
-- Array defaults are shallow-copied to prevent shared mutation.
+- 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.
+- 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.
 
 ### Important: defaults are not auto-persisted
 
-Merged defaults exist only in memory. The merged result is **not** written back to disk. The persisted file remains unchanged until you explicitly call `write()` or `update()`.
+Merged defaults exist only in memory. The persisted file remains unchanged until you explicitly call `write()`, `update()`, or `patch()`.
+
+## 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.
+
+### Using `@crustjs/validate`
+
+The easiest way to add validation is with store adapters from `@crustjs/validate`:
+
+```ts
+import { z } from "zod";
+import { storeValidator } 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(),
+    }),
+  ),
+});
+
+// write() validates before persisting
+await store.write({ theme: "neon", verbose: true });
+// → throws CrustStoreError("VALIDATION")
+
+// read() validates after applying defaults
+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()`:
+
+```ts
+import * as Schema from "effect/Schema";
+import { storeValidator } 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") }),
+    ),
+  ),
+});
+```
+
+### Custom validators
+
+You can also provide a validator function directly without `@crustjs/validate`:
+
+```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 };
+};
+```
+
+The `StoreValidator<T>` contract is `(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.
+- **Reset**: No validation — just removes the persisted file.
+
+### Catching validation errors
+
+```ts
+import { CrustStoreError } from "@crustjs/store";
+
+try {
+  await store.read();
+} catch (err) {
+  if (err instanceof CrustStoreError && err.is("VALIDATION")) {
+    // err.details is { operation: "read" | "write" | "update" | "patch", issues: StoreValidationIssue[] }
+    console.error(`Validation failed during ${err.details.operation}:`);
+    for (const issue of err.details.issues) {
+      console.error(`  ${issue.path || "(root)"}: ${issue.message}`);
+    }
+  }
+}
+```
 
 ## Error Handling
 
 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 }`      |
+| 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
 
@@ -255,12 +409,12 @@ All errors thrown by `@crustjs/store` are instances of `CrustStoreError` with a
 import { CrustStoreError } from "@crustjs/store";
 
 try {
-  const config = await store.read();
+  const state = await store.read();
 } catch (err) {
   if (err instanceof CrustStoreError) {
     switch (err.code) {
       case "PARSE":
-        console.error(`Corrupt config at ${err.details.path}`);
+        console.error(`Corrupt file at ${err.details.path}`);
         console.error("Delete the file and retry, or fix the JSON manually.");
         break;
       case "IO":
@@ -287,14 +441,14 @@ if (err instanceof CrustStoreError && err.is("IO")) {
 `CrustStoreError` preserves the original error as `cause` for debugging:
 
 ```ts
-if (err instanceof CrustStoreError && err.is("PARSE")) {
-  console.error("Original parse error:", err.cause);
+if (err instanceof CrustStoreError && err.is("VALIDATION")) {
+  console.error("Validation error:", err.cause);
 }
 ```
 
 ### Malformed JSON
 
-`@crustjs/store` does **not** silently recover from malformed JSON. If the persisted config file contains invalid JSON, `read()` throws a `CrustStoreError` with `PARSE` code immediately — no fallback to defaults.
+`@crustjs/store` does **not** silently recover from malformed JSON. If the persisted file contains invalid JSON, `read()` throws a `CrustStoreError` with `PARSE` code immediately — no fallback to defaults.
 
 ## Types
 
@@ -303,38 +457,47 @@ All types are exported for use in your application:
 ```ts
 import type {
   CreateStoreOptions,
-  FieldDef,
-  FieldsDef,
-  InferStoreConfig,
   Store,
   StoreUpdater,
-  ValueType,
+  StoreValidator,
+  StoreValidatorResult,
+  StoreValidatorSuccess,
+  StoreValidatorFailure,
+  StoreValidatorIssue,
   StoreErrorCode,
+  StoreValidationIssue,
+  ValidationErrorDetails,
+  PlatformEnv,
 } from "@crustjs/store";
 ```
 
-| Type                 | Description                                                             |
-| -------------------- | ----------------------------------------------------------------------- |
-| `CreateStoreOptions` | Options object for `createStore()`.                                     |
-| `FieldDef`           | Single field definition (discriminated by `type` and `array`).          |
-| `FieldsDef`          | Record mapping field names to `FieldDef`.                               |
-| `InferStoreConfig`   | Utility type: infers the config shape from a `FieldsDef`.               |
-| `Store`              | Store instance with `read`, `write`, `update`, `reset`.                 |
-| `StoreUpdater`       | Updater function type `(current: TConfig) => TConfig`.                  |
-| `ValueType`          | Supported type literals: `"string" \| "number" \| "boolean"`.          |
-| `StoreErrorCode`     | Union of error codes: `"PATH" \| "PARSE" \| "IO"`.                    |
-
-## v1 Scope & Non-Goals
-
-`@crustjs/store` v1 is intentionally minimal. The following are **not** included:
-
-- **Generic state/cache abstractions** — v1 is config-only (single typed object per 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`.                  |
+
+## Scope & Non-Goals
+
+`@crustjs/store` is intentionally focused. The following are **not** included:
+
+- **Cross-process locking** — assumes single-process usage for write coordination.
 - **Built-in encryption or keychain integration.**
-- **Cross-process locking** — v1 assumes single-process usage for write coordination.
 - **Sync API variants** (`readSync`, `writeSync`, etc.).
-- **Built-in validation** — will be added later via `@crustjs/validate` integration.
+- **Automatic migration of invalid persisted config** — validation fails loudly; callers handle recovery.
 - **Alternative formats** (YAML, TOML, JSON5) — JSON is the only on-disk format.
-- **Deep `@crustjs/core` integration** — the store is a standalone package.
+- **Remote/cloud synchronization** or multi-device sync.
+- **Domain-specific migration frameworks** beyond simple store-level upgrade hooks.
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,251 @@
 /**
+* Recursively makes all properties of `T` optional.
+*
+* - Plain objects are recursed into — each nested key becomes optional.
+* - Arrays are left as-is (replaced wholesale, not partially updated).
+* - Primitives pass through unchanged.
+*
+* Used by {@link Store.patch} for deep partial updates.
+*
+* @example
+* ```ts
+* type Config = { ui: { theme: string; fontSize: number }; verbose: boolean };
+* type Partial = DeepPartial<Config>;
+* // → { ui?: { theme?: string; fontSize?: number }; verbose?: boolean }
+* ```
+*/
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends Record<string, unknown> ? { [K in keyof T]? : DeepPartial<T[K]> } : T;
+/**
+* Result returned by a {@link StoreValidator} when validation succeeds.
+*
+* Carries the (possibly transformed) config value from the schema.
+*/
+interface StoreValidatorSuccess<T> {
+	readonly ok: true;
+	readonly value: T;
+}
+/**
+* A single validation issue reported by a {@link StoreValidator}.
+*
+* Compatible with the canonical `ValidationIssue` shape used across the Crust
+* validation platform.
+*/
+interface StoreValidatorIssue {
+	/** Human-readable description of the validation failure. */
+	message: string;
+	/** Dot-path to the invalid field, or empty string for root-level issues. */
+	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`.
+*
+* @example
+* ```ts
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   defaults: {
+*     ui: { theme: "light", fontSize: 14 },
+*     verbose: false,
+*     tags: ["default"],
+*   },
+* });
+* ```
+*/
+interface CreateStoreOptions<T extends Record<string, unknown>> {
+	/**
+	* Absolute directory path where the store JSON file is persisted.
+	*
+	* Use a path helper ({@link configDir}, {@link dataDir}, etc.) to resolve
+	* the platform-standard directory from an app name.
+	*/
+	dirPath: string;
+	/**
+	* Store name used as the JSON filename in the directory.
+	*
+	* Defaults to `"config"`, producing `config.json`. Set to a different value
+	* to create multiple stores under the same directory
+	* (e.g. `name: "auth"` → `auth.json`).
+	*
+	* Must not contain path separators or the `.json` extension.
+	*/
+	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";
+	*
+	* const store = createStore({
+	*   dirPath: configDir("my-cli"),
+	*   defaults: { theme: "light", verbose: false },
+	*   validator: storeValidator(z.object({ theme: z.enum(["light", "dark"]) })),
+	* });
+	* ```
+	*/
+	validator?: StoreValidator<T>;
+	/**
+	* When `true` (the default), persisted keys not present in `defaults`
+	* are dropped on read. Set to `false` to preserve unknown keys.
+	*
+	* @default true
+	*/
+	pruneUnknown?: boolean;
+}
+/**
+* Receives the current effective state and returns an updated state.
+*
+* Used by {@link Store.update} to apply mutations atomically.
+*
+* @example
+* ```ts
+* await store.update((current) => ({
+*   ...current,
+*   ui: { ...current.ui, theme: "dark" },
+* }));
+* ```
+*/
+type StoreUpdater<T> = (current: T) => NoInfer<T>;
+/**
+* A typed async 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.
+*
+* @typeParam T - The store data shape, inferred from `defaults`.
+*
+* @example
+* ```ts
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   defaults: {
+*     ui: { theme: "light", fontSize: 14 },
+*     verbose: 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" } });
+* await store.reset();
+* ```
+*/
+interface Store<T> {
+	/**
+	* Reads the persisted state, merging defaults for missing keys.
+	*
+	* Always returns a complete `T` — missing persisted keys are filled
+	* from `defaults`.
+	*
+	* When a validator is configured, the merged config is validated after
+	* defaults are applied. Invalid persisted config fails loudly.
+	*
+	* @returns The effective config value (possibly transformed by the validator).
+	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `VALIDATION` if the config fails validation.
+	* @throws {CrustStoreError} `IO` on filesystem read failures.
+	*/
+	read(): Promise<T>;
+	/**
+	* Atomically persists the full state object.
+	*
+	* When a validator is configured, the config is validated before persistence.
+	*
+	* @param state - The complete state to persist.
+	* @throws {CrustStoreError} `VALIDATION` if the config fails validation.
+	* @throws {CrustStoreError} `IO` on filesystem write failures.
+	*/
+	write(state: NoInfer<T>): 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).
+	*
+	* @param updater - Function receiving current state and returning updated state.
+	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `VALIDATION` if the updated config fails validation.
+	* @throws {CrustStoreError} `IO` on filesystem failures.
+	*/
+	update(updater: StoreUpdater<T>): Promise<void>;
+	/**
+	* Applies a deep partial update to the current state 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.
+	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `IO` on filesystem failures.
+	*/
+	patch(partial: DeepPartial<NoInfer<T>>): Promise<void>;
+	/**
+	* Removes the persisted state file, returning the store to
+	* defaults-on-read behavior.
+	*
+	* @throws {CrustStoreError} `IO` on filesystem deletion failures.
+	*/
+	reset(): Promise<void>;
+}
+/**
 * Contextual details attached to a `PATH` error.
 *
 * Returned when the resolved or provided config file path is invalid.
@@ -28,6 +275,18 @@ interface IOErrorDetails {
 	operation: "read" | "write" | "delete";
 }
 /**
+* Contextual details attached to a `VALIDATION` error.
+*
+* Returned when a store validator rejects a config object during
+* read, write, update, or patch operations.
+*/
+interface ValidationErrorDetails {
+	/** The store operation during which validation failed. */
+	operation: "read" | "write" | "update" | "patch";
+	/** Structured validation issues for programmatic handling. */
+	issues: readonly StoreValidatorIssue[];
+}
+/**
 * Maps each {@link StoreErrorCode} to its structured details type.
 *
 * Used internally for conditional constructor parameters and type narrowing.
@@ -36,6 +295,7 @@ interface StoreErrorDetailsMap {
 	PATH: PathErrorDetails;
 	PARSE: ParseErrorDetails;
 	IO: IOErrorDetails;
+	VALIDATION: ValidationErrorDetails;
 }
 /**
 * All possible error codes emitted by `@crustjs/store`.
@@ -43,6 +303,7 @@ interface StoreErrorDetailsMap {
 * - `PATH` — Invalid or unsupported config file path
 * - `PARSE` — Malformed JSON in persisted config file
 * - `IO` — Filesystem read, write, or delete failure
+* - `VALIDATION` — Config object rejected by a store validator
 *
 * @example
 * ```ts
@@ -56,6 +317,11 @@ interface StoreErrorDetailsMap {
 *       case "PARSE":
 *         console.error(`Corrupt config at ${err.details.path}`);
 *         break;
+*       case "VALIDATION":
+*         for (const issue of err.details.issues) {
+*           console.error(`${issue.path}: ${issue.message}`);
+*         }
+*         break;
 *       case "IO":
 *         console.error(`File ${err.details.operation} failed: ${err.message}`);
 *         break;
@@ -68,7 +334,7 @@ type StoreErrorCode = keyof StoreErrorDetailsMap;
 /** Resolves the details type for a given {@link StoreErrorCode}. */
 type StoreErrorDetails<C extends StoreErrorCode> = StoreErrorDetailsMap[C];
 /**
-* A typed error thrown by `@crustjs/store` for path, parse, and IO failures.
+* A typed error thrown by `@crustjs/store` for path, parse, IO, and validation failures.
 *
 * Every `CrustStoreError` carries a {@link StoreErrorCode} that identifies the failure
 * category, along with structured {@link StoreErrorDetails} for programmatic handling
@@ -143,10 +409,11 @@ interface PlatformEnv {
 * Resolves the platform-standard config directory for the given app.
 *
 * Platform conventions:
-* - **Linux**: `$XDG_CONFIG_HOME/<appName>` or `~/.config/<appName>`
-* - **macOS**: `~/Library/Application Support/<appName>`
+* - **Linux / macOS**: `$XDG_CONFIG_HOME/<appName>` or `~/.config/<appName>`
 * - **Windows**: `%APPDATA%/<appName>` or `~/AppData/Roaming/<appName>`
 *
+* macOS uses XDG conventions for consistency with Linux.
+*
 * @param appName - Application name used as directory name. Must be a non-empty
 *   string without path separators.
 * @param env - Optional platform environment override for testing.
@@ -159,241 +426,99 @@ interface PlatformEnv {
 *
 * const dir = configDir("my-cli");
 * // → "/home/user/.config/my-cli" (Linux)
-* // → "/Users/user/Library/Application Support/my-cli" (macOS)
+* // → "/Users/user/.config/my-cli" (macOS)
 * // → "C:\\Users\\user\\AppData\\Roaming\\my-cli" (Windows)
 * ```
 */
 declare function configDir(appName: string, env?: PlatformEnv): string;
-/** Supported type literals for store fields. */
-type ValueType = "string" | "number" | "boolean";
-/**
-* Resolves a type literal to its corresponding TypeScript primitive type.
-*
-* - `"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 {
-	/** Human-readable description for documentation and tooling. */
-	description?: string;
-}
-/** Base for scalar (non-array) fields — `array` must be omitted. */
-interface ScalarFieldBase extends FieldDefBase {
-	/** Must be omitted for scalar fields — set to `true` for array fields. */
-	array?: never;
-}
-/** A scalar string field. */
-interface StringFieldDef extends ScalarFieldBase {
-	type: "string";
-	/** Default string value when the field is not persisted. */
-	default?: string;
-}
-/** A scalar number field. */
-interface NumberFieldDef extends ScalarFieldBase {
-	type: "number";
-	/** Default number value when the field is not persisted. */
-	default?: number;
-}
-/** A scalar boolean field. */
-interface BooleanFieldDef extends ScalarFieldBase {
-	type: "boolean";
-	/** Default boolean value when the field is not persisted. */
-	default?: boolean;
-}
-/** Base for array fields — `array` is required as `true`. */
-interface ArrayFieldBase extends FieldDefBase {
-	/** Collect values into an array. */
-	array: true;
-}
-/** An array of strings field. */
-interface StringArrayFieldDef extends ArrayFieldBase {
-	type: "string";
-	/** Default string array value when the field is not persisted. */
-	default?: readonly string[];
-}
-/** An array of numbers field. */
-interface NumberArrayFieldDef extends ArrayFieldBase {
-	type: "number";
-	/** Default number array value when the field is not persisted. */
-	default?: readonly number[];
-}
-/** An array of booleans field. */
-interface BooleanArrayFieldDef extends ArrayFieldBase {
-	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.
+* Resolves the platform-standard data directory for the given app.
 *
-* Discriminated by `type` and `array` for type-safe `default` values.
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_DATA_HOME/<appName>` or `~/.local/share/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Data` or `~/AppData/Local/<appName>/Data`
 *
-* @example
-* ```ts
-* const fields = {
-*   theme: { type: "string", default: "light" },
-*   verbose: { type: "boolean", default: false },
-*   tags: { type: "string", array: true, default: [] },
-*   token: { type: "string" },  // optional — no default
-* } satisfies FieldsDef;
-* ```
-*/
-type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef;
-/** Record mapping field names to their definitions. */
-type FieldsDef = Record<string, FieldDef>;
-/**
-* Infer the resolved type for a single field definition.
+* macOS uses XDG conventions for consistency with Linux.
 *
-* - **array** → `primitive[]` (or `primitive[] | undefined` if no default)
-* - **has default** → `primitive` (guaranteed present)
-* - **no default** → `primitive | undefined` (optional)
-*/
-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;
-/**
-* Maps a full {@link FieldsDef} record to the inferred config object type.
+* @param appName - Application name used as directory name. Must be a non-empty
+*   string without path separators.
+* @param env - Optional platform environment override for testing.
+* @returns Absolute path to the app's data directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
 *
 * @example
 * ```ts
-* type Config = InferStoreConfig<{
-*   theme: { type: "string"; default: "light" };
-*   verbose: { type: "boolean" };
-* }>;
-* // → { theme: string; verbose: boolean | undefined }
+* import { dataDir } from "@crustjs/store";
+*
+* const dir = dataDir("my-cli");
+* // → "/home/user/.local/share/my-cli" (Linux)
+* // → "/Users/user/.local/share/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\Data" (Windows)
 * ```
 */
-type InferStoreConfig<F extends FieldsDef> = { [K in keyof F] : InferFieldValue<F[K]> };
+declare function dataDir(appName: string, env?: PlatformEnv): string;
 /**
-* Options for {@link createStore}.
+* Resolves the platform-standard state directory for the given app.
 *
-* @typeParam F - The field definitions record (inferred via `const` generic).
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_STATE_HOME/<appName>` or `~/.local/state/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/State` or `~/AppData/Local/<appName>/State`
 *
-* @example
-* ```ts
-* const store = createStore({
-*   dirPath: configDir("my-cli"),
-*   fields: {
-*     theme: { type: "string", default: "light" },
-*     verbose: { type: "boolean", default: false },
-*   },
-* });
-* ```
-*/
-interface CreateStoreOptions<F extends FieldsDef> {
-	/**
-	* Absolute directory path where the store JSON file is persisted.
-	*
-	* Use the {@link configDir} helper to resolve the platform-standard
-	* config directory from an app name.
-	*/
-	dirPath: string;
-	/**
-	* Store name used as the JSON filename in the directory.
-	*
-	* Defaults to `"config"`, producing `config.json`. Set to a different value
-	* to create multiple stores under the same directory
-	* (e.g. `name: "auth"` → `auth.json`).
-	*
-	* Must not contain path separators or the `.json` extension.
-	*/
-	name?: string;
-	/**
-	* Field definitions that declare the store's config schema.
-	*
-	* Each key maps to a {@link FieldDef} with a `type` discriminant and optional
-	* `default`. Fields without a `default` are optional (`T | undefined`).
-	*/
-	fields: F;
-}
-/**
-* Receives the current effective config and returns an updated config.
+* macOS uses XDG conventions for consistency with Linux.
 *
-* Used by {@link Store.update} to apply partial mutations atomically.
+* @param appName - Application name used as directory name. Must be a non-empty
+*   string without path separators.
+* @param env - Optional platform environment override for testing.
+* @returns Absolute path to the app's state directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
 *
 * @example
 * ```ts
-* await store.update((current) => ({
-*   ...current,
-*   theme: "dark",
-* }));
+* import { stateDir } from "@crustjs/store";
+*
+* const dir = stateDir("my-cli");
+* // → "/home/user/.local/state/my-cli" (Linux)
+* // → "/Users/user/.local/state/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\State" (Windows)
 * ```
 */
-type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
+declare function stateDir(appName: string, env?: PlatformEnv): string;
 /**
-* A typed async config store returned by {@link createStore}.
+* Resolves the platform-standard cache directory for the given app.
 *
-* Provides `read`, `write`, `update`, and `reset` operations for a single
-* typed config object persisted as JSON on the local filesystem.
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_CACHE_HOME/<appName>` or `~/.cache/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Cache` or `~/AppData/Local/<appName>/Cache`
 *
-* @typeParam TConfig - The inferred config shape from field definitions.
+* macOS uses XDG conventions for consistency with Linux.
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   string without path separators.
+* @param env - Optional platform environment override for testing.
+* @returns Absolute path to the app's cache directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
 *
 * @example
 * ```ts
-* const store = createStore({
-*   dirPath: configDir("my-cli"),
-*   fields: {
-*     theme: { type: "string", default: "light" },
-*   },
-* });
+* import { cacheDir } from "@crustjs/store";
 *
-* const config = await store.read();
-* await store.write({ theme: "dark" });
-* await store.update((c) => ({ ...c, theme: "dark" }));
-* await store.reset();
+* const dir = cacheDir("my-cli");
+* // → "/home/user/.cache/my-cli" (Linux)
+* // → "/Users/user/.cache/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\Cache" (Windows)
 * ```
 */
-interface Store<TConfig> {
-	/**
-	* Reads the persisted config, applying field defaults for missing keys.
-	*
-	* Always returns a value — fields with defaults are guaranteed present,
-	* fields without defaults may be `undefined`.
-	*
-	* @returns The effective config value.
-	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
-	* @throws {CrustStoreError} `IO` on filesystem read failures.
-	*/
-	read(): Promise<TConfig>;
-	/**
-	* Atomically persists the full config object.
-	*
-	* @param config - The complete config to persist.
-	* @throws {CrustStoreError} `IO` on filesystem write failures.
-	*/
-	write(config: NoInfer<TConfig>): Promise<void>;
-	/**
-	* Reads current effective config, applies the updater, and persists.
-	*
-	* @param updater - Function receiving current config and returning updated config.
-	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
-	* @throws {CrustStoreError} `IO` on filesystem failures.
-	*/
-	update(updater: StoreUpdater<TConfig>): Promise<void>;
-	/**
-	* Removes the persisted config file, returning the store to defaults-on-read behavior.
-	*
-	* @throws {CrustStoreError} `IO` on filesystem deletion failures.
-	*/
-	reset(): Promise<void>;
-}
+declare function cacheDir(appName: string, env?: PlatformEnv): string;
 /**
-* Creates a typed async config store backed by a local JSON file.
+* Creates a typed async store backed by a local JSON file.
 *
 * The store resolves its file path once at creation time from `dirPath` and
-* 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`).
+* optional `name`. The `defaults` object declares the data shape — its
+* TypeScript type determines the store's type parameter `T`.
 *
-* @typeParam F - Field definitions record (inferred via `const` generic).
+* @typeParam T - The store data shape (inferred from `defaults`).
 * @param options - Store configuration options.
-* @returns A {@link Store} instance with `read`, `write`, `update`, and `reset` methods.
+* @returns A {@link Store} instance with `read`, `write`, `update`, `patch`, and `reset` methods.
 * @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
 *
 * @example
@@ -402,20 +527,20 @@ interface Store<TConfig> {
 *
 * const store = createStore({
 *   dirPath: configDir("my-cli"),
-*   fields: {
-*     theme: { type: "string", default: "light" },
-*     verbose: { type: "boolean", default: false },
-*     token: { type: "string" },
+*   defaults: {
+*     ui: { theme: "light", fontSize: 14 },
+*     verbose: false,
 *   },
 * });
 *
-* const config = await store.read();
-* // → { theme: "light", verbose: false } (defaults when no persisted file)
+* const state = await store.read();
+* // → { ui: { theme: "light", fontSize: 14 }, verbose: false }
 *
-* await store.write({ theme: "dark", verbose: true, token: "abc" });
-* await store.update((c) => ({ ...c, theme: "light" }));
+* 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.reset();
 * ```
 */
-declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
-export { createStore, configDir, ValueType, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };
+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 };

package/dist/index.js

@@ -1,2 +1,4 @@
 // @bun
-class G extends Error{code;details;cause;constructor(x,z,V){super(z);this.name="CrustStoreError",this.code=x,this.details=V}is(x){return this.code===x}withCause(x){return this.cause=x,this}}import{homedir as y}from"os";import{join as H}from"path";var A="config";function D(){return{platform:process.platform,env:process.env,homedir:y()}}function F(x){if(!x||x.trim().length===0)throw new G("PATH","appName must be a non-empty string",{path:x??""});if(x.includes("/")||x.includes("\\"))throw new G("PATH","appName must not contain path separators",{path:x})}function J(x){if(!x||x.trim().length===0)throw new G("PATH","name must be a non-empty string",{path:x??""});if(x.includes("/")||x.includes("\\"))throw new G("PATH","name must not contain path separators",{path:x});if(x.endsWith(".json"))throw new G("PATH","name must not include the .json extension",{path:x})}function R(x){if(!x||x.trim().length===0)throw new G("PATH","dirPath must be a non-empty string",{path:x??""});if(!(x.startsWith("/")||/^[A-Za-z]:[/\\]/.test(x)))throw new G("PATH","dirPath must be an absolute path",{path:x});if(x.endsWith(".json"))throw new G("PATH","dirPath must be a directory path, not a file path (should not end with .json)",{path:x})}function T(x,z){F(x);let V=z??D();switch(V.platform){case"linux":{let B=V.env.XDG_CONFIG_HOME,q=B&&B.trim().length>0?B:H(V.homedir,".config");return H(q,x)}case"darwin":return H(V.homedir,"Library","Application Support",x);case"win32":{let B=V.env.APPDATA,q=B&&B.trim().length>0?B:H(V.homedir,"AppData","Roaming");return H(q,x)}default:throw new G("PATH",`Unsupported platform: ${V.platform}`,{path:V.platform})}}function Q(x,z){R(x);let V=z??A;if(z!==void 0)J(z);return H(x,`${V}.json`)}function W(x,z){let V={};for(let[B,q]of Object.entries(z))if(x&&B in x)V[B]=x[B];else if("default"in q&&q.default!==void 0)V[B]=Array.isArray(q.default)?[...q.default]:q.default;return V}import{randomUUID as j}from"crypto";import{mkdir as k,readFile as S,rename as g,rm as w,unlink as C,writeFile as c}from"fs/promises";import{dirname as N,join as v}from"path";async function Y(x){let z;try{z=await S(x,"utf-8")}catch(V){if($(V))return;throw new G("IO",`Failed to read config file: ${x}`,{path:x,operation:"read"}).withCause(V)}try{return JSON.parse(z)}catch(V){throw new G("PARSE",`Malformed JSON in config file: ${x}`,{path:x}).withCause(V)}}async function L(x,z){let V=N(x),B=v(V,`.config-${j()}.tmp`);try{await k(V,{recursive:!0})}catch(q){throw new G("IO",`Failed to create config directory: ${V}`,{path:x,operation:"write"}).withCause(q)}try{let q=JSON.stringify(z,null,"\t");await c(B,q,"utf-8")}catch(q){throw await X(B),new G("IO",`Failed to write config file: ${x}`,{path:x,operation:"write"}).withCause(q)}try{await g(B,x)}catch(q){throw await X(B),new G("IO",`Failed to finalize config file: ${x}`,{path:x,operation:"write"}).withCause(q)}}async function Z(x){try{await C(x)}catch(z){if($(z))return;throw new G("IO",`Failed to delete config file: ${x}`,{path:x,operation:"delete"}).withCause(z)}}function $(x){return x!==null&&typeof x==="object"&&"code"in x&&x.code==="ENOENT"}async function X(x){try{await w(x,{force:!0})}catch{}}function E(x){let{dirPath:z,name:V,fields:B}=x,q=Q(z,V);async function M(){let K=await Y(q);return W(K,B)}async function I(K){await L(q,K)}async function O(K){let _=await M(),b=K(_);await L(q,b)}async function U(){await Z(q)}return{read:M,write:I,update:O,reset:U}}export{E as createStore,T as configDir,G as CrustStoreError};
+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};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@crustjs/store",
-	"version": "0.0.2",
-	"description": "Minimal, type-safe config persistence for CLI apps",
+	"version": "0.0.3",
+	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"license": "MIT",
 	"author": "chenxin-yan",
@@ -17,8 +17,12 @@
 	"keywords": [
 		"cli",
 		"config",
+		"data",
+		"state",
+		"cache",
 		"store",
 		"persistence",
+		"xdg",
 		"bun",
 		"typescript"
 	],