@crustjs/store 0.1.0 → 0.1.1

package/README.md

@@ -85,7 +85,7 @@ const config = createStore({
 const data = createStore({
   dirPath: dataDir("my-cli"),
   fields: {
-    bookmarks: { type: "array", default: [] },
+    bookmarks: { type: "string", array: true, default: [] },
   },
 });
 
@@ -320,8 +320,9 @@ 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";
@@ -358,33 +359,34 @@ const store = createStore({
 });
 ```
 
+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
 
@@ -470,6 +472,7 @@ All errors thrown by `@crustjs/store` are instances of `CrustStoreError` with a
 | `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
 
@@ -529,13 +532,13 @@ import type {
   StoreUpdater,
   FieldDef,
   FieldsDef,
+  FieldOptions,
   InferStoreConfig,
-  StoreValidator,
-  StoreValidatorResult,
   StoreValidatorIssue,
   StoreErrorCode,
-  StoreValidationIssue,
   ValidationErrorDetails,
+  DefinitionErrorDetails,
+  ValueType,
   PlatformEnv,
 } from "@crustjs/store";
 ```
@@ -547,13 +550,13 @@ import type {
 | `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.                                       |
-| `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"`.                             |
+| `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`.                                         |
 

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.
 *
@@ -339,11 +351,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 +464,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 +481,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 +586,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.
 *

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 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.1.0",
+	"version": "0.1.1",
 	"description": "DX-first, typed persistence for CLI apps with config/data/state/cache separation",
 	"type": "module",
 	"license": "MIT",
@@ -48,13 +48,13 @@
 	"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.2"
 	}
 }