@hardlydifficult/state-tracker 2.0.13 → 2.0.14

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/state-tracker
 
-Atomic JSON state persistence with sync/async APIs, auto-save debouncing, typed migrations, key sanitization, and graceful fallback to in-memory mode.
+TypeScript state tracker with atomic JSON persistence, auto-save debouncing, typed migrations, and graceful fallback.
 
 ## Installation
 
@@ -13,358 +13,210 @@ npm install @hardlydifficult/state-tracker
 ```typescript
 import { StateTracker } from "@hardlydifficult/state-tracker";
 
-interface AppConfig {
-  version: string;
-  theme: "light" | "dark";
-}
-
-const tracker = new StateTracker<AppConfig>({
+const tracker = new StateTracker({
   key: "app-config",
-  default: { version: "1.0.0", theme: "light" },
-  autoSaveMs: 1000,
+  default: { theme: "light", notifications: true },
+  autoSaveMs: 500,
 });
 
-await tracker.loadAsync(); // Loads from disk, enables isPersistent tracking
-tracker.update({ theme: "dark" }); // Auto-saves after 1s of inactivity
-console.log(tracker.state); // { version: "1.0.0", theme: "dark" }
-```
-
-## Core Features
-
-### State Persistence
-
-The `StateTracker` class provides atomic JSON-based state persistence with auto-save support.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `key` | `string` | Unique identifier for the state file (alphanumeric, hyphens, underscores only) |
-| `default` | `T` | Default state if no persisted data exists |
-| `stateDirectory` | `string` (default: `~/.app-state` or `$STATE_TRACKER_DIR`) | Directory to store state files |
-| `autoSaveMs` | `number` (default: `0`) | Debounce delay in ms for auto-save |
-| `migration` | `Migration<T>` (deprecated) | Optional migration function (use `loadOrDefault()` with `defineStateMigration` instead) |
-| `onEvent` | `(event: StateTrackerEvent) => void` | Callback for internal events (debug/info/warn/error) |
-
-#### Async vs Sync Persistence
-
-```typescript
-// Async (recommended for production)
-await tracker.loadAsync();
-await tracker.saveAsync();
+tracker.set({ theme: "dark" }); // saves debounced
+console.log(tracker.state); // { theme: "dark", notifications: true }
 
-// Sync fallback (throws if file access fails)
-tracker.load();
-tracker.save({ theme: "dark" });
+tracker.reset(); // restores default
 ```
 
-### Key Sanitization
+## Core State Management
 
-Invalid keys (including `__proto__`, `constructor`, `prototype`) are sanitized automatically to prevent prototype pollution and path traversal.
+The `StateTracker` class provides type-safe state persistence with automatic atomic writes and in-memory caching.
 
-```typescript
-tracker.set("__proto__", { malicious: true }); // ignored
-tracker.set("normalKey", "value"); // works as expected
-```
+### Constructor Options
 
-### Typed Migrations
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `key` | `string` | — | Unique identifier; must contain only alphanumeric characters, hyphens, underscores |
+| `default` | `T` | — | Initial state used if no saved state is found |
+| `stateDirectory?` | `string` | `~/.app-state` | Override storage directory (or `STATE_TRACKER_DIR` env var) |
+| `autoSaveMs?` | `number` | `0` | Debounce delay (ms) after state changes |
+| `onEvent?` | `(event) => void` | — | Optional callback for debug/info/warn/error events |
 
-Support for typed migrations from older state formats using `loadOrDefault()` and `defineStateMigration()`.
+### Instance Properties
 
-```typescript
-import { defineStateMigration } from "@hardlydifficult/state-tracker";
+- `state: Readonly<T>` — Current in-memory state (read-only)
+- `isPersistent: boolean` — Whether disk storage is available
+- `getFilePath(): string` — Full path to the JSON file
 
-interface LegacyConfig {
-  theme: "light" | "dark";
-}
+### Instance Methods
 
-interface Config {
-  version: string;
-  theme: "light" | "dark";
-}
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `load()` / `loadSync()` | `(): T` | Sync load (uses defaults on error) |
+| `save(value)` | `(value: T): void` | Sync save to disk |
+| `set(newState)` | `(newState: T): void` | Replace state, triggers auto-save |
+| `update(changes)` | `(changes: Partial<T>): void` | Shallow merge (object state only) |
+| `reset()` | `(): void` | Restore to default value |
 
-const legacyMigration = defineStateMigration<Config, LegacyConfig>({
-  name: "legacy-config",
-  isLegacy(input): input is LegacyConfig {
-    return (
-      typeof input === "object" &&
-      input !== null &&
-      !Array.isArray(input) &&
-      "theme" in input &&
-      !("version" in input)
-    );
-  },
-  migrate(legacy) {
-    return { version: "1.0.0", ...legacy };
-  },
-});
+### Async Persistence API
 
-const tracker = new StateTracker<Config>({
-  key: "config",
-  default: { version: "1.1.0", theme: "dark" },
-});
+Async methods support graceful degradation when file system access fails.
 
-const state = tracker.loadOrDefault({ migrations: [legacyMigration] });
-```
+#### Methods
 
-### Graceful Degradation
+- `loadAsync(): Promise<void>` — Loads state from disk; sets `isPersistent` to `false` on failure
+- `saveAsync(): Promise<void>` — Atomic async save using temp file + rename
+- Both are idempotent: subsequent calls after first `loadAsync` are no-ops
 
-If persistent storage fails (e.g., due to permissions or path issues), the tracker falls back to in-memory mode without throwing errors.
+#### Example
 
 ```typescript
-const tracker = new StateTracker<AppConfig>({
-  key: "config",
-  default: { version: "1.0.0", theme: "light" },
+const tracker = new StateTracker({
+  key: "settings",
+  default: { fontSize: 14 },
+  stateDirectory: "/app/state",
 });
 
 await tracker.loadAsync();
-if (!tracker.isPersistent) {
-  console.warn("Running in-memory mode");
-}
-```
+console.log(tracker.isPersistent); // true (or false if directory not writable)
 
-## State Management
-
-The `StateTracker` class provides a robust interface for managing persistent application state.
-
-### Constructor Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `key` | `string` | — | Unique identifier for the state file (alphanumeric, hyphens, underscores only) |
-| `default` | `T` | — | Default state value used if no persisted state exists |
-| `stateDirectory` | `string` | `~/.app-state` or `$STATE_TRACKER_DIR` | Directory to store state files |
-| `autoSaveMs` | `number` | `0` | Debounce delay (ms) for auto-save after state changes |
-| `migration` | `Migration<T>` | — | **Deprecated:** Use `defineStateMigration` with `loadOrDefault` instead |
-| `onEvent` | `(event: StateTrackerEvent) => void` | `undefined` | Callback for internal events (debug/info/warn/error) |
+tracker.set({ fontSize: 16 });
+await tracker.saveAsync();
+```
 
-### State Accessors
+## Auto-Save with Debouncing
 
-- **`state: Readonly<T>`** — Read-only getter for the current in-memory state.
-- **`isPersistent: boolean`** — Indicates whether disk persistence is available (set after `loadAsync()`).
+Set `autoSaveMs` in the constructor to debounce writes after state changes via `set()` or `update()`.
 
 ```typescript
 const tracker = new StateTracker({
-  key: "counter",
-  default: 0,
-  stateDirectory: "./data",
+  key: "editor",
+  default: { text: "", cursor: 0 },
+  autoSaveMs: 300,
 });
 
-console.log(tracker.state); // 0
-await tracker.loadAsync();
-console.log(tracker.isPersistent); // true if disk write succeeded
+tracker.set({ text: "Hello" }); // will auto-save after 300ms
+tracker.update({ cursor: 5 }); // cancels pending auto-save, re-schedules
 ```
 
-### Persistence Operations
+- `save()` and `saveAsync()` cancel pending auto-saves and write immediately
+- If `autoSaveMs <= 0`, no debounced saves are scheduled
+- On persistent storage failure, auto-save is disabled until `loadAsync` succeeds
+
+## Typed Migrations
+
+Support legacy state formats with typed migrations.
 
-#### `load(): T`
-Synchronous state load from disk. Returns the current state (default if missing or corrupted).
+### Migration Interface
 
 ```typescript
-const tracker = new StateTracker({
-  key: "config",
-  default: { version: 1 },
-});
-const config = tracker.load(); // Loads from disk or uses default
+interface StateTrackerMigration<TCurrent, TLegacy = unknown> {
+  name?: string;
+  isLegacy(input: unknown): input is TLegacy;
+  migrate(legacy: TLegacy): TCurrent;
+}
 ```
 
-#### `loadOrDefault(options?): T`
-Explicit "safe load" convenience. Behaves like `load()` and supports typed legacy migrations.
+### Helper
 
-```typescript
-import { defineStateMigration, StateTracker } from "@hardlydifficult/state-tracker";
+- `defineStateMigration<TCurrent, TLegacy>(migration)` — Type-safe migration builder
 
-interface LegacySyncState {
-  offset: number;
-  completedIds: string[];
-}
+### Usage
 
-const tracker = new StateTracker({
-  key: "sync-state",
-  default: { cursor: 0, done: [] as string[] },
-});
+```typescript
+interface LegacyState { offset: number; completedIds: string[] }
+interface CurrentState { cursor: number; done: string[] }
 
-const legacyMigration = defineStateMigration<
-  { cursor: number; done: string[] },
-  LegacySyncState
->({
-  name: "sync-state-v0",
-  isLegacy(input): input is LegacySyncState {
+const migration = defineStateMigration<CurrentState, LegacyState>({
+  name: "cursor-migration",
+  isLegacy(input): input is LegacyState {
     return (
-      input !== null &&
+      input &&
       typeof input === "object" &&
-      !Array.isArray(input) &&
-      typeof (input as Record<string, unknown>).offset === "number" &&
-      Array.isArray((input as Record<string, unknown>).completedIds)
+      "offset" in input &&
+      "completedIds" in input
     );
   },
   migrate(legacy) {
-    return { cursor: legacy.offset, done: legacy.completedIds };
+    return {
+      cursor: legacy.offset,
+      done: legacy.completedIds,
+    };
   },
 });
 
-const state = tracker.loadOrDefault({ migrations: [legacyMigration] });
-```
-
-#### `save(value: T): void`
-Synchronous atomic save using temp file + rename.
-
-```typescript
-tracker.save({ version: 2 });
-// File is updated atomically; previous state preserved if crash occurs mid-write
-```
-
-#### `saveWithMeta(value: T, meta?: Record<string, unknown>): void`
-Synchronous atomic save with optional metadata in the envelope.
-
-```typescript
-tracker.saveWithMeta(
-  { version: 3 },
-  { source: "sync-script", reason: "manual-run" }
-);
-```
-
-#### `loadAsync(): Promise<void>`
-Async state load with graceful degradation. Sets `isPersistent = false` on failure instead of throwing.
-
-```typescript
 const tracker = new StateTracker({
-  key: "preferences",
-  default: { darkMode: false },
+  key: "tasks",
+  default: { cursor: 0, done: [] } as CurrentState,
 });
 
-await tracker.loadAsync();
-if (!tracker.isPersistent) {
-  console.warn("Running in-memory mode (disk unavailable)");
-}
+// Load with migration
+const value = tracker.loadOrDefault({ migrations: [migration] });
+// Legacy { offset: 3, completedIds: ["a", "b"] } → { cursor: 3, done: ["a", "b"] }
 ```
 
-#### `saveAsync(): Promise<void>`
-Async atomic save (temp file + rename). Cancels any pending auto-save before writing.
+### Envelope Format
 
-```typescript
-tracker.set({ darkMode: true });
-await tracker.saveAsync(); // Immediate save, bypassing debounce
-```
-
-### State Mutations
-
-#### `set(newState: T): void`
-Replace entire state and schedule auto-save.
-
-```typescript
-tracker.set({ darkMode: true, theme: "midnight" });
-// Auto-saves after configured delay (if autoSaveMs > 0)
-```
-
-#### `update(changes: Partial<T>): void`
-Shallow merge for object types and schedule auto-save.
+Saved state uses a JSON envelope:
 
-```typescript
-tracker.update({ theme: "dark" }); // Preserves darkMode: true
-```
-
-> **Note:** Throws at runtime if state is not an object (array/primitive).
-
-#### `reset(): void`
-Restore state to the default value and schedule auto-save.
-
-```typescript
-tracker.reset(); // Reverts to default state
+```json
+{
+  "value": { /* your state */ },
+  "lastUpdated": "2025-04-05T12:34:56.789Z",
+  "meta": { /* optional metadata */ }
+}
 ```
 
-### File Management
+- `load()` and `loadAsync()` extract `value` and merge missing keys from `default`
+- Supports raw legacy objects (without envelope) with default-merge
 
-#### `getFilePath(): string`
-Returns the full path to the state file.
+## Event Logging
 
-```typescript
-console.log(tracker.getFilePath()); // "/home/user/.app-state/counter.json"
-```
+Optionally track runtime events via the `onEvent` callback.
 
-## Event System
+### Event Types
 
-Events are emitted for internal operations via the optional `onEvent` callback.
+- `debug`: Internal behavior (e.g., auto-save completion)
+- `info`: Startup/loading (e.g., no existing state, directory creation)
+- `warn`: recoverable issues (e.g., storage unavailable, migration failure)
+- `error`: unrecoverable errors (e.g., disk write failure)
 
-| Level | Description |
-|-------|-------------|
-| `debug` | Low-level operations (e.g., save completion) |
-| `info` | Normal operations (e.g., file read/write) |
-| `warn` | Recoverable failures (e.g., disk I/O errors) |
-| `error` | Non-recoverable failures (e.g., permission issues) |
+### Example
 
 ```typescript
 const tracker = new StateTracker({
-  key: "app",
+  key: "my-state",
   default: {},
   onEvent: (event) => {
-    console[event.level](`[${event.level}] ${event.message}`, event.context);
+    if (event.level === "error") console.error(event.message, event.context);
   },
 });
 
 await tracker.loadAsync();
-// Outputs: [info] Loaded state from disk { path: ".../app.json" }
-```
-
-## Persistence Format
-
-### v2 (Envelope) Format
-```json
-{
-  "value": { "theme": "dark", "notifications": true },
-  "lastUpdated": "2024-05-01T12:00:00.000Z",
-  "meta": { "source": "sync-script" }
-}
-```
-
-### Legacy (PersistentStore) Migration
-The tracker automatically detects and merges legacy raw JSON objects with defaults on load.
-
-```typescript
-// If disk contains: { "count": 42 }
-// And default is: { "count": 0, "name": "default" }
-// Loaded state becomes: { "count": 42, "name": "default" }
+// emits info: "No existing state file" or "Loaded state from disk"
 ```
 
-After the first `saveAsync()`, files are rewritten in the v2 envelope format.
-
-For custom legacy formats, use typed migrations with `defineStateMigration(...)`
-and pass them to `loadOrDefault({ migrations })`.
-
-## Auto-Save Behavior
+## Appendix: Key Sanitization
 
-When `autoSaveMs > 0`, state changes are debounced:
-
-1. `set()` or `update()` triggers a timer.
-2. Subsequent changes within the window reset the timer.
-3. After `autoSaveMs` ms of inactivity, the state is saved.
+Keys must match `^[A-Za-z0-9_-]+$`. Invalid keys throw at construction:
 
 ```typescript
-const tracker = new StateTracker({
-  key: "debounced",
-  default: { x: 0 },
-  autoSaveMs: 500,
-});
-
-tracker.set({ x: 1 });
-tracker.set({ x: 2 }); // Timer resets
-await new Promise(r => setTimeout(r, 100));
-tracker.set({ x: 3 }); // Timer resets again
+new StateTracker({ key: "../evil", default: 0 });
+// Error: StateTracker key contains invalid characters
 
-// Only saved once after 500ms of inactivity with final value { x: 3 }
+new StateTracker({ key: "", default: 0 });
+// Error: StateTracker key must be a non-empty string
 ```
 
-Calling `save()` or `saveAsync()` cancels pending auto-saves and writes immediately.
-
-## Types
+State files are written as `<key>.json` inside the state directory.
 
-```typescript
-export type StateTrackerEventLevel = "debug" | "info" | "warn" | "error";
+## Exported API
 
-export interface StateTrackerEvent {
-  level: StateTrackerEventLevel;
-  message: string;
-  context?: Record<string, unknown>;
-}
-```
+- `StateTracker<T>` — Main persistence class
+- `defineStateMigration<TCurrent, TLegacy>` — Migration builder
+- `StateTrackerOptions<T>` — Constructor options
+- `StateTrackerEvent` — Event payload
+- `StateTrackerEventLevel` — `"debug" \| "info" \| "warn" \| "error"`
+- `StateTrackerLoadOrDefaultOptions<T>` — Options for `loadOrDefault`
+- `StateTrackerMigration<TCurrent, TLegacy>` — Migration definition
+- `StateTrackerSaveMeta` — Optional metadata in save envelope
 
 ## Environment Variable
 
@@ -383,13 +235,12 @@ STATE_TRACKER_DIR=/custom/path npm start
 - **Auto-save** — debounced saves after state mutations
 - **Legacy format support** — reads both v1 envelope format and legacy PersistentStore formats
 - **Typed migration helper** — declarative migration rules for old JSON shapes
-- **Optional save metadata** — annotate saved state with `saveWithMeta(...)`
 - **API consistency** — all operations work seamlessly across sync/async modes
 
-## Appendix: Platform Behavior
+## Platform Behavior
 
 | Environment | Persistence | Fallback Behavior |
 |-------------|-------------|-------------------|
-| Node.js | ✅ File system access | Falls back to memory on errors |
-| Browser | ❌ No file system access | Always in-memory only |
-| Bun/Deno | ⚠️ Experimental support | Depends on environment capabilities |
+| Node.js     | ✅ File system access | Falls back to memory on errors |
+| Browser     | ❌ No file system access | Always in-memory only |
+| Bun/Deno    | ⚠️ Experimental support | Depends on environment capabilities |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/state-tracker",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [