@crustjs/store 0.0.1

package/README.md

@@ -0,0 +1,341 @@
+# @crustjs/store
+
+Minimal, DX-first, type-safe config persistence for CLI apps.
+
+`@crustjs/store` gives your CLI a production-ready config store with near-zero setup. Declare your fields, get full type inference, and let the store handle path resolution, file IO, defaults, and error mapping.
+
+## Install
+
+```sh
+# bun
+bun add @crustjs/store
+
+# npm
+npm install @crustjs/store
+
+# pnpm
+pnpm add @crustjs/store
+```
+
+**Requirements:** Bun 1.x or Node 18+. TypeScript 5.x recommended.
+
+## Quick Start
+
+```ts
+import { createStore, configDir } from "@crustjs/store";
+
+const store = createStore({
+  dirPath: configDir("my-cli"),
+  fields: {
+    theme: { type: "string", default: "light" },
+    verbose: { type: "boolean", default: false },
+    token: { type: "string" }, // optional — no default
+  },
+});
+
+// Read config (returns defaults when no persisted file exists)
+const config = await store.read();
+// → { theme: "light", verbose: false, token: undefined }
+
+// Write a full config object
+await store.write({ theme: "dark", verbose: true, token: "abc123" });
+
+// Update a single field
+await store.update((current) => ({ ...current, verbose: false }));
+
+// Reset to defaults (removes persisted file)
+await store.reset();
+```
+
+No explicit generics needed — types are inferred from your field definitions.
+
+## API
+
+### `createStore(options)`
+
+Creates a typed async config store backed by a local JSON file. The file path is resolved once at creation time.
+
+```ts
+const store = createStore(options);
+```
+
+**Returns:** A `Store<TConfig>` with `read()`, `write()`, `update()`, and `reset()` methods.
+
+**Throws:** `CrustStoreError` with `PATH` code if `dirPath` or `name` is invalid.
+
+#### 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 that declare the config schema.                  |
+
+### `configDir(appName, env?)`
+
+Resolves the platform-standard config directory for the given app name.
+
+```ts
+import { configDir } from "@crustjs/store";
+
+const dir = configDir("my-cli");
+// → "/home/user/.config/my-cli"       (Linux)
+// → "/Users/user/Library/Application Support/my-cli"  (macOS)
+// → "C:\\Users\\user\\AppData\\Roaming\\my-cli"       (Windows)
+```
+
+Use it with `dirPath`:
+
+```ts
+const store = createStore({
+  dirPath: configDir("my-cli"),
+  fields: { /* ... */ },
+});
+```
+
+### Field Definitions
+
+Each field in the `fields` record is a `FieldDef` with a `type` discriminant:
+
+| Property      | Type                                    | Required | Description                                         |
+| ------------- | --------------------------------------- | -------- | --------------------------------------------------- |
+| `type`        | `"string" \| "number" \| "boolean"`    | Yes      | The value type.                                     |
+| `default`     | Matches `type`                          | No       | Default value when the field is not persisted.       |
+| `array`       | `true`                                  | No       | Collect values into an array.                        |
+| `description` | `string`                                | No       | Human-readable description for tooling.              |
+
+Type inference rules:
+
+- **Has `default`** → field is guaranteed present (e.g., `string`)
+- **No `default`** → field is optional (e.g., `string | undefined`)
+- **`array: true`** → wraps the type in an array (e.g., `string[]`)
+
+```ts
+const store = createStore({
+  dirPath: configDir("my-cli"),
+  fields: {
+    theme:   { type: "string", default: "light" },       // → string
+    verbose: { type: "boolean", default: false },         // → boolean
+    retries: { type: "number", default: 3 },              // → number
+    token:   { type: "string" },                          // → string | undefined
+    tags:    { type: "string", array: true, default: [] },// → string[]
+    ids:     { type: "number", array: true },             // → number[] | undefined
+  },
+});
+```
+
+### `store.read()`
+
+Reads the persisted config file. Missing fields are filled from their `default` values. Fields without defaults are `undefined` when not persisted.
+
+```ts
+const config = await store.read();
+```
+
+Always returns a value — never `undefined`.
+
+### `store.write(config)`
+
+Atomically persists a full config object. The entire previous config is replaced.
+
+```ts
+await store.write({ theme: "dark", verbose: true, token: "abc123" });
+```
+
+### `store.update(updater)`
+
+Reads the current effective config, applies the updater function, and atomically persists the result.
+
+```ts
+await store.update((current) => ({
+  ...current,
+  theme: "dark",
+}));
+```
+
+When no persisted file exists, the updater receives field defaults as the current value.
+
+### `store.reset()`
+
+Removes the persisted config file. After reset, `read()` returns field defaults.
+
+```ts
+await store.reset();
+```
+
+Reset is idempotent — calling it when no file exists is a no-op.
+
+## Config File Path
+
+`configDir()` resolves the platform-standard config directory. The `name` option defaults to `"config"`, producing `config.json`:
+
+| Platform | Default Path                                            | Env Override       |
+| -------- | ------------------------------------------------------- | ------------------ |
+| Linux    | `~/.config/<appName>/<name>.json`                       | `$XDG_CONFIG_HOME` |
+| macOS    | `~/Library/Application Support/<appName>/<name>.json`   | —                  |
+| Windows  | `%APPDATA%\<appName>\<name>.json`                       | `%APPDATA%`        |
+
+### Multiple Stores
+
+Use the `name` option to create multiple stores under the same directory:
+
+```ts
+import { createStore, configDir } from "@crustjs/store";
+
+const dir = configDir("my-cli");
+
+// Default store → ~/.config/my-cli/config.json
+const configStore = createStore({
+  dirPath: dir,
+  fields: {
+    theme: { type: "string", default: "light" },
+    verbose: { type: "boolean", default: false },
+  },
+});
+
+// Auth store → ~/.config/my-cli/auth.json
+const authStore = createStore({
+  dirPath: dir,
+  name: "auth",
+  fields: {
+    token: { type: "string" },
+  },
+});
+```
+
+Each store is fully independent — reading, writing, updating, and resetting one store does not affect the others.
+
+The `name` must not contain path separators or the `.json` extension.
+
+## Defaults & Merge
+
+When a persisted file exists, `read()` applies field defaults for any missing keys:
+
+```ts
+const store = createStore({
+  dirPath: configDir("my-cli"),
+  fields: {
+    theme: { type: "string", default: "light" },
+    verbose: { type: "boolean", default: false },
+    retries: { type: "number", default: 3 },
+  },
+});
+
+// Persisted file contains: { "theme": "dark" }
+const config = await store.read();
+// → { theme: "dark", verbose: false, retries: 3 }
+```
+
+### Merge rules
+
+- Fields present in the persisted file use the persisted value.
+- Missing fields with a `default` use the default value.
+- Missing fields without a `default` are omitted (typed as `T | undefined`).
+- Extra keys in the persisted file that are not defined in `fields` are dropped.
+- Array defaults are shallow-copied to prevent shared mutation.
+- Falsy values (`null`, `0`, `""`, `false`) in the persisted file are preserved — only truly missing keys trigger defaults.
+
+### Important: defaults are not auto-persisted
+
+Merged defaults exist only in memory. The merged result is **not** written back to disk. The persisted file remains unchanged until you explicitly call `write()` or `update()`.
+
+## Error Handling
+
+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 }`      |
+
+### Catching errors by code
+
+```ts
+import { CrustStoreError } from "@crustjs/store";
+
+try {
+  const config = await store.read();
+} catch (err) {
+  if (err instanceof CrustStoreError) {
+    switch (err.code) {
+      case "PARSE":
+        console.error(`Corrupt config at ${err.details.path}`);
+        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;
+    }
+  }
+}
+```
+
+### Type narrowing with `.is()`
+
+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);
+}
+```
+
+### Cause chaining
+
+`CrustStoreError` preserves the original error as `cause` for debugging:
+
+```ts
+if (err instanceof CrustStoreError && err.is("PARSE")) {
+  console.error("Original parse error:", err.cause);
+}
+```
+
+### Malformed JSON
+
+`@crustjs/store` does **not** silently recover from malformed JSON. If the persisted config file contains invalid JSON, `read()` throws a `CrustStoreError` with `PARSE` code immediately — no fallback to defaults.
+
+## Types
+
+All types are exported for use in your application:
+
+```ts
+import type {
+  CreateStoreOptions,
+  FieldDef,
+  FieldsDef,
+  InferStoreConfig,
+  Store,
+  StoreUpdater,
+  ValueType,
+  StoreErrorCode,
+} from "@crustjs/store";
+```
+
+| Type                 | Description                                                             |
+| -------------------- | ----------------------------------------------------------------------- |
+| `CreateStoreOptions` | Options object for `createStore()`.                                     |
+| `FieldDef`           | Single field definition (discriminated by `type` and `array`).          |
+| `FieldsDef`          | Record mapping field names to `FieldDef`.                               |
+| `InferStoreConfig`   | Utility type: infers the config shape from a `FieldsDef`.               |
+| `Store`              | Store instance with `read`, `write`, `update`, `reset`.                 |
+| `StoreUpdater`       | Updater function type `(current: TConfig) => TConfig`.                  |
+| `ValueType`          | Supported type literals: `"string" \| "number" \| "boolean"`.          |
+| `StoreErrorCode`     | Union of error codes: `"PATH" \| "PARSE" \| "IO"`.                    |
+
+## v1 Scope & Non-Goals
+
+`@crustjs/store` v1 is intentionally minimal. The following are **not** included:
+
+- **Generic state/cache abstractions** — v1 is config-only (single typed object per store).
+- **Built-in encryption or keychain integration.**
+- **Cross-process locking** — v1 assumes single-process usage for write coordination.
+- **Sync API variants** (`readSync`, `writeSync`, etc.).
+- **Built-in validation** — will be added later via `@crustjs/validate` integration.
+- **Alternative formats** (YAML, TOML, JSON5) — JSON is the only on-disk format.
+- **Deep `@crustjs/core` integration** — the store is a standalone package.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,421 @@
+/**
+* Contextual details attached to a `PATH` error.
+*
+* Returned when the resolved or provided config file path is invalid.
+*/
+interface PathErrorDetails {
+	/** The path value that caused the error. */
+	path: string;
+}
+/**
+* Contextual details attached to a `PARSE` error.
+*
+* Returned when the persisted JSON file cannot be parsed.
+*/
+interface ParseErrorDetails {
+	/** Absolute path to the file that failed parsing. */
+	path: string;
+}
+/**
+* Contextual details attached to an `IO` error.
+*
+* Returned on filesystem read, write, or delete failures.
+*/
+interface IOErrorDetails {
+	/** Absolute path to the file involved in the failed operation. */
+	path: string;
+	/** The filesystem operation that failed (e.g. `"read"`, `"write"`, `"delete"`). */
+	operation: "read" | "write" | "delete";
+}
+/**
+* Maps each {@link StoreErrorCode} to its structured details type.
+*
+* Used internally for conditional constructor parameters and type narrowing.
+*/
+interface StoreErrorDetailsMap {
+	PATH: PathErrorDetails;
+	PARSE: ParseErrorDetails;
+	IO: IOErrorDetails;
+}
+/**
+* All possible error codes emitted by `@crustjs/store`.
+*
+* - `PATH` — Invalid or unsupported config file path
+* - `PARSE` — Malformed JSON in persisted config file
+* - `IO` — Filesystem read, write, or delete failure
+*
+* @example
+* ```ts
+* import { CrustStoreError } from "@crustjs/store";
+*
+* try {
+*   const config = await store.read();
+* } catch (err) {
+*   if (err instanceof CrustStoreError) {
+*     switch (err.code) {
+*       case "PARSE":
+*         console.error(`Corrupt config at ${err.details.path}`);
+*         break;
+*       case "IO":
+*         console.error(`File ${err.details.operation} failed: ${err.message}`);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+type StoreErrorCode = keyof StoreErrorDetailsMap;
+/** Resolves the details type for a given {@link StoreErrorCode}. */
+type StoreErrorDetails<C extends StoreErrorCode> = StoreErrorDetailsMap[C];
+/**
+* A typed error thrown by `@crustjs/store` for path, parse, and IO failures.
+*
+* Every `CrustStoreError` carries a {@link StoreErrorCode} that identifies the failure
+* category, along with structured {@link StoreErrorDetails} for programmatic handling
+* without fragile message parsing.
+*
+* @example
+* ```ts
+* import { CrustStoreError } from "@crustjs/store";
+*
+* try {
+*   const config = await store.read();
+* } catch (err) {
+*   if (err instanceof CrustStoreError && err.is("PARSE")) {
+*     console.error(`Corrupt config at ${err.details.path}`);
+*   }
+* }
+* ```
+*/
+declare class CrustStoreError<C extends StoreErrorCode = StoreErrorCode> extends Error {
+	/** Machine-readable error code for programmatic handling. */
+	readonly code: C;
+	/** Structured payload with context about the failure. */
+	readonly details: StoreErrorDetails<C>;
+	/** Optional wrapped original error or value. */
+	cause?: unknown;
+	constructor(code: C, message: string, details: StoreErrorDetails<C>);
+	/**
+	* Type-guard that narrows this error to a specific {@link StoreErrorCode}.
+	*
+	* When the guard returns `true`, TypeScript narrows the `details` property
+	* to the corresponding details type.
+	*
+	* @example
+	* ```ts
+	* if (err.is("IO")) {
+	*   // err.details is IOErrorDetails
+	*   console.error(err.details.operation, err.details.path);
+	* }
+	* ```
+	*/
+	is<T extends StoreErrorCode>(code: T): this is CrustStoreError<T>;
+	/**
+	* Attaches a cause to this error for stack-trace chaining.
+	*
+	* Returns `this` for fluent usage.
+	*
+	* @example
+	* ```ts
+	* throw new CrustStoreError("IO", "write failed", {
+	*   path: "/path/to/config.json",
+	*   operation: "write",
+	* }).withCause(originalError);
+	* ```
+	*/
+	withCause(cause: unknown): this;
+}
+/**
+* Encapsulates runtime environment values needed for path resolution.
+*
+* Exposed as a parameter to allow deterministic testing without mutating
+* `process.env` or `process.platform`.
+*/
+interface PlatformEnv {
+	/** Operating system platform identifier (e.g. `"linux"`, `"darwin"`, `"win32"`). */
+	platform: string;
+	/** Environment variables map. */
+	env: Record<string, string | undefined>;
+	/** User home directory path. */
+	homedir: string;
+}
+/**
+* Resolves the platform-standard config directory for the given app.
+*
+* Platform conventions:
+* - **Linux**: `$XDG_CONFIG_HOME/<appName>` or `~/.config/<appName>`
+* - **macOS**: `~/Library/Application Support/<appName>`
+* - **Windows**: `%APPDATA%/<appName>` or `~/AppData/Roaming/<appName>`
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   string without path separators.
+* @param env - Optional platform environment override for testing.
+* @returns Absolute path to the app's config directory.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+*
+* @example
+* ```ts
+* import { configDir } from "@crustjs/store";
+*
+* const dir = configDir("my-cli");
+* // → "/home/user/.config/my-cli" (Linux)
+* // → "/Users/user/Library/Application Support/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Roaming\\my-cli" (Windows)
+* ```
+*/
+declare function configDir(appName: string, env?: PlatformEnv): string;
+/** Supported type literals for store fields. */
+type ValueType = "string" | "number" | "boolean";
+/**
+* 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;
+/** Shared fields present on every store field definition. */
+interface FieldDefBase {
+	/** Human-readable description for documentation and tooling. */
+	description?: string;
+}
+/** Base for scalar (non-array) fields — `array` must be omitted. */
+interface ScalarFieldBase extends FieldDefBase {
+	/** Must be omitted for scalar fields — set to `true` for array fields. */
+	array?: never;
+}
+/** A scalar string field. */
+interface StringFieldDef extends ScalarFieldBase {
+	type: "string";
+	/** Default string value when the field is not persisted. */
+	default?: string;
+}
+/** A scalar number field. */
+interface NumberFieldDef extends ScalarFieldBase {
+	type: "number";
+	/** Default number value when the field is not persisted. */
+	default?: number;
+}
+/** A scalar boolean field. */
+interface BooleanFieldDef extends ScalarFieldBase {
+	type: "boolean";
+	/** Default boolean value when the field is not persisted. */
+	default?: boolean;
+}
+/** Base for array fields — `array` is required as `true`. */
+interface ArrayFieldBase extends FieldDefBase {
+	/** Collect values into an array. */
+	array: true;
+}
+/** An array of strings field. */
+interface StringArrayFieldDef extends ArrayFieldBase {
+	type: "string";
+	/** Default string array value when the field is not persisted. */
+	default?: readonly string[];
+}
+/** An array of numbers field. */
+interface NumberArrayFieldDef extends ArrayFieldBase {
+	type: "number";
+	/** Default number array value when the field is not persisted. */
+	default?: readonly number[];
+}
+/** An array of booleans field. */
+interface BooleanArrayFieldDef extends ArrayFieldBase {
+	type: "boolean";
+	/** Default boolean array value when the field is not persisted. */
+	default?: readonly boolean[];
+}
+/**
+* Defines a single field in a store's config schema.
+*
+* Discriminated by `type` and `array` for type-safe `default` values.
+*
+* @example
+* ```ts
+* const fields = {
+*   theme: { type: "string", default: "light" },
+*   verbose: { type: "boolean", default: false },
+*   tags: { type: "string", array: true, default: [] },
+*   token: { type: "string" },  // optional — no default
+* } satisfies FieldsDef;
+* ```
+*/
+type FieldDef = StringFieldDef | NumberFieldDef | BooleanFieldDef | StringArrayFieldDef | NumberArrayFieldDef | BooleanArrayFieldDef;
+/** Record mapping field names to their definitions. */
+type FieldsDef = Record<string, FieldDef>;
+/**
+* Infer the resolved type for a single field definition.
+*
+* - **array** → `primitive[]` (or `primitive[] | undefined` if no default)
+* - **has default** → `primitive` (guaranteed present)
+* - **no default** → `primitive | undefined` (optional)
+*/
+type InferFieldValue<F extends FieldDef> = 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;
+/**
+* Maps a full {@link FieldsDef} record to the inferred config object type.
+*
+* @example
+* ```ts
+* type Config = InferStoreConfig<{
+*   theme: { type: "string"; default: "light" };
+*   verbose: { type: "boolean" };
+* }>;
+* // → { theme: string; verbose: boolean | undefined }
+* ```
+*/
+type InferStoreConfig<F extends FieldsDef> = { [K in keyof F] : InferFieldValue<F[K]> };
+/**
+* Options for {@link createStore}.
+*
+* @typeParam F - The field definitions record (inferred via `const` generic).
+*
+* @example
+* ```ts
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
+*   },
+* });
+* ```
+*/
+interface CreateStoreOptions<F extends FieldsDef> {
+	/**
+	* Absolute directory path where the store JSON file is persisted.
+	*
+	* Use the {@link configDir} helper to resolve the platform-standard
+	* config directory from an app name.
+	*/
+	dirPath: string;
+	/**
+	* Store name used as the JSON filename in the directory.
+	*
+	* Defaults to `"config"`, producing `config.json`. Set to a different value
+	* to create multiple stores under the same directory
+	* (e.g. `name: "auth"` → `auth.json`).
+	*
+	* Must not contain path separators or the `.json` extension.
+	*/
+	name?: string;
+	/**
+	* Field definitions that declare the store's config schema.
+	*
+	* Each key maps to a {@link FieldDef} with a `type` discriminant and optional
+	* `default`. Fields without a `default` are optional (`T | undefined`).
+	*/
+	fields: F;
+}
+/**
+* Receives the current effective config and returns an updated config.
+*
+* Used by {@link Store.update} to apply partial mutations atomically.
+*
+* @example
+* ```ts
+* await store.update((current) => ({
+*   ...current,
+*   theme: "dark",
+* }));
+* ```
+*/
+type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
+/**
+* A typed async config store returned by {@link createStore}.
+*
+* Provides `read`, `write`, `update`, and `reset` operations for a single
+* typed config object persisted as JSON on the local filesystem.
+*
+* @typeParam TConfig - The inferred config shape from field definitions.
+*
+* @example
+* ```ts
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*   },
+* });
+*
+* const config = await store.read();
+* await store.write({ theme: "dark" });
+* await store.update((c) => ({ ...c, theme: "dark" }));
+* await store.reset();
+* ```
+*/
+interface Store<TConfig> {
+	/**
+	* Reads the persisted config, applying field defaults for missing keys.
+	*
+	* Always returns a value — fields with defaults are guaranteed present,
+	* fields without defaults may be `undefined`.
+	*
+	* @returns The effective config value.
+	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `IO` on filesystem read failures.
+	*/
+	read(): Promise<TConfig>;
+	/**
+	* Atomically persists the full config object.
+	*
+	* @param config - The complete config to persist.
+	* @throws {CrustStoreError} `IO` on filesystem write failures.
+	*/
+	write(config: NoInfer<TConfig>): Promise<void>;
+	/**
+	* Reads current effective config, applies the updater, and persists.
+	*
+	* @param updater - Function receiving current config and returning updated config.
+	* @throws {CrustStoreError} `PARSE` if persisted JSON is malformed.
+	* @throws {CrustStoreError} `IO` on filesystem failures.
+	*/
+	update(updater: StoreUpdater<TConfig>): Promise<void>;
+	/**
+	* Removes the persisted config file, returning the store to defaults-on-read behavior.
+	*
+	* @throws {CrustStoreError} `IO` on filesystem deletion failures.
+	*/
+	reset(): Promise<void>;
+}
+/**
+* Creates a typed async config store backed by a local JSON file.
+*
+* The store resolves its file path once at creation time from `dirPath` and
+* optional `name`. Field definitions declare the config schema — each field's
+* `type` determines its TypeScript type, and the presence of `default`
+* determines whether the field is guaranteed or optional (`T | undefined`).
+*
+* @typeParam F - Field definitions record (inferred via `const` generic).
+* @param options - Store configuration options.
+* @returns A {@link Store} instance with `read`, `write`, `update`, and `reset` methods.
+* @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
+*
+* @example
+* ```ts
+* import { createStore, configDir } from "@crustjs/store";
+*
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
+*     token: { type: "string" },
+*   },
+* });
+*
+* const config = await store.read();
+* // → { theme: "light", verbose: false } (defaults when no persisted file)
+*
+* await store.write({ theme: "dark", verbose: true, token: "abc" });
+* await store.update((c) => ({ ...c, theme: "light" }));
+* await store.reset();
+* ```
+*/
+declare function createStore<const F extends FieldsDef>(options: CreateStoreOptions<F>): Store<InferStoreConfig<F>>;
+export { createStore, configDir, ValueType, StoreUpdater, StoreErrorCode, Store, PlatformEnv, InferStoreConfig, FieldsDef, FieldDef, CrustStoreError, CreateStoreOptions };

package/dist/index.js

@@ -0,0 +1,231 @@
+// @bun
+// src/errors.ts
+class CrustStoreError extends Error {
+  code;
+  details;
+  cause;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "CrustStoreError";
+    this.code = code;
+    this.details = details;
+  }
+  is(code) {
+    return this.code === code;
+  }
+  withCause(cause) {
+    this.cause = cause;
+    return this;
+  }
+}
+// src/path.ts
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_STORE_NAME = "config";
+function getRuntimeEnv() {
+  return {
+    platform: process.platform,
+    env: process.env,
+    homedir: homedir()
+  };
+}
+function validateAppName(appName) {
+  if (!appName || appName.trim().length === 0) {
+    throw new CrustStoreError("PATH", "appName must be a non-empty string", {
+      path: appName ?? ""
+    });
+  }
+  if (appName.includes("/") || appName.includes("\\")) {
+    throw new CrustStoreError("PATH", "appName must not contain path separators", {
+      path: appName
+    });
+  }
+}
+function validateName(name) {
+  if (!name || name.trim().length === 0) {
+    throw new CrustStoreError("PATH", "name must be a non-empty string", {
+      path: name ?? ""
+    });
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    throw new CrustStoreError("PATH", "name must not contain path separators", {
+      path: name
+    });
+  }
+  if (name.endsWith(".json")) {
+    throw new CrustStoreError("PATH", "name must not include the .json extension", {
+      path: name
+    });
+  }
+}
+function validateDirPath(dirPath) {
+  if (!dirPath || dirPath.trim().length === 0) {
+    throw new CrustStoreError("PATH", "dirPath must be a non-empty string", {
+      path: dirPath ?? ""
+    });
+  }
+  const isAbsolute = dirPath.startsWith("/") || /^[A-Za-z]:[/\\]/.test(dirPath);
+  if (!isAbsolute) {
+    throw new CrustStoreError("PATH", "dirPath must be an absolute path", {
+      path: dirPath
+    });
+  }
+  if (dirPath.endsWith(".json")) {
+    throw new CrustStoreError("PATH", "dirPath must be a directory path, not a file path (should not end with .json)", {
+      path: dirPath
+    });
+  }
+}
+function configDir(appName, env) {
+  validateAppName(appName);
+  const resolvedEnv = env ?? getRuntimeEnv();
+  switch (resolvedEnv.platform) {
+    case "linux": {
+      const xdgConfig = resolvedEnv.env.XDG_CONFIG_HOME;
+      const base = xdgConfig && xdgConfig.trim().length > 0 ? xdgConfig : join(resolvedEnv.homedir, ".config");
+      return join(base, appName);
+    }
+    case "darwin": {
+      return join(resolvedEnv.homedir, "Library", "Application Support", appName);
+    }
+    case "win32": {
+      const appData = resolvedEnv.env.APPDATA;
+      const base = appData && appData.trim().length > 0 ? appData : join(resolvedEnv.homedir, "AppData", "Roaming");
+      return join(base, appName);
+    }
+    default:
+      throw new CrustStoreError("PATH", `Unsupported platform: ${resolvedEnv.platform}`, {
+        path: resolvedEnv.platform
+      });
+  }
+}
+function resolveStorePath(dirPath, name) {
+  validateDirPath(dirPath);
+  const storeName = name ?? DEFAULT_STORE_NAME;
+  if (name !== undefined) {
+    validateName(name);
+  }
+  return join(dirPath, `${storeName}.json`);
+}
+// src/merge.ts
+function applyFieldDefaults(persisted, fields) {
+  const result = {};
+  for (const [key, def] of Object.entries(fields)) {
+    if (persisted && key in persisted) {
+      result[key] = persisted[key];
+    } else if ("default" in def && def.default !== undefined) {
+      result[key] = Array.isArray(def.default) ? [...def.default] : def.default;
+    }
+  }
+  return result;
+}
+
+// src/persistence.ts
+import { randomUUID } from "crypto";
+import {
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  unlink,
+  writeFile
+} from "fs/promises";
+import { dirname, join as join2 } from "path";
+async function readJson(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (isEnoent(err)) {
+      return;
+    }
+    throw new CrustStoreError("IO", `Failed to read config file: ${filePath}`, {
+      path: filePath,
+      operation: "read"
+    }).withCause(err);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new CrustStoreError("PARSE", `Malformed JSON in config file: ${filePath}`, { path: filePath }).withCause(err);
+  }
+}
+async function writeJson(filePath, data) {
+  const dir = dirname(filePath);
+  const tempPath = join2(dir, `.config-${randomUUID()}.tmp`);
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch (err) {
+    throw new CrustStoreError("IO", `Failed to create config directory: ${dir}`, {
+      path: filePath,
+      operation: "write"
+    }).withCause(err);
+  }
+  try {
+    const json = JSON.stringify(data, null, "\t");
+    await writeFile(tempPath, json, "utf-8");
+  } catch (err) {
+    await cleanupTempFile(tempPath);
+    throw new CrustStoreError("IO", `Failed to write config file: ${filePath}`, {
+      path: filePath,
+      operation: "write"
+    }).withCause(err);
+  }
+  try {
+    await rename(tempPath, filePath);
+  } catch (err) {
+    await cleanupTempFile(tempPath);
+    throw new CrustStoreError("IO", `Failed to finalize config file: ${filePath}`, {
+      path: filePath,
+      operation: "write"
+    }).withCause(err);
+  }
+}
+async function deleteJson(filePath) {
+  try {
+    await unlink(filePath);
+  } catch (err) {
+    if (isEnoent(err)) {
+      return;
+    }
+    throw new CrustStoreError("IO", `Failed to delete config file: ${filePath}`, {
+      path: filePath,
+      operation: "delete"
+    }).withCause(err);
+  }
+}
+function isEnoent(err) {
+  return err !== null && typeof err === "object" && "code" in err && err.code === "ENOENT";
+}
+async function cleanupTempFile(tempPath) {
+  try {
+    await rm(tempPath, { force: true });
+  } catch {}
+}
+
+// src/store.ts
+function createStore(options) {
+  const { dirPath, name, fields } = options;
+  const filePath = resolveStorePath(dirPath, name);
+  async function read() {
+    const persisted = await readJson(filePath);
+    return applyFieldDefaults(persisted, fields);
+  }
+  async function write(config) {
+    await writeJson(filePath, config);
+  }
+  async function update(updater) {
+    const current = await read();
+    const updated = updater(current);
+    await writeJson(filePath, updated);
+  }
+  async function reset() {
+    await deleteJson(filePath);
+  }
+  return { read, write, update, reset };
+}
+export {
+  createStore,
+  configDir,
+  CrustStoreError
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@crustjs/store",
+	"version": "0.0.1",
+	"description": "Minimal, type-safe config persistence for CLI apps",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/store"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"config",
+		"store",
+		"persistence",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"bunup": "^0.16.29"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}