@crustjs/store 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,759 +1,701 @@
-import { BaseValueType, ResolvePrimitive } from "@crustjs/utils";
+//#region ../utils/src/json.d.ts
+/** Any value representable in a JSON document. */
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | JsonObject;
+interface JsonObject {
+  [key: string]: JsonValue;
+}
+/** Preserve a type when all of its properties are recursively JSON-compatible. */
+type JsonCompatible<T> = T extends JsonValue ? T : T extends ((...arguments_: never[]) => void) ? never : T extends readonly unknown[] ? { [K in keyof T]: JsonCompatible<T[K]>; } : T extends object ? { [K in keyof T]: JsonCompatible<T[K]>; } : never;
+//#endregion
+//#region ../utils/src/primitive.d.ts
+/** Supported primitive type literals shared by Crust packages. */
+type BaseValueType = "string" | "number" | "boolean";
+/**
+ * Resolves a primitive type literal to its corresponding TypeScript type.
+ *
+ * @example
+ * ```ts
+ * type Port = ResolvePrimitive<"number">;
+ * //   ^? number
+ * ```
+ */
+type ResolvePrimitive<T extends BaseValueType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+//#endregion
+//#region ../utils/src/schema.d.ts
+/** The Standard Typed types interface. */
+interface StandardSchemaTypes<Input = unknown, Output = Input> {
+  /** The input type of the schema. */
+  readonly input: Input;
+  /** The output type of the schema. */
+  readonly output: Output;
+}
+/** The result interface if validation succeeds. */
+interface StandardSchemaSuccessResult<Output> {
+  /** The typed output value. */
+  readonly value: Output;
+  /** A falsy value for `issues` indicates success. */
+  readonly issues?: undefined;
+}
+/** The result interface if validation fails. */
+interface StandardSchemaFailureResult {
+  /** The issues of failed validation. */
+  readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+/** The result interface of the validate function. */
+type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
+/** The issue interface of the failure output. */
+interface StandardSchemaIssue {
+  /** The error message of the issue. */
+  readonly message: string;
+  /** The path of the issue, if any. */
+  readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
+}
+/** The path segment interface of the issue. */
+interface StandardSchemaPathSegment {
+  /** The key representing a path segment. */
+  readonly key: PropertyKey;
+}
+/** The Standard Schema properties interface. */
+interface StandardSchemaProps<Input = unknown, Output = Input> {
+  /** The version number of the standard. */
+  readonly version: 1;
+  /** The vendor name of the schema library. */
+  readonly vendor: string;
+  /** Inferred types associated with the schema. */
+  readonly types?: StandardSchemaTypes<Input, Output> | undefined;
+  /** Validates unknown input values. */
+  readonly validate: (value: StandardSchemaTypes["input"]) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+}
+/**
+ * A Standard Schema-compatible schema object.
+ *
+ * Any schema library implementing the Standard Schema v1 spec
+ * (Zod, Effect, Valibot, ArkType, etc.) produces objects matching this type.
+ */
+type StandardSchema<Input = unknown, Output = Input> = {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaProps<Input, Output>;
+};
+/** Infer the output type produced by a Standard Schema on success. */
+type InferOutput<S extends StandardSchema> = NonNullable<S["~standard"]["types"]>["output"];
+//#endregion
+//#region src/types.d.ts
 /** Supported type literals for store fields. */
 type ValueType = BaseValueType;
 /** 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;
-	}>;
-	/** Internal marker: validate missing values as `undefined` for schema-backed fields. */
-	validateMissing?: true;
+  /** Standard Schemas are an exclusive definition mode. */
+  schema?: never;
+  /**
+   * 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.
+   * - `{ value }` (or `Promise<{ value }>`) — a transform produced an
+   *   output within the field's declared type. On `write` / `update` /
+   *   `patch`, the transformed value replaces the input before
+   *   persistence and is re-validated once to catch read-unstable
+   *   transforms. Outputs outside the declared type are rejected with
+   *   `VALIDATION`. On `read`, the transformed value is discarded —
+   *   reads always return the on-disk value verbatim.
+   * - 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: V;
+  } | Promise<{
+    value: V;
+  }>;
 }
 /** 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;
+  /** 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;
+  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;
+  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;
+  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;
+  /** 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[];
+  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[];
+  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[];
+  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.
-*
-* 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
-* 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;
-* ```
-*/
-interface RawScalarFieldDef extends ScalarFieldBase<unknown> {
-	type?: never;
-	default?: unknown;
+/** A field whose Standard Schema exclusively owns its value semantics. */
+interface SchemaFieldDef {
+  /** Standard Schema that owns validation, transformation, defaults, and optionality. */
+  schema: StandardSchema<unknown, unknown>;
+  type?: BaseValueType;
+  array?: true;
+  default?: never;
+  validate?: never;
 }
-interface RawArrayFieldDef extends ArrayFieldBase<unknown[]> {
-	type?: never;
-	default?: readonly unknown[];
-}
-type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef | RawScalarFieldDef | RawArrayFieldDef;
+/**
+ * Defines a single field in a store's config schema.
+ *
+ * Core definitions are discriminated by `type` and `array`. Schema-backed
+ * definitions use a `schema` key and cannot mix schema semantics with
+ * `default` or `validate`.
+ *
+ * @example
+ * ```ts
+ * const fields = {
+ *   theme: { type: "string", default: "light" },
+ *   port: { schema: z.coerce.number().int().positive() },
+ * } satisfies FieldsDef;
+ * ```
+ */
+type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef | SchemaFieldDef;
 /** Record mapping field names to their definitions. */
 type FieldsDef = Record<string, FieldDef>;
-declare const FIELD_SCHEMA_OUTPUT: unique symbol;
+type JsonCompatibleFields<F extends FieldsDef> = { [K in keyof F]: F[K] extends {
+  schema: StandardSchema<unknown, infer Output>;
+} ? Exclude<Output, undefined> extends JsonCompatible<Exclude<Output, undefined>> ? F[K] : never : F[K]; };
 /**
-* Infer the resolved type for a single field definition.
-*
-* - **array** → `primitive[]` (or `primitive[] | undefined` if no default)
-* - **has default** → `primitive` (guaranteed present)
-* - **no default** → `primitive | undefined` (optional)
-*/
+ * Infer the resolved type for a single field definition.
+ *
+ * - **schema** → the schema's exact output type
+ * - **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 {
-	readonly [FIELD_SCHEMA_OUTPUT]?: infer O;
-} ? F extends {
-	default: infer D;
-} ? D : O | undefined : F extends {
-	type: ValueType;
+  schema: infer S extends StandardSchema;
+} ? InferOutput<S> : F extends {
+  type: ValueType;
 } ? F extends {
-	array: true;
+  array: true;
 } ? F extends {
-	default: readonly ResolvePrimitive<F["type"]>[];
+  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 : F extends {
-	default: infer D;
-} ? D : unknown;
+  default: ResolvePrimitive<F["type"]>;
+} ? ResolvePrimitive<F["type"]> : ResolvePrimitive<F["type"]> | undefined : never;
 /**
-* Maps a full {@link FieldsDef} record to the inferred config object type.
-*
-* @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]> };
+ * Maps a full {@link FieldsDef} record to the inferred config object type.
+ *
+ * @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.
-*/
+ * 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;
+  /** Human-readable description of the validation failure. */
+  message: string;
+  /** Field name where the issue occurred. */
+  path: string;
 }
+/** Explicit Unix permission bits for store persistence. */
+interface StorePermissionBits {
+  /** Permission bits for the persisted store file (e.g. `0o600`). */
+  file?: number;
+  /** Permission bits for the store's parent directory (e.g. `0o700`). */
+  directory?: number;
+}
+/**
+ * Persistence visibility for store writes.
+ *
+ * - `"default"` or omitted uses platform defaults.
+ * - `"private"` keeps the store owner-only on Unix (`0600` file, `0700` directory).
+ * - An object lets advanced callers provide explicit Unix permission bits for
+ *   group-readable or public non-secret stores without expanding the preset list.
+ */
+type StoreAccess = "default" | "private" | StorePermissionBits;
 /**
-* Options for {@link createStore}.
-*
-* @typeParam F - The field definitions record (inferred via `const` generic).
-*
-* @example
-* ```ts
-* const store = createStore({
-*   dirPath: configDir("my-cli"),
-*   fields: {
-*     theme: { type: "string", default: "light" },
-*     verbose: { type: "boolean", default: false },
-*     token: { type: "string" },
-*   },
-* });
-* ```
-*/
+ * Options for {@link createStore}.
+ *
+ * @typeParam F - The field definitions record (inferred via `const` generic).
+ *
+ * @example
+ * ```ts
+ * const store = createStore({
+ *   dirPath: configDir("my-cli"),
+ *   name: "config",
+ *   fields: {
+ *     theme: { type: "string", default: "light" },
+ *     verbose: { type: "boolean", default: false },
+ *     token: { type: "string" },
+ *   },
+ * });
+ * ```
+ */
 interface CreateStoreOptions<F extends FieldsDef> {
-	/**
-	* 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;
-	/**
-	* Field definitions that declare the store's config schema.
-	*
-	* Each key maps to a {@link FieldDef} with a `type` discriminant and optional
-	* `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;
+  /**
+   * 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.
+   *
+   * For example, `name: "auth"` produces `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}: either a core definition or a
+   * schema-backed definition. Core fields without `default` are optional;
+   * schema fields use the schema's exact output type.
+   */
+  fields: F & JsonCompatibleFields<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;
+  /**
+   * Persistence visibility for store writes.
+   *
+   * Use `"private"` for config/state stores holding secrets (tokens, API keys)
+   * that should stay owner-only. On Unix this writes the file as `0600` and
+   * creates the parent directory as `0700`; on Windows it is not enforced
+   * because Windows uses ACLs instead of Unix permission bits.
+   *
+   * The only built-in presets are `"default"` and `"private"`. Advanced callers
+   * can pass explicit bits with `{ file, directory }` for group-readable or public
+   * non-secret stores. The file bits are enforced exactly on every write
+   * regardless of `umask`. Directory bits apply only when a write creates the
+   * directory; pre-existing directories are left untouched.
+   *
+   * @default "default"
+   * @example "private"
+   * @example { file: 0o600, directory: 0o700 }
+   */
+  access?: StoreAccess;
 }
 /**
-* Receives the current effective config and returns an updated config.
-*
-* Used by {@link Store.update} to apply mutations atomically.
-*
-* @example
-* ```ts
-* await store.update((current) => ({
-*   ...current,
-*   theme: "dark",
-* }));
-* ```
-*/
+ * Receives the current config with defaults and core coercion applied,
+ * but without full field validation, and returns an updated config.
+ * Persisted values may not yet satisfy their declared types or validators.
+ *
+ * Used by {@link Store.update}, which validates the result before persistence.
+ *
+ * @example
+ * ```ts
+ * await store.update((current) => ({
+ *   ...current,
+ *   theme: "dark",
+ * }));
+ * ```
+ */
 type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
 /**
-* A typed async config store returned by {@link createStore}.
-*
-* 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.
-*
-* @example
-* ```ts
-* const store = createStore({
-*   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", verbose: true });
-* await store.update((c) => ({ ...c, theme: "dark" }));
-* await store.patch({ theme: "dark" });
-* await store.reset();
-* ```
-*/
+ * A typed async config store returned by {@link createStore}.
+ *
+ * Provides `read`, `write`, `update`, `patch`, and `reset` operations for a
+ * single typed config object persisted as JSON on the local filesystem.
+ * Mutations are not serialized, including overlapping calls in one process.
+ * Await mutations sequentially for each file; coordinate multiple processes externally.
+ *
+ * @typeParam TConfig - The inferred config shape from field definitions.
+ *
+ * @example
+ * ```ts
+ * const store = createStore({
+ *   dirPath: configDir("my-cli"),
+ *   name: "config",
+ *   fields: {
+ *     theme: { type: "string", default: "light" },
+ *     verbose: { type: "boolean", default: false },
+ *   },
+ * });
+ *
+ * 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<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`.
-	*
-	* 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>;
-	/**
-	* 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} `VALIDATION` if field validation fails.
-	* @throws {CrustStoreError} `IO` on filesystem failures.
-	*/
-	update(updater: StoreUpdater<TConfig>): Promise<void>;
-	/**
-	* 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;
+  /**
+   * 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`.
+   *
+   * 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 or its root is not an object.
+   * @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.
+   * @returns The persisted config, including schema transformations.
+   * @throws {CrustStoreError} `VALIDATION` if field validation fails.
+   * @throws {CrustStoreError} `IO` on filesystem write failures.
+   */
+  write(config: NoInfer<TConfig>): Promise<TConfig>;
+  /**
+   * Reads current config with defaults and core coercion applied, without
+   * full field validation. Applies the updater, validates the result, and persists.
+   *
+   * The final file replacement is atomic, but the read-modify-write sequence
+   * is not serialized, even within one process. Await mutations sequentially
+   * to avoid lost updates; coordinate multiple processes externally.
+   *
+   * @param updater - Function receiving current config and returning updated config.
+   * @returns The persisted config, including schema transformations.
+   * @throws {CrustStoreError} `PARSE` if persisted JSON is malformed or its root is not an object.
+   * @throws {CrustStoreError} `VALIDATION` if field validation fails.
+   * @throws {CrustStoreError} `IO` on filesystem failures.
+   */
+  update(updater: StoreUpdater<TConfig>): Promise<TConfig>;
+  /**
+   * Applies a partial update to the current config and persists.
+   *
+   * Only the provided keys are updated; everything else is preserved.
+   * Like {@link Store.update}, the current config has defaults and core coercion
+   * applied but has not undergone full field validation. The merged result is
+   * validated before persistence. Await mutations sequentially to avoid lost updates.
+   *
+   * @param partial - A partial subset of the config to merge in.
+   * @returns The persisted config, including schema transformations.
+   * @throws {CrustStoreError} `VALIDATION` if field validation fails.
+   * @throws {CrustStoreError} `PARSE` if persisted JSON is malformed or its root is not an object.
+   * @throws {CrustStoreError} `IO` on filesystem failures.
+   */
+  patch(partial: Partial<NoInfer<TConfig>>): Promise<TConfig>;
+  /**
+   * Removes the persisted config file, returning the store to
+   * defaults-on-read behavior.
+   *
+   * @throws {CrustStoreError} `IO` on filesystem deletion failures.
+   */
+  reset(): Promise<void>;
 }
+//#endregion
+//#region src/errors.d.ts
 /**
-* 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.
-*/
+ * 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";
+  /** 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.
-*/
+ * 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[];
+  /** The store operation during which validation failed. */
+  operation: "read" | "write" | "update" | "patch";
+  /** Structured validation issues for programmatic handling. */
+  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.
-*/
-interface DefinitionErrorDetails {
-	/** The schema vendor name, when available. */
-	vendor?: string;
-}
-/**
-* Maps each {@link StoreErrorCode} to its structured details type.
-*
-* Used internally for conditional constructor parameters and type narrowing.
-*/
+ * 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;
-	DEFINITION: DefinitionErrorDetails;
+  PATH: {
+    path: string;
+  };
+  PARSE: {
+    path: string;
+  };
+  IO: IOErrorDetails;
+  VALIDATION: ValidationErrorDetails;
+  DEFINITION: undefined;
 }
 /**
-* 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
-* - `DEFINITION` — `field()` cannot produce a valid `FieldDef` from the given schema/options
-*
-* @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;
-*     }
-*   }
-* }
-* ```
-*/
+ * 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
+ * - `DEFINITION` — A field mixes mutually exclusive definition modes
+ *
+ * @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}`);
+ *   } else if (err instanceof CrustStoreError && err.is("VALIDATION")) {
+ *     for (const issue of err.details.issues) {
+ *       console.error(`${issue.path}: ${issue.message}`);
+ *     }
+ *   } else if (err instanceof CrustStoreError && err.is("IO")) {
+ *     console.error(`File ${err.details.operation} failed: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
 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;
-}
-import { BaseValueType as BaseValueType2 } from "@crustjs/utils";
-import { InferOutput, StandardSchema } from "@crustjs/utils/schema";
-/**
-* Optional Crust metadata for the `FieldDef` shape produced by {@link field}.
-*
-* Every key is optional. Crust does not infer metadata from schemas; schemas
-* validate and transform actual runtime values, including missing values passed
-* as `undefined`.
-*
-* 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?: BaseValueType2;
-	description?: string;
-	/**
-	* Crust metadata default for this field when the persisted state does not
-	* contain a value for it. Schema defaults should usually live in the schema;
-	* missing persisted values are validated as `undefined`, so `.default()` works
-	* naturally at read time.
-	*/
-	default?: T;
-	/** Mark this field as an array (collects values into an array). */
-	array?: true;
+ * 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. Codes other than `DEFINITION` include 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}`);
+ *   }
+ * }
+ * ```
+ */
+export 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>;
+  constructor(code: C, message: string, ...[details, cause]: StoreErrorDetails<C> extends undefined ? [details?: undefined, cause?: unknown] : [details: StoreErrorDetails<C>, cause?: unknown]);
+  /**
+   * 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>;
 }
-type RawSchemaFieldDef<Out> = {
-	readonly type?: never;
-	readonly array?: never;
-	readonly description?: string;
-	readonly validate: (value: unknown) => Promise<{
-		value: unknown;
-	}>;
-	readonly validateMissing: true;
-	readonly [FIELD_SCHEMA_OUTPUT]?: Out;
-};
-type SchemaFieldDefWithOptions<
-	Out,
-	Type extends FieldOptions["type"],
-	Array extends true | undefined,
-	D = never
-> = Omit<RawSchemaFieldDef<Out>, "type" | "array"> & (Type extends NonNullable<FieldOptions["type"]> ? {
-	readonly type: Type;
-} : {
-	readonly type?: never;
-}) & (Array extends true ? {
-	readonly array: true;
-} : {
-	readonly array?: never;
-}) & ([D] extends [never] ? unknown : {
-	readonly default: D;
-});
-/**
-* `FieldDef` inferred from a Standard Schema, with no narrowed default.
-*
-* Standard Schema v1 has no spec-portable type-level access to defaults, so
-* schema `.default()` does not narrow the inferred TypeScript type. Pass
-* `field(schema, { default: x })` explicitly to narrow.
-*/
-type SchemaFieldDef<S extends StandardSchema> = RawSchemaFieldDef<InferOutput<S>>;
-/**
-* Define a `@crustjs/store` field from any Standard Schema v1.
-*
-* Returns a value that satisfies store's `FieldDef` discriminated union.
-* Crust stores raw values and lets the schema validate and transform them on
-* read/write; missing persisted values flow through the schema as `undefined`,
-* so `.optional()` and `.default()` behave naturally.
-*
-* 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**: Standard Schema v1 has no spec-portable type-level
-* access to defaults. For tight typing of default-bearing fields, pass
-* `default` via `opts`:
-*
-* ```ts
-* field(z.string().default("x"))         // value materializes on read; state: string | undefined
-* field(z.string(), { default: "x" })    // Crust-level default; 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 Crust-level metadata
-* @throws {CrustStoreError} With code `"DEFINITION"` when the input is not
-*         a Standard Schema v1 object.
-*
-* @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>,
-	const Type extends FieldOptions<InferOutput<S>>["type"] = undefined,
-	const Array extends true | undefined = undefined
->(schema: S, opts: FieldOptions<InferOutput<S>> & {
-	default: D;
-	type?: Type;
-	array?: Array;
-}): SchemaFieldDefWithOptions<InferOutput<S>, Type, Array, D>;
-declare function field<
-	S extends StandardSchema,
-	const Type extends FieldOptions<InferOutput<S>>["type"] = undefined,
-	const Array extends true | undefined = undefined
->(schema: S, opts: FieldOptions<InferOutput<S>> & {
-	type?: Type;
-	array?: Array;
-}): SchemaFieldDefWithOptions<InferOutput<S>, Type, Array>;
+//#endregion
+//#region src/path.d.ts
 /**
-* Encapsulates runtime environment values needed for path resolution.
-*
-* Exposed as a parameter to allow deterministic testing without mutating
-* `process.env` or `process.platform`.
-*/
+ * 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;
+  /** 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 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)
+ * ```
+ */
+export 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 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)
+ * ```
+ */
+export 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 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)
+ * ```
+ */
+export 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;
+ * 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)
+ * ```
+ */
+export declare function cacheDir(appName: string, env?: PlatformEnv): string;
+//#endregion
+//#region src/store.d.ts
 /**
-* 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`. 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 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.
-*
-* @example
-* ```ts
-* 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" },
-*   },
-* });
-*
-* const config = await store.read();
-* // → { 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 { stateDir, field, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldOptions, FieldDef, DefinitionErrorDetails, CrustStoreError, CreateStoreOptions };
+ * 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
+ * `name`. Core field definitions infer from `type` and `default`;
+ * schema-backed fields use the Standard Schema's exact output type.
+ *
+ * @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.
+ * @throws {CrustStoreError} `DEFINITION` if a field mixes `schema` with `default` or `validate`.
+ *
+ * @example
+ * ```ts
+ * import { createStore, configDir } from "@crustjs/store";
+ *
+ * const store = createStore({
+ *   dirPath: configDir("my-cli"),
+ *   name: "config",
+ *   fields: {
+ *     theme: { type: "string", default: "light" },
+ *     verbose: { type: "boolean", default: false },
+ *     token: { type: "string" },
+ *   },
+ * });
+ *
+ * const config = await store.read();
+ * // → { 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();
+ * ```
+ */
+export declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
+//#endregion
+export type { CreateStoreOptions, FieldDef, FieldsDef, InferStoreConfig, PlatformEnv, Store, StoreAccess, StoreErrorCode, StorePermissionBits, StoreUpdater, StoreValidatorIssue, ValidationErrorDetails, ValueType };