@crustjs/store 0.0.4 → 0.1.1

package/README.md

@@ -56,15 +56,21 @@ No explicit generics needed — types are inferred from your `fields` definition
 
 `@crustjs/store` provides four path helpers that resolve platform-standard directories for different storage intents. Use the one that matches what you're persisting:
 
-| Helper      | Intent                     | Example Use Case                        |
-| ----------- | -------------------------- | --------------------------------------- |
-| `configDir` | User preferences & config  | Theme, editor settings, API keys        |
-| `dataDir`   | Important app data         | Local databases, downloaded resources   |
-| `stateDir`  | Runtime state              | Window positions, scroll offsets, undo  |
-| `cacheDir`  | Regenerable cached data    | HTTP caches, compiled assets            |
+| Helper      | Intent                    | Example Use Case                       |
+| ----------- | ------------------------- | -------------------------------------- |
+| `configDir` | User preferences & config | Theme, editor settings, API keys       |
+| `dataDir`   | Important app data        | Local databases, downloaded resources  |
+| `stateDir`  | Runtime state             | Window positions, scroll offsets, undo |
+| `cacheDir`  | Regenerable cached data   | HTTP caches, compiled assets           |
 
 ```ts
-import { createStore, configDir, dataDir, stateDir, cacheDir } from "@crustjs/store";
+import {
+  createStore,
+  configDir,
+  dataDir,
+  stateDir,
+  cacheDir,
+} from "@crustjs/store";
 
 // User preferences → ~/.config/my-cli/config.json
 const config = createStore({
@@ -79,7 +85,7 @@ const config = createStore({
 const data = createStore({
   dirPath: dataDir("my-cli"),
   fields: {
-    bookmarks: { type: "array", default: [] },
+    bookmarks: { type: "string", array: true, default: [] },
   },
 });
 
@@ -106,12 +112,12 @@ const cache = createStore({
 
 All four helpers follow XDG conventions on Linux and macOS, and Windows-native conventions on Windows:
 
-| Helper      | Linux / macOS                       | Windows                                     | Env Override         |
-| ----------- | ----------------------------------- | ------------------------------------------- | -------------------- |
-| `configDir` | `~/.config/<app>`                   | `%APPDATA%\<app>`                           | `$XDG_CONFIG_HOME`   |
-| `dataDir`   | `~/.local/share/<app>`              | `%LOCALAPPDATA%\<app>\Data`                 | `$XDG_DATA_HOME`     |
-| `stateDir`  | `~/.local/state/<app>`              | `%LOCALAPPDATA%\<app>\State`                | `$XDG_STATE_HOME`    |
-| `cacheDir`  | `~/.cache/<app>`                    | `%LOCALAPPDATA%\<app>\Cache`                | `$XDG_CACHE_HOME`    |
+| Helper      | Linux / macOS          | Windows                      | Env Override       |
+| ----------- | ---------------------- | ---------------------------- | ------------------ |
+| `configDir` | `~/.config/<app>`      | `%APPDATA%\<app>`            | `$XDG_CONFIG_HOME` |
+| `dataDir`   | `~/.local/share/<app>` | `%LOCALAPPDATA%\<app>\Data`  | `$XDG_DATA_HOME`   |
+| `stateDir`  | `~/.local/state/<app>` | `%LOCALAPPDATA%\<app>\State` | `$XDG_STATE_HOME`  |
+| `cacheDir`  | `~/.cache/<app>`       | `%LOCALAPPDATA%\<app>\Cache` | `$XDG_CACHE_HOME`  |
 
 macOS uses XDG conventions (same as Linux) for a unified Unix mental model.
 
@@ -131,12 +137,12 @@ const store = createStore(options);
 
 #### Options
 
-| Option         | Type                       | Required | Description                                                        |
-| -------------- | -------------------------- | -------- | ------------------------------------------------------------------ |
-| `dirPath`      | `string`                   | Yes      | Absolute directory path where the JSON file is stored.             |
-| `name`         | `string`                   | No       | Store name used as filename (default `"config"` → `config.json`).  |
-| `fields`       | `FieldsDef`                | Yes      | Field definitions defining the store's data shape, types, defaults, and optional validation. |
-| `pruneUnknown` | `boolean`                  | No       | Drop unknown persisted keys on read (default `true`).              |
+| Option         | Type        | Required | Description                                                                                  |
+| -------------- | ----------- | -------- | -------------------------------------------------------------------------------------------- |
+| `dirPath`      | `string`    | Yes      | Absolute directory path where the JSON file is stored.                                       |
+| `name`         | `string`    | No       | Store name used as filename (default `"config"` → `config.json`).                            |
+| `fields`       | `FieldsDef` | Yes      | Field definitions defining the store's data shape, types, defaults, and optional validation. |
+| `pruneUnknown` | `boolean`   | No       | Drop unknown persisted keys on read (default `true`).                                        |
 
 ### `store.read()`
 
@@ -311,23 +317,21 @@ Merged defaults exist only in memory. The persisted file remains unchanged until
 
 Add per-field validation to enforce config integrity on every read, write, update, and patch. When a `validate` function is configured on a field, validation is **strict by default** — invalid values fail loudly.
 
-### Using `@crustjs/validate`
+### Schema-driven validation
 
-The easiest way to add validation is with field adapters from `@crustjs/validate`:
+The easiest way to add validation is with the built-in `field()` factory.
+It builds a `FieldDef` from any [Standard Schema v1](https://standardschema.dev/)
+object. Crust stores raw values; the schema validates and transforms them on
+read/write.
 
 ```ts
 import { z } from "zod";
-import { field } from "@crustjs/validate/zod";
-import { createStore, configDir } from "@crustjs/store";
+import { createStore, configDir, field } from "@crustjs/store";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
   fields: {
-    theme: {
-      type: "string",
-      default: "light",
-      validate: field(z.enum(["light", "dark"])),
-    },
+    theme: field(z.enum(["light", "dark"]).default("light")),
     verbose: { type: "boolean", default: false },
   },
 });
@@ -341,33 +345,55 @@ const config = await store.read();
 // → throws if persisted config is invalid
 ```
 
-`fieldSync()` is also available for synchronous schemas.
-
-For Effect schemas, wrap with `Schema.standardSchemaV1()`:
+For Effect schemas, wrap once with `Schema.standardSchemaV1()`:
 
 ```ts
 import * as Schema from "effect/Schema";
-import { field } from "@crustjs/validate/effect";
+import { createStore, configDir, field } from "@crustjs/store";
 
 const store = createStore({
   dirPath: configDir("my-cli"),
   fields: {
-    theme: {
-      type: "string",
-      default: "light",
-      validate: field(
-        Schema.standardSchemaV1(
-          Schema.Literal("light", "dark"),
-        ),
-      ),
-    },
+    theme: field(Schema.standardSchemaV1(Schema.Literal("light", "dark"))),
   },
 });
 ```
 
+Missing persisted values flow through the schema as `undefined`:
+
+- `field(z.string().default("x"))` returns `"x"` on read when the field
+  is missing from disk.
+- `field(z.string().optional())` returns `undefined`.
+- `field(z.string())` fails read-time validation with a `VALIDATION`
+  error when the field is missing.
+
+#### Schema-derived defaults and TypeScript
+
+Standard Schema v1 has no spec-portable type-level access to schema
+defaults. Crust does not inspect schemas to populate runtime metadata;
+defaults are materialized on read by validating `undefined` through the
+schema. As a result:
+
+- `field(z.string().default("x"))` returns `"x"` on read, but the
+  inferred config type is `string | undefined` (NOT narrowed).
+- `field(z.string(), { default: "x" })` keeps `"x"` as the Crust-level
+  default AND narrows the inferred config type to `string`.
+
+Prefer the explicit form when the field is required to always have a
+value at use sites.
+
+#### `field()` throws on invalid input
+
+`field()` throws `CrustStoreError("DEFINITION")` when handed a value that
+is not a Standard Schema v1 object. `type` is optional for schema-backed
+fields; pass it through `opts` only as legacy metadata for tooling.
+
 ### Custom validators
 
-You can also provide a validator function directly on each field:
+You can also provide a validator function directly on each field. Validators
+return `void` on success and **throw** on failure — the thrown `Error`'s
+`message` is captured as the issue text and the field name is used as the
+issue path.
 
 ```ts
 const store = createStore({
@@ -377,28 +403,45 @@ const store = createStore({
       type: "string",
       default: "light",
       validate(value) {
-        const str = value as string;
-        if (str !== "light" && str !== "dark") {
-          return {
-            ok: false,
-            issues: [{ message: 'Must be "light" or "dark"', path: "" }],
-          };
+        if (value !== "light" && value !== "dark") {
+          throw new Error('Must be "light" or "dark"');
         }
-        return { ok: true, value: str };
       },
     },
   },
 });
 ```
 
-The per-field `validate` function follows the `StoreValidator<T>` contract: `(value: unknown) => StoreValidatorResult<T> | Promise<StoreValidatorResult<T>>`, where `StoreValidatorResult<T>` is `{ ok: true, value: T } | { ok: false, issues: StoreValidatorIssue[] }`.
+Hand-rolled `validate` callbacks are `(value: V) => void | Promise<void>`.
+Return `void` (or `Promise<void>`) to accept; throw an `Error` to reject.
+These remain validation-only — they cannot transform the persisted value.
+
+Fields built via the `field()` factory carry a Standard Schema and DO
+persist transforms on `write` / `update` / `patch` (e.g.
+`field(z.string().transform(s => s.trim()))` writes the trimmed value to
+disk). On `read`, the schema still validates the persisted value but its
+transform output is discarded — the on-disk value is returned unchanged.
+Existing on-disk values survive unchanged across upgrades; the first
+subsequent write canonicalizes them through the transform.
+
+A write-time **read-stability guard** rejects cross-type transforms whose
+output would fail the schema's own re-validation. For example,
+`field(z.string().transform(Number))` (string in, number out) is rejected
+with `CrustStoreError("VALIDATION")` and an issue message tagged
+`read-unstable transform`. No on-disk write occurs.
 
 ### Validation behavior
 
-- **Write**: Validates each field before persisting. If a validator transforms the value, the transformed result is persisted.
-- **Read**: Validates each field after applying defaults. Invalid persisted config fails loudly — no silent fallback to defaults.
-- **Update**: Reads raw config (no validation), applies updater, validates each field, then persists.
-- **Patch**: Reads raw config, applies shallow partial merge, validates each field, then persists.
+- **Write**: Validates each field before persisting. Schema-driven
+  transforms (via `field()`) replace the input value with the transformed
+  output; hand-rolled validators cannot transform.
+- **Read**: Validates each field after applying defaults. Invalid persisted
+  config fails loudly — no silent fallback to defaults. Schema transform
+  output is discarded on read; the returned value matches what is on disk.
+- **Update**: Reads raw config (no validation), applies updater, validates
+  each field (persisting any schema-transformed outputs), then persists.
+- **Patch**: Reads raw config, applies shallow partial merge, validates each
+  field (persisting any schema-transformed outputs), then persists.
 - **Reset**: No validation — just removes the persisted file.
 
 ### Catching validation errors
@@ -410,7 +453,7 @@ try {
   await store.read();
 } catch (err) {
   if (err instanceof CrustStoreError && err.is("VALIDATION")) {
-    // err.details is { operation: "read" | "write" | "update" | "patch", issues: StoreValidationIssue[] }
+    // err.details is { operation: "read" | "write" | "update" | "patch", issues: StoreValidatorIssue[] }
     console.error(`Validation failed during ${err.details.operation}:`);
     for (const issue of err.details.issues) {
       console.error(`  ${issue.path || "(root)"}: ${issue.message}`);
@@ -423,12 +466,13 @@ try {
 
 All errors thrown by `@crustjs/store` are instances of `CrustStoreError` with a typed `code` property:
 
-| Code         | When                                                            | Details                     |
-| ------------ | --------------------------------------------------------------- | --------------------------- |
-| `PATH`       | Invalid `dirPath`, invalid `name`, unsupported platform         | `{ path: string }`         |
-| `PARSE`      | Malformed JSON in persisted config file                         | `{ path: string }`         |
-| `IO`         | Filesystem read, write, or delete failure                       | `{ path, operation }`      |
-| `VALIDATION` | Config fails validator on read, write, update, or patch         | `{ operation, issues }`    |
+| Code         | When                                                    | Details                 |
+| ------------ | ------------------------------------------------------- | ----------------------- |
+| `PATH`       | Invalid `dirPath`, invalid `name`, unsupported platform | `{ path: string }`      |
+| `PARSE`      | Malformed JSON in persisted config file                 | `{ path: string }`      |
+| `IO`         | Filesystem read, write, or delete failure               | `{ path, operation }`   |
+| `VALIDATION` | Config fails validator on read, write, update, or patch | `{ operation, issues }` |
+| `DEFINITION` | `field()` received an invalid (non-Standard-Schema) input | `{ vendor? }`         |
 
 ### Catching errors by code
 
@@ -488,33 +532,33 @@ import type {
   StoreUpdater,
   FieldDef,
   FieldsDef,
+  FieldOptions,
   InferStoreConfig,
-  StoreValidator,
-  StoreValidatorResult,
   StoreValidatorIssue,
   StoreErrorCode,
-  StoreValidationIssue,
   ValidationErrorDetails,
+  DefinitionErrorDetails,
+  ValueType,
   PlatformEnv,
 } from "@crustjs/store";
 ```
 
-| Type                      | Description                                                             |
-| ------------------------- | ----------------------------------------------------------------------- |
-| `CreateStoreOptions`      | Options object for `createStore()`.                                     |
-| `Store`                   | Store instance with `read`, `write`, `update`, `patch`, `reset`.        |
-| `StoreUpdater`            | Updater function type `(current: T) => T`.                              |
-| `FieldDef`                | Single field definition with `type`, optional `default`, and optional `validate`. |
-| `FieldsDef`               | Record of field names to `FieldDef` definitions.                        |
-| `InferStoreConfig`        | Inferred store state type from a `FieldsDef` definition.                |
-| `StoreValidator`          | Validator function contract `(value: unknown) => StoreValidatorResult`. |
-| `StoreValidatorResult`    | Discriminated union: `{ ok: true, value: T } \| { ok: false, issues: StoreValidatorIssue[] }`. |
-| `StoreValidatorIssue`     | `{ message: string, path: string }`.                                   |
-| `StoreValidationIssue`    | Validation issue in error details payload.                              |
-| `ValidationErrorDetails`  | Error details for `VALIDATION` code: `{ operation, issues }`.          |
-| `StoreErrorCode`          | Union of error codes: `"PATH" \| "PARSE" \| "IO" \| "VALIDATION"`.    |
-| `PlatformEnv`             | Injectable platform environment for testing path helpers.               |
-| `CrustStoreError`         | Typed error class with `code`, `details`, and `cause`.                  |
+| Type                     | Description                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `CreateStoreOptions`     | Options object for `createStore()`.                                                            |
+| `Store`                  | Store instance with `read`, `write`, `update`, `patch`, `reset`.                               |
+| `StoreUpdater`           | Updater function type `(current: T) => T`.                                                     |
+| `FieldDef`               | Single field definition with `type`, optional `default`, and optional `validate`.              |
+| `FieldsDef`              | Record of field names to `FieldDef` definitions.                                               |
+| `FieldOptions`           | Optional Crust metadata accepted by the `field()` factory (`type`, `default`, `array`, `description`). |
+| `InferStoreConfig`       | Inferred store state type from a `FieldsDef` definition.                                       |
+| `StoreValidatorIssue`    | `{ message: string, path: string }`.                                                           |
+| `ValidationErrorDetails` | Error details for `VALIDATION` code: `{ operation, issues }`.                                  |
+| `DefinitionErrorDetails` | Error details for `DEFINITION` code: `{ vendor? }`.                                            |
+| `StoreErrorCode`         | Union of error codes: `"PATH" \| "PARSE" \| "IO" \| "VALIDATION" \| "DEFINITION"`.             |
+| `ValueType`              | Supported field type literals: `"string" \| "number" \| "boolean"`.                            |
+| `PlatformEnv`            | Injectable platform environment for testing path helpers.                                      |
+| `CrustStoreError`        | Typed error class with `code`, `details`, and `cause`.                                         |
 
 ## Scope & Non-Goals
 

package/dist/index.d.ts

@@ -1,13 +1,6 @@
+import { BaseValueType, ResolvePrimitive } from "@crustjs/utils";
 /** 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;
+type ValueType = BaseValueType;
 /** Shared fields present on every store field definition. */
 interface FieldDefBase<V> {
 	/** Human-readable description for documentation and tooling. */
@@ -16,14 +9,33 @@ interface FieldDefBase<V> {
 	* 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.
+	* 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.
-	* @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>;
+	validate?: (value: V) => void | Promise<void> | {
+		value: unknown;
+	} | Promise<{
+		value: unknown;
+	}>;
+	/** Internal marker: validate missing values as `undefined` for schema-backed fields. */
+	validateMissing?: true;
 }
 /** Base for scalar (non-array) fields — `array` must be omitted. */
 interface ScalarFieldBase<V> extends FieldDefBase<V> {
@@ -93,9 +105,18 @@ interface BooleanArrayFieldDef extends ArrayFieldBase<boolean[]> {
 * } satisfies FieldsDef;
 * ```
 */
-type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef;
+interface RawScalarFieldDef extends ScalarFieldBase<unknown> {
+	type?: never;
+	default?: unknown;
+}
+interface RawArrayFieldDef extends ArrayFieldBase<unknown[]> {
+	type?: never;
+	default?: readonly unknown[];
+}
+type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef | RawScalarFieldDef | RawArrayFieldDef;
 /** Record mapping field names to their definitions. */
 type FieldsDef = Record<string, FieldDef>;
+declare const FIELD_SCHEMA_OUTPUT: unique symbol;
 /**
 * Infer the resolved type for a single field definition.
 *
@@ -104,12 +125,20 @@ type FieldsDef = Record<string, FieldDef>;
 * - **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;
+} ? 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;
+} ? ResolvePrimitive<F["type"]> : ResolvePrimitive<F["type"]> | undefined : F extends {
+	default: infer D;
+} ? D : unknown;
 /**
 * Maps a full {@link FieldsDef} record to the inferred config object type.
 *
@@ -318,6 +347,17 @@ interface ValidationErrorDetails {
 	issues: readonly StoreValidatorIssue[];
 }
 /**
+* Contextual details attached to a `DEFINITION` error.
+*
+* Returned when a `field()` call cannot produce a valid `FieldDef` from the
+* provided schema and options — e.g. the input is not a Standard Schema v1
+* object.
+*/
+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.
@@ -327,6 +367,7 @@ interface StoreErrorDetailsMap {
 	PARSE: ParseErrorDetails;
 	IO: IOErrorDetails;
 	VALIDATION: ValidationErrorDetails;
+	DEFINITION: DefinitionErrorDetails;
 }
 /**
 * All possible error codes emitted by `@crustjs/store`.
@@ -335,6 +376,7 @@ interface StoreErrorDetailsMap {
 * - `PARSE` — Malformed JSON in persisted config file
 * - `IO` — Filesystem read, write, or delete failure
 * - `VALIDATION` — Config object rejected by a store validator
+* - `DEFINITION` — `field()` cannot produce a valid `FieldDef` from the given schema/options
 *
 * @example
 * ```ts
@@ -422,6 +464,144 @@ declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends
 	*/
 	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;
+}
+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>;
 /**
 * Encapsulates runtime environment values needed for path resolution.
 *
@@ -576,4 +756,4 @@ declare function cacheDir(appName: string, env?: PlatformEnv): string;
 * ```
 */
 declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
-export { stateDir, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };
+export { stateDir, field, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldOptions, FieldDef, DefinitionErrorDetails, CrustStoreError, CreateStoreOptions };

package/dist/index.js

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

package/package.json

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