@crustjs/store 0.1.0 → 0.2.0

package/README.md

@@ -25,12 +25,12 @@ pnpm add @crustjs/store
 import { createStore, configDir } from "@crustjs/store";
 
 const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme: { type: "string", default: "light" },
-    fontSize: { type: "number", default: 14 },
-    verbose: { type: "boolean", default: false },
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		theme: { type: "string", default: "light" },
+		fontSize: { type: "number", default: 14 },
+		verbose: { type: "boolean", default: false },
+	},
 });
 
 // Read state (returns defaults when no persisted file exists)
@@ -64,47 +64,41 @@ No explicit generics needed — types are inferred from your `fields` definition
 | `cacheDir`  | Regenerable cached data   | HTTP caches, compiled assets           |
 
 ```ts
-import {
-  createStore,
-  configDir,
-  dataDir,
-  stateDir,
-  cacheDir,
-} from "@crustjs/store";
+import { createStore, configDir, dataDir, stateDir, cacheDir } from "@crustjs/store";
 
 // User preferences → ~/.config/my-cli/config.json
 const config = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme: { type: "string", default: "light" },
-    verbose: { type: "boolean", default: false },
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		theme: { type: "string", default: "light" },
+		verbose: { type: "boolean", default: false },
+	},
 });
 
 // App data → ~/.local/share/my-cli/config.json
 const data = createStore({
-  dirPath: dataDir("my-cli"),
-  fields: {
-    bookmarks: { type: "array", default: [] },
-  },
+	dirPath: dataDir("my-cli"),
+	fields: {
+		bookmarks: { type: "string", array: true, default: [] },
+	},
 });
 
 // Runtime state → ~/.local/state/my-cli/config.json
 const state = createStore({
-  dirPath: stateDir("my-cli"),
-  fields: {
-    lastOpened: { type: "string", default: "" },
-    scrollY: { type: "number", default: 0 },
-  },
+	dirPath: stateDir("my-cli"),
+	fields: {
+		lastOpened: { type: "string", default: "" },
+		scrollY: { type: "number", default: 0 },
+	},
 });
 
 // Cache → ~/.cache/my-cli/config.json
 const cache = createStore({
-  dirPath: cacheDir("my-cli"),
-  fields: {
-    etag: { type: "string", default: "" },
-    payload: { type: "string", default: "" },
-  },
+	dirPath: cacheDir("my-cli"),
+	fields: {
+		etag: { type: "string", default: "" },
+		payload: { type: "string", default: "" },
+	},
 });
 ```
 
@@ -137,12 +131,55 @@ 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`).                                                        |
+| `access`       | `"default" \| "private" \| { file?: number; directory?: number }` | No       | Persistence visibility. Use `"private"` for owner-only secret stores, or pass explicit Unix permission bits. |
+
+#### Securing secrets
+
+Config/state stores that hold tokens or API keys should not be world-readable. Pass `access: "private"` so the file is owner-only on Unix:
+
+```ts
+const auth = createStore({
+	dirPath: configDir("my-cli"),
+	name: "auth",
+	fields: { token: { type: "string" } },
+	access: "private",
+});
+
+await auth.write({ token: "secret" }); // auth.json is 0600 even under a permissive umask
+```
+
+`access: "private"` maps to `0600` for the file (`rw-------`) and `0700` for the parent directory (`rwx------`, only when created). The file mode is enforced on the temp file before the atomic rename, so the persisted file is never momentarily group/other-readable.
+
+The built-in string presets are intentionally small:
+
+| Access                | File                                                  | Directory                                             | Use case                                                                  |
+| --------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
+| omitted / `"default"` | Platform default, usually `0644` after a common umask | Platform default, usually `0755` after a common umask | Non-secret stores where the user's environment should decide permissions. |
+| `"private"`           | `0600`                                                | `0700`                                                | Secret-bearing stores such as tokens, API keys, and local auth state.     |
+
+Advanced callers can provide explicit permission bits without adding more named presets:
+
+```ts
+const store = createStore({
+	dirPath: configDir("my-cli"),
+	name: "auth",
+	fields: { token: { type: "string" } },
+	// Owner-only secret store (same as access: "private")
+	access: { file: 0o600, directory: 0o700 },
+	// Group-readable store; group ownership is managed outside @crustjs/store
+	// access: { file: 0o640, directory: 0o750 },
+	// World-readable non-secret store
+	// access: { file: 0o644, directory: 0o755 },
+});
+```
+
+**Platform behavior:** `access` permission bits are enforced on **macOS and Linux** (and other Unix systems), where POSIX permission bits are checked by the OS. On **Windows** they are **not enforced** — Windows uses ACLs, not Unix bits, so `access: "private"` does not make a file owner-only there. The store does not throw or warn in this case. On Windows, confidentiality relies on the ACL inherited from the parent directory; the per-user profile location resolved by `configDir` / `stateDir` (under `%APPDATA%` / `%LOCALAPPDATA%`) is already restricted to the user. If you need strong secret confidentiality on Windows, use the OS credential store (Windows Credential Manager / DPAPI) rather than file permissions.
 
 ### `store.read()`
 
@@ -170,8 +207,8 @@ Reads the current effective state, applies the updater function, and atomically
 
 ```ts
 await store.update((current) => ({
-  ...current,
-  theme: "dark",
+	...current,
+	theme: "dark",
 }));
 ```
 
@@ -260,21 +297,21 @@ const dir = configDir("my-cli");
 
 // Default store → ~/.config/my-cli/config.json
 const settingsStore = createStore({
-  dirPath: dir,
-  fields: {
-    theme: { type: "string", default: "light" },
-    fontSize: { type: "number", default: 14 },
-    verbose: { type: "boolean", default: false },
-  },
+	dirPath: dir,
+	fields: {
+		theme: { type: "string", default: "light" },
+		fontSize: { type: "number", default: 14 },
+		verbose: { type: "boolean", default: false },
+	},
 });
 
 // Auth store → ~/.config/my-cli/auth.json
 const authStore = createStore({
-  dirPath: dir,
-  name: "auth",
-  fields: {
-    token: { type: "string", default: "" },
-  },
+	dirPath: dir,
+	name: "auth",
+	fields: {
+		token: { type: "string", default: "" },
+	},
 });
 ```
 
@@ -288,12 +325,12 @@ When a persisted file exists, `read()` fills missing keys from field `defaults`:
 
 ```ts
 const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme: { type: "string", default: "light" },
-    fontSize: { type: "number", default: 14 },
-    verbose: { type: "boolean", default: false },
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		theme: { type: "string", default: "light" },
+		fontSize: { type: "number", default: 14 },
+		verbose: { type: "boolean", default: false },
+	},
 });
 
 // Persisted file contains: { "theme": "dark", "verbose": true }
@@ -320,19 +357,20 @@ Add per-field validation to enforce config integrity on every read, write, updat
 ### Schema-driven validation
 
 The easiest way to add validation is with the built-in `field()` factory.
-It builds a complete `FieldDef` from any Standard Schema — type, default,
-description, and the per-field validator are all derived in one call:
+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 { createStore, configDir, field } from "@crustjs/store";
 
 const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme: field(z.enum(["light", "dark"]).default("light")),
-    verbose: { type: "boolean", default: false },
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		theme: field(z.enum(["light", "dark"]).default("light")),
+		verbose: { type: "boolean", default: false },
+	},
 });
 
 // write() validates before persisting
@@ -351,40 +389,41 @@ 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"))),
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		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. As a result:
+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"))` populates `default: "x"` at runtime,
-  but the inferred config type is `string | undefined` (NOT narrowed).
-- `field(z.string(), { default: "x" })` populates `default: "x"` AND
-  narrows the inferred config type to `string`.
+- `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
-non-Standard-Schema value, or when the runtime CLI type cannot be
-inferred from the schema and `opts.type` was not supplied. The thrown
-error's `details.vendor` field carries the schema's vendor name (when
-available) to help locate the offending call site.
-
-> **Effect ≥ 3.14.2 required.** Effect 3.14.2 made `standardSchemaV1(...)`
-> wrappers expose `.ast`, which is what the validate registry walks. On
-> Effect 3.14.0 / 3.14.1 the wrapper is a plain object and introspection
-> silently fails. See
-> [`@crustjs/validate` Effect setup](https://crustjs.com/docs/modules/validate#quick-start--effect)
-> for the floor and a workaround.
+`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
 
@@ -395,18 +434,18 @@ issue path.
 
 ```ts
 const store = createStore({
-  dirPath: configDir("my-cli"),
-  fields: {
-    theme: {
-      type: "string",
-      default: "light",
-      validate(value) {
-        if (value !== "light" && value !== "dark") {
-          throw new Error('Must be "light" or "dark"');
-        }
-      },
-    },
-  },
+	dirPath: configDir("my-cli"),
+	fields: {
+		theme: {
+			type: "string",
+			default: "light",
+			validate(value) {
+				if (value !== "light" && value !== "dark") {
+					throw new Error('Must be "light" or "dark"');
+				}
+			},
+		},
+	},
 });
 ```
 
@@ -448,15 +487,15 @@ with `CrustStoreError("VALIDATION")` and an issue message tagged
 import { CrustStoreError } from "@crustjs/store";
 
 try {
-  await store.read();
+	await store.read();
 } catch (err) {
-  if (err instanceof CrustStoreError && err.is("VALIDATION")) {
-    // 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}`);
-    }
-  }
+	if (err instanceof CrustStoreError && err.is("VALIDATION")) {
+		// 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}`);
+		}
+	}
 }
 ```
 
@@ -464,12 +503,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
 
@@ -477,19 +517,19 @@ All errors thrown by `@crustjs/store` are instances of `CrustStoreError` with a
 import { CrustStoreError } from "@crustjs/store";
 
 try {
-  const state = await store.read();
+	const state = await store.read();
 } catch (err) {
-  if (err instanceof CrustStoreError) {
-    switch (err.code) {
-      case "PARSE":
-        console.error(`Corrupt file at ${err.details.path}`);
-        console.error("Delete the file and retry, or fix the JSON manually.");
-        break;
-      case "IO":
-        console.error(`File ${err.details.operation} failed: ${err.message}`);
-        break;
-    }
-  }
+	if (err instanceof CrustStoreError) {
+		switch (err.code) {
+			case "PARSE":
+				console.error(`Corrupt file at ${err.details.path}`);
+				console.error("Delete the file and retry, or fix the JSON manually.");
+				break;
+			case "IO":
+				console.error(`File ${err.details.operation} failed: ${err.message}`);
+				break;
+		}
+	}
 }
 ```
 
@@ -499,8 +539,8 @@ The `.is()` method narrows the error type so `details` is fully typed:
 
 ```ts
 if (err instanceof CrustStoreError && err.is("IO")) {
-  // err.details is { path: string; operation: "read" | "write" | "delete" }
-  console.error(err.details.operation, err.details.path);
+	// err.details is { path: string; operation: "read" | "write" | "delete" }
+	console.error(err.details.operation, err.details.path);
 }
 ```
 
@@ -510,7 +550,7 @@ if (err instanceof CrustStoreError && err.is("IO")) {
 
 ```ts
 if (err instanceof CrustStoreError && err.is("VALIDATION")) {
-  console.error("Validation error:", err.cause);
+	console.error("Validation error:", err.cause);
 }
 ```
 
@@ -524,38 +564,38 @@ All types are exported for use in your application:
 
 ```ts
 import type {
-  CreateStoreOptions,
-  Store,
-  StoreUpdater,
-  FieldDef,
-  FieldsDef,
-  InferStoreConfig,
-  StoreValidator,
-  StoreValidatorResult,
-  StoreValidatorIssue,
-  StoreErrorCode,
-  StoreValidationIssue,
-  ValidationErrorDetails,
-  PlatformEnv,
+	CreateStoreOptions,
+	Store,
+	StoreUpdater,
+	FieldDef,
+	FieldsDef,
+	FieldOptions,
+	InferStoreConfig,
+	StoreValidatorIssue,
+	StoreErrorCode,
+	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. */
@@ -41,6 +34,8 @@ interface FieldDefBase<V> {
 	} | 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> {
@@ -110,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.
 *
@@ -121,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.
 *
@@ -149,6 +161,22 @@ interface StoreValidatorIssue {
 	/** 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}.
 *
@@ -198,6 +226,25 @@ interface CreateStoreOptions<F extends FieldsDef> {
 	* @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.
@@ -339,11 +386,10 @@ interface ValidationErrorDetails {
 *
 * Returned when a `field()` call cannot produce a valid `FieldDef` from the
 * provided schema and options — e.g. the input is not a Standard Schema v1
-* object, or the schema is of an unknown vendor and `opts.type` was not
-* supplied so the runtime CLI type cannot be inferred.
+* object.
 */
 interface DefinitionErrorDetails {
-	/** The schema vendor name, when the failing input was a Standard Schema. */
+	/** The schema vendor name, when available. */
 	vendor?: string;
 }
 /**
@@ -453,16 +499,14 @@ declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends
 	*/
 	withCause(cause: unknown): this;
 }
-import { InferOutput, StandardSchema } from "@crustjs/schema-utils";
+import { BaseValueType as BaseValueType2 } from "@crustjs/utils";
+import { InferOutput, StandardSchema } from "@crustjs/utils/schema";
 /**
-* Optional overrides for the introspected `FieldDef` shape produced by
-* {@link field}.
+* Optional Crust metadata for the `FieldDef` shape produced by {@link field}.
 *
-* Every key is optional. When automatic introspection covers a field
-* (`type`, `description`, `default`, `array`), explicit values override
-* the introspection silently. For schemas with unknown vendors (e.g.
-* Valibot, ArkType), `type` MUST be supplied explicitly because no
-* inference is available.
+* 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(...)`
@@ -472,122 +516,79 @@ import { InferOutput, StandardSchema } from "@crustjs/schema-utils";
 *               `default` key when the user wants a non-`undefined` field.
 */
 interface FieldOptions<T = unknown> {
-	type?: "string" | "number" | "boolean";
+	type?: BaseValueType2;
 	description?: string;
 	/**
-	* Default value for this field when the persisted state does not contain
-	* a value for it. Passing `default` explicitly here narrows the inferred
-	* config type from `T | undefined` to `T`. Schema-derived defaults
-	* (e.g. `z.string().default("x")`) populate the runtime default but do
-	* NOT narrow the TypeScript type — pass it explicitly here for tight
-	* typing.
+	* 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 ValueType2 = "string" | "number" | "boolean";
-type StripUndefined<T> = Exclude<T, undefined>;
-type PrimitiveToValueType<T> = [T] extends [string] ? "string" : [T] extends [number] ? "number" : [T] extends [boolean] ? "boolean" : ValueType2;
-/**
-* Resolve the runtime CLI value-type from a Standard Schema's output type.
-*
-* Array schemas are detected via `IsArrayOutput`; their element type drives
-* the value-type literal so `field(z.array(z.string()))` resolves to
-* `{ type: "string"; array: true }`.
-*/
-type IsArrayOutput<S> = S extends StandardSchema<infer _I, infer Out> ? StripUndefined<Out> extends readonly unknown[] ? true : false : false;
-type ArrayElementOutput<S> = S extends StandardSchema<infer _I, infer Out> ? StripUndefined<Out> extends readonly (infer E)[] ? E : never : never;
-type ResolveScalarType<S> = S extends StandardSchema<infer _I, infer Out> ? PrimitiveToValueType<StripUndefined<Out>> : ValueType2;
-/** A scalar `FieldDef` with no narrowed default. */
-type ScalarFieldDef<T extends ValueType2> = {
-	readonly type: T;
-	readonly description?: string;
-	readonly validate: (value: unknown) => Promise<{
-		value: unknown;
-	}>;
-};
-/** A scalar `FieldDef` with a narrowed default. */
-type ScalarFieldDefWithDefault<
-	T extends ValueType2,
-	D
-> = {
-	readonly type: T;
+type RawSchemaFieldDef<Out> = {
+	readonly type?: never;
+	readonly array?: never;
 	readonly description?: string;
-	readonly default: D;
 	readonly validate: (value: unknown) => Promise<{
 		value: unknown;
 	}>;
+	readonly validateMissing: true;
+	readonly [FIELD_SCHEMA_OUTPUT]?: Out;
 };
-/** An array `FieldDef` with no narrowed default. */
-type ArrayFieldDef<T extends ValueType2> = {
-	readonly type: T;
+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 description?: string;
-	readonly validate: (value: unknown) => Promise<{
-		value: unknown;
-	}>;
-};
-/** An array `FieldDef` with a narrowed default. */
-type ArrayFieldDefWithDefault<
-	T extends ValueType2,
-	D
-> = {
-	readonly type: T;
-	readonly array: true;
-	readonly description?: string;
+} : {
+	readonly array?: never;
+}) & ([D] extends [never] ? unknown : {
 	readonly default: D;
-	readonly validate: (value: unknown) => Promise<{
-		value: unknown;
-	}>;
-};
+});
 /**
 * `FieldDef` inferred from a Standard Schema, with no narrowed default.
 *
-* Schema-derived defaults are populated at runtime but do NOT narrow the
-* TypeScript type — Standard Schema v1 has no spec-portable type-level
-* access to defaults. Pass `field(schema, { default: x })` explicitly to
-* narrow.
-*/
-type SchemaFieldDef<S extends StandardSchema> = IsArrayOutput<S> extends true ? ArrayFieldDef<PrimitiveToValueType<StripUndefined<ArrayElementOutput<S>>>> : ScalarFieldDef<ResolveScalarType<S>>;
-/**
-* `FieldDef` inferred from a Standard Schema, with the explicit `opts.default`
-* narrowed into the type.
+* 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 SchemaFieldDefWithDefault<
-	S extends StandardSchema,
-	D
-> = IsArrayOutput<S> extends true ? ArrayFieldDefWithDefault<PrimitiveToValueType<StripUndefined<ArrayElementOutput<S>>>, D> : ScalarFieldDefWithDefault<ResolveScalarType<S>, D>;
+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.
-* Auto-derives `type`, `array`, `description`, and `default` from the
-* schema (Zod and Effect natively; Valibot/ArkType via the
-* `validate(undefined)` fallback for defaults). Pass `opts` to override
-* any key explicitly — explicit values win silently.
+* 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**: schema-derived defaults populate at runtime but
-* do NOT narrow the inferred config type. For tight typing of
-* default-bearing fields, pass `default` via `opts`:
+* **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"))                       // state: string | undefined
-* field(z.string(), { default: "x" })                  // state: string
+* 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 store-field metadata; explicit keys override
-*                   the introspected values silently
+* @param opts - Optional Crust-level metadata
 * @throws {CrustStoreError} With code `"DEFINITION"` when the input is not
-*         a Standard Schema, or when the runtime CLI type cannot be inferred
-*         and `opts.type` was not supplied.
+*         a Standard Schema v1 object.
 *
 * @example Zod
 * ```ts
@@ -620,11 +621,22 @@ type SchemaFieldDefWithDefault<
 declare function field<S extends StandardSchema>(schema: S): SchemaFieldDef<S>;
 declare function field<
 	S extends StandardSchema,
-	D extends InferOutput<S>
+	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;
-}): SchemaFieldDefWithDefault<S, D>;
-declare function field<S extends StandardSchema>(schema: S, opts: FieldOptions<InferOutput<S>>): SchemaFieldDef<S>;
+	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.
 *
@@ -779,4 +791,4 @@ declare function cacheDir(appName: string, env?: PlatformEnv): string;
 * ```
 */
 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 };
+export { stateDir, field, dataDir, createStore, configDir, cacheDir, ValueType, ValidationErrorDetails, StoreValidatorIssue, StoreUpdater, StorePermissionBits, StoreErrorCode, StoreAccess, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldOptions, FieldDef, DefinitionErrorDetails, CrustStoreError, CreateStoreOptions };

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/store",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"license": "MIT",
@@ -48,13 +48,14 @@
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
 		"bunup": "^0.16.31",
-		"effect": "3.14.2",
+		"effect": "3.21.2",
 		"zod": "^4.0.0"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {
-		"@crustjs/schema-utils": "0.0.1"
+		"@crustjs/utils": "0.0.3",
+		"@standard-schema/spec": "^1.1.0"
 	}
 }