@crustjs/store 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -1,169 +1,3 @@
-/**
-* Contextual details attached to a `PATH` error.
-*
-* Returned when the resolved or provided config file path is invalid.
-*/
-interface PathErrorDetails {
-	/** The path value that caused the error. */
-	path: string;
-}
-/**
-* Contextual details attached to a `PARSE` error.
-*
-* Returned when the persisted JSON file cannot be parsed.
-*/
-interface ParseErrorDetails {
-	/** Absolute path to the file that failed parsing. */
-	path: string;
-}
-/**
-* Contextual details attached to an `IO` error.
-*
-* Returned on filesystem read, write, or delete failures.
-*/
-interface IOErrorDetails {
-	/** Absolute path to the file involved in the failed operation. */
-	path: string;
-	/** The filesystem operation that failed (e.g. `"read"`, `"write"`, `"delete"`). */
-	operation: "read" | "write" | "delete";
-}
-/**
-* Maps each {@link StoreErrorCode} to its structured details type.
-*
-* Used internally for conditional constructor parameters and type narrowing.
-*/
-interface StoreErrorDetailsMap {
-	PATH: PathErrorDetails;
-	PARSE: ParseErrorDetails;
-	IO: IOErrorDetails;
-}
-/**
-* All possible error codes emitted by `@crustjs/store`.
-*
-* - `PATH` — Invalid or unsupported config file path
-* - `PARSE` — Malformed JSON in persisted config file
-* - `IO` — Filesystem read, write, or delete failure
-*
-* @example
-* ```ts
-* import { CrustStoreError } from "@crustjs/store";
-*
-* try {
-*   const config = await store.read();
-* } catch (err) {
-*   if (err instanceof CrustStoreError) {
-*     switch (err.code) {
-*       case "PARSE":
-*         console.error(`Corrupt config at ${err.details.path}`);
-*         break;
-*       case "IO":
-*         console.error(`File ${err.details.operation} failed: ${err.message}`);
-*         break;
-*     }
-*   }
-* }
-* ```
-*/
-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.
-*
-* Every `CrustStoreError` carries a {@link StoreErrorCode} that identifies the failure
-* category, along with structured {@link StoreErrorDetails} for programmatic handling
-* without fragile message parsing.
-*
-* @example
-* ```ts
-* import { CrustStoreError } from "@crustjs/store";
-*
-* try {
-*   const config = await store.read();
-* } catch (err) {
-*   if (err instanceof CrustStoreError && err.is("PARSE")) {
-*     console.error(`Corrupt config at ${err.details.path}`);
-*   }
-* }
-* ```
-*/
-declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends Error {
-	/** Machine-readable error code for programmatic handling. */
-	readonly code: C;
-	/** Structured payload with context about the failure. */
-	readonly details: StoreErrorDetails<C>;
-	/** Optional wrapped original error or value. */
-	cause?: unknown;
-	constructor(code: C, message: string, details: StoreErrorDetails<C>);
-	/**
-	* Type-guard that narrows this error to a specific {@link StoreErrorCode}.
-	*
-	* When the guard returns `true`, TypeScript narrows the `details` property
-	* to the corresponding details type.
-	*
-	* @example
-	* ```ts
-	* if (err.is("IO")) {
-	*   // err.details is IOErrorDetails
-	*   console.error(err.details.operation, err.details.path);
-	* }
-	* ```
-	*/
-	is<T extends StoreErrorCode>(code: T): this is CrustStoreError<T>;
-	/**
-	* Attaches a cause to this error for stack-trace chaining.
-	*
-	* Returns `this` for fluent usage.
-	*
-	* @example
-	* ```ts
-	* throw new CrustStoreError("IO", "write failed", {
-	*   path: "/path/to/config.json",
-	*   operation: "write",
-	* }).withCause(originalError);
-	* ```
-	*/
-	withCause(cause: unknown): this;
-}
-/**
-* Encapsulates runtime environment values needed for path resolution.
-*
-* Exposed as a parameter to allow deterministic testing without mutating
-* `process.env` or `process.platform`.
-*/
-interface PlatformEnv {
-	/** Operating system platform identifier (e.g. `"linux"`, `"darwin"`, `"win32"`). */
-	platform: string;
-	/** Environment variables map. */
-	env: Record<string, string | undefined>;
-	/** User home directory path. */
-	homedir: string;
-}
-/**
-* 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>`
-* - **Windows**: `%APPDATA%/<appName>` or `~/AppData/Roaming/<appName>`
-*
-* @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 config directory.
-* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
-*
-* @example
-* ```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)
-* ```
-*/
-declare function configDir(appName: string, env?: PlatformEnv): string;
 /** Supported type literals for store fields. */
 type ValueType = "string" | "number" | "boolean";
 /**
@@ -175,52 +9,64 @@ type ValueType = "string" | "number" | "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 {
+interface FieldDefBase<V> {
 	/** Human-readable description for documentation and tooling. */
 	description?: string;
+	/**
+	* Optional per-field validation function.
+	*
+	* Called during `read`, `write`, `update`, and `patch` operations when
+	* the field has a value (not `undefined`). Throw an error to reject the
+	* value.
+	*
+	* @param value - The field value to validate.
+	* @throws When the value is invalid — the error message is captured as a
+	*   validation issue with the field name as `path`.
+	*/
+	validate?: (value: V) => void | Promise<void>;
 }
 /** Base for scalar (non-array) fields — `array` must be omitted. */
-interface ScalarFieldBase extends FieldDefBase {
+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 {
+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 {
+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 {
+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 extends FieldDefBase {
+interface ArrayFieldBase<V> extends FieldDefBase<V> {
 	/** Collect values into an array. */
 	array: true;
 }
 /** An array of strings field. */
-interface StringArrayFieldDef extends ArrayFieldBase {
+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 {
+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 {
+interface BooleanArrayFieldDef extends ArrayFieldBase<boolean[]> {
 	type: "boolean";
 	/** Default boolean array value when the field is not persisted. */
 	default?: readonly boolean[];
@@ -229,6 +75,8 @@ interface BooleanArrayFieldDef extends ArrayFieldBase {
 * Defines a single field in a store's config schema.
 *
 * 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
@@ -237,6 +85,11 @@ interface BooleanArrayFieldDef extends ArrayFieldBase {
 *   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;
 * ```
 */
@@ -271,6 +124,15 @@ type InferFieldValue<F extends FieldDef> = F extends {
 */
 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;
+	/** Field name where the issue occurred. */
+	path: string;
+}
+/**
 * Options for {@link createStore}.
 *
 * @typeParam F - The field definitions record (inferred via `const` generic).
@@ -282,6 +144,7 @@ type InferStoreConfig<F extends FieldsDef> = { [K in keyof F] : InferFieldValue<
 *   fields: {
 *     theme: { type: "string", default: "light" },
 *     verbose: { type: "boolean", default: false },
+*     token: { type: "string" },
 *   },
 * });
 * ```
@@ -290,8 +153,8 @@ 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.
+	* Use a path helper ({@link configDir}, {@link dataDir}, etc.) to resolve
+	* the platform-standard directory from an app name.
 	*/
 	dirPath: string;
 	/**
@@ -308,14 +171,21 @@ interface CreateStoreOptions<F extends FieldsDef> {
 	* 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`).
+	* `default` and `validate`. Fields without a `default` are optional (`T | undefined`).
 	*/
 	fields: F;
+	/**
+	* When `true` (the default), persisted keys not present in `fields`
+	* are dropped on read. Set to `false` to preserve unknown keys.
+	*
+	* @default true
+	*/
+	pruneUnknown?: boolean;
 }
 /**
 * Receives the current effective config and returns an updated config.
 *
-* Used by {@link Store.update} to apply partial mutations atomically.
+* Used by {@link Store.update} to apply mutations atomically.
 *
 * @example
 * ```ts
@@ -329,8 +199,8 @@ type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
 /**
 * A typed async config store returned by {@link createStore}.
 *
-* Provides `read`, `write`, `update`, and `reset` operations for a single
-* typed config object persisted as JSON on the local filesystem.
+* Provides `read`, `write`, `update`, `patch`, and `reset` operations for a
+* single typed config object persisted as JSON on the local filesystem.
 *
 * @typeParam TConfig - The inferred config shape from field definitions.
 *
@@ -340,12 +210,14 @@ type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
 *   dirPath: configDir("my-cli"),
 *   fields: {
 *     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
 *   },
 * });
 *
 * const config = await store.read();
-* await store.write({ theme: "dark" });
+* await store.write({ theme: "dark", verbose: true });
 * await store.update((c) => ({ ...c, theme: "dark" }));
+* await store.patch({ theme: "dark" });
 * await store.reset();
 * ```
 */
@@ -356,15 +228,23 @@ interface Store<TConfig> {
 	* Always returns a value — fields with defaults are guaranteed present,
 	* fields without defaults may be `undefined`.
 	*
+	* When fields have `validate` functions, the merged config is validated
+	* after defaults are applied. Invalid persisted config fails loudly.
+	*
 	* @returns The effective config value.
 	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `IO` on filesystem read failures.
 	*/
 	read(): Promise<TConfig>;
 	/**
 	* Atomically persists the full config object.
 	*
+	* When fields have `validate` functions, the config is validated before
+	* persistence.
+	*
 	* @param config - The complete config to persist.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @throws {CrustStoreError} `IO` on filesystem write failures.
 	*/
 	write(config: NoInfer<TConfig>): Promise<void>;
@@ -373,17 +253,294 @@ interface Store<TConfig> {
 	*
 	* @param updater - Function receiving current config and returning updated config.
 	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `VALIDATION` if field validation fails.
 	* @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.
+	* Applies a partial update to the current config and persists.
+	*
+	* Only the provided keys are updated; everything else is preserved.
+	*
+	* @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: Partial<NoInfer<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>;
 }
 /**
+* Contextual details attached to a `PATH` error.
+*
+* Returned when the resolved or provided config file path is invalid.
+*/
+interface PathErrorDetails {
+	/** The path value that caused the error. */
+	path: string;
+}
+/**
+* Contextual details attached to a `PARSE` error.
+*
+* Returned when the persisted JSON file cannot be parsed.
+*/
+interface ParseErrorDetails {
+	/** Absolute path to the file that failed parsing. */
+	path: string;
+}
+/**
+* Contextual details attached to an `IO` error.
+*
+* Returned on filesystem read, write, or delete failures.
+*/
+interface IOErrorDetails {
+	/** Absolute path to the file involved in the failed operation. */
+	path: string;
+	/** The filesystem operation that failed (e.g. `"read"`, `"write"`, `"delete"`). */
+	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.
+*/
+interface StoreErrorDetailsMap {
+	PATH: PathErrorDetails;
+	PARSE: ParseErrorDetails;
+	IO: IOErrorDetails;
+	VALIDATION: ValidationErrorDetails;
+}
+/**
+* All possible error codes emitted by `@crustjs/store`.
+*
+* - `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
+* import { CrustStoreError } from "@crustjs/store";
+*
+* try {
+*   const config = await store.read();
+* } catch (err) {
+*   if (err instanceof CrustStoreError) {
+*     switch (err.code) {
+*       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;
+*     }
+*   }
+* }
+* ```
+*/
+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, IO, and validation failures.
+*
+* Every `CrustStoreError` carries a {@link StoreErrorCode} that identifies the failure
+* category, along with structured {@link StoreErrorDetails} for programmatic handling
+* without fragile message parsing.
+*
+* @example
+* ```ts
+* import { CrustStoreError } from "@crustjs/store";
+*
+* try {
+*   const config = await store.read();
+* } catch (err) {
+*   if (err instanceof CrustStoreError && err.is("PARSE")) {
+*     console.error(`Corrupt config at ${err.details.path}`);
+*   }
+* }
+* ```
+*/
+declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends Error {
+	/** Machine-readable error code for programmatic handling. */
+	readonly code: C;
+	/** Structured payload with context about the failure. */
+	readonly details: StoreErrorDetails<C>;
+	/** Optional wrapped original error or value. */
+	cause?: unknown;
+	constructor(code: C, message: string, details: StoreErrorDetails<C>);
+	/**
+	* Type-guard that narrows this error to a specific {@link StoreErrorCode}.
+	*
+	* When the guard returns `true`, TypeScript narrows the `details` property
+	* to the corresponding details type.
+	*
+	* @example
+	* ```ts
+	* if (err.is("IO")) {
+	*   // err.details is IOErrorDetails
+	*   console.error(err.details.operation, err.details.path);
+	* }
+	* ```
+	*/
+	is<T extends StoreErrorCode>(code: T): this is CrustStoreError<T>;
+	/**
+	* Attaches a cause to this error for stack-trace chaining.
+	*
+	* Returns `this` for fluent usage.
+	*
+	* @example
+	* ```ts
+	* throw new CrustStoreError("IO", "write failed", {
+	*   path: "/path/to/config.json",
+	*   operation: "write",
+	* }).withCause(originalError);
+	* ```
+	*/
+	withCause(cause: unknown): this;
+}
+/**
+* Encapsulates runtime environment values needed for path resolution.
+*
+* Exposed as a parameter to allow deterministic testing without mutating
+* `process.env` or `process.platform`.
+*/
+interface PlatformEnv {
+	/** Operating system platform identifier (e.g. `"linux"`, `"darwin"`, `"win32"`). */
+	platform: string;
+	/** Environment variables map. */
+	env: Record<string, string | undefined>;
+	/** User home directory path. */
+	homedir: string;
+}
+/**
+* Resolves the platform-standard config directory for the given app.
+*
+* Platform conventions:
+* - **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.
+* @returns Absolute path to the app's config directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+*
+* @example
+* ```ts
+* import { configDir } from "@crustjs/store";
+*
+* const dir = configDir("my-cli");
+* // → "/home/user/.config/my-cli" (Linux)
+* // → "/Users/user/.config/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Roaming\\my-cli" (Windows)
+* ```
+*/
+declare function configDir(appName: string, env?: PlatformEnv): string;
+/**
+* Resolves the platform-standard data directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_DATA_HOME/<appName>` or `~/.local/share/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Data` or `~/AppData/Local/<appName>/Data`
+*
+* 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 data directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+*
+* @example
+* ```ts
+* 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)
+* ```
+*/
+declare function dataDir(appName: string, env?: PlatformEnv): string;
+/**
+* Resolves the platform-standard state directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_STATE_HOME/<appName>` or `~/.local/state/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/State` or `~/AppData/Local/<appName>/State`
+*
+* 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 state directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+*
+* @example
+* ```ts
+* 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)
+* ```
+*/
+declare function stateDir(appName: string, env?: PlatformEnv): string;
+/**
+* Resolves the platform-standard cache directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_CACHE_HOME/<appName>` or `~/.cache/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Cache` or `~/AppData/Local/<appName>/Cache`
+*
+* 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
+* import { cacheDir } from "@crustjs/store";
+*
+* 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)
+* ```
+*/
+declare function cacheDir(appName: string, env?: PlatformEnv): string;
+/**
 * 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
@@ -393,7 +550,7 @@ interface Store<TConfig> {
 *
 * @typeParam F - Field definitions record (inferred via `const` generic).
 * @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
@@ -410,12 +567,13 @@ interface Store<TConfig> {
 * });
 *
 * const config = await store.read();
-* // → { theme: "light", verbose: false } (defaults when no persisted file)
+* // → { theme: "light", verbose: false, token: undefined }
 *
 * 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 F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
-export { createStore, configDir, ValueType, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };
+export { stateDir, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };