@hardlydifficult/state-tracker 2.0.12 → 2.0.14

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/state-tracker
 
-Atomic JSON state persistence with sync/async APIs, auto-save debouncing, and graceful degradation to in-memory mode for TypeScript.
+TypeScript state tracker with atomic JSON persistence, auto-save debouncing, typed migrations, and graceful fallback.
 
 ## Installation
 
@@ -14,266 +14,210 @@ npm install @hardlydifficult/state-tracker
 import { StateTracker } from "@hardlydifficult/state-tracker";
 
 const tracker = new StateTracker({
-  key: "user-settings",
+  key: "app-config",
   default: { theme: "light", notifications: true },
-  autoSaveMs: 1000,
+  autoSaveMs: 500,
 });
 
-// Load persisted state (sync or async)
-tracker.load(); // or await tracker.loadAsync();
-
-// Update state and auto-save
-tracker.update({ theme: "dark" });
-// State is saved automatically after 1 second of inactivity
-
-// Read current state
+tracker.set({ theme: "dark" }); // saves debounced
 console.log(tracker.state); // { theme: "dark", notifications: true }
+
+tracker.reset(); // restores default
 ```
 
-## State Management
+## Core State Management
 
-The `StateTracker` class provides a robust interface for managing persistent application state.
+The `StateTracker` class provides type-safe state persistence with automatic atomic writes and in-memory caching.
 
-### Constructor
+### 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 |
-| `onEvent` | `(event: StateTrackerEvent) => void` | `undefined` | Callback for internal events (debug/info/warn/error) |
+| `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 |
 
-### State Accessors
+### Instance Properties
 
-- **`state: Readonly<T>`** — Read-only getter for the current in-memory state.
-- **`isPersistent: boolean`** — Indicates whether disk persistence is available (set after `loadAsync()`).
+- `state: Readonly<T>` — Current in-memory state (read-only)
+- `isPersistent: boolean` — Whether disk storage is available
+- `getFilePath(): string` — Full path to the JSON file
 
-```typescript
-const tracker = new StateTracker({
-  key: "counter",
-  default: 0,
-  stateDirectory: "./data",
-});
+### Instance Methods
 
-console.log(tracker.state); // 0
-await tracker.loadAsync();
-console.log(tracker.isPersistent); // true if disk write succeeded
-```
+| 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 |
 
-### Persistence Operations
+### Async Persistence API
 
-#### `load(): T`
-Synchronous state load from disk. Returns the current state (default if missing or corrupted).
+Async methods support graceful degradation when file system access fails.
 
-```typescript
-const tracker = new StateTracker({
-  key: "config",
-  default: { version: 1 },
-});
-const config = tracker.load(); // Loads from disk or uses default
-```
+#### Methods
 
-#### `loadOrDefault(options?): T`
-Explicit "safe load" convenience. Behaves like `load()` and supports typed legacy migrations.
+- `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
 
-```typescript
-import { defineStateMigration, StateTracker } from "@hardlydifficult/state-tracker";
-
-interface LegacySyncState {
-  offset: number;
-  completedIds: string[];
-}
+#### Example
 
+```typescript
 const tracker = new StateTracker({
-  key: "sync-state",
-  default: { cursor: 0, done: [] as string[] },
-});
-
-const legacyMigration = defineStateMigration<
-  { cursor: number; done: string[] },
-  LegacySyncState
->({
-  name: "sync-state-v0",
-  isLegacy(input): input is LegacySyncState {
-    return (
-      input !== null &&
-      typeof input === "object" &&
-      !Array.isArray(input) &&
-      typeof (input as Record<string, unknown>).offset === "number" &&
-      Array.isArray((input as Record<string, unknown>).completedIds)
-    );
-  },
-  migrate(legacy) {
-    return { cursor: legacy.offset, done: legacy.completedIds };
-  },
+  key: "settings",
+  default: { fontSize: 14 },
+  stateDirectory: "/app/state",
 });
 
-const state = tracker.loadOrDefault({ migrations: [legacyMigration] });
-```
-
-#### `save(value: T): void`
-Synchronous atomic save using temp file + rename.
+await tracker.loadAsync();
+console.log(tracker.isPersistent); // true (or false if directory not writable)
 
-```typescript
-tracker.save({ version: 2 });
-// File is updated atomically; previous state preserved if crash occurs mid-write
+tracker.set({ fontSize: 16 });
+await tracker.saveAsync();
 ```
 
-#### `saveWithMeta(value: T, meta?: Record<string, unknown>): void`
-Synchronous atomic save with optional metadata in the envelope.
+## Auto-Save with Debouncing
 
-```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.
+Set `autoSaveMs` in the constructor to debounce writes after state changes via `set()` or `update()`.
 
 ```typescript
 const tracker = new StateTracker({
-  key: "preferences",
-  default: { darkMode: false },
+  key: "editor",
+  default: { text: "", cursor: 0 },
+  autoSaveMs: 300,
 });
 
-await tracker.loadAsync();
-if (!tracker.isPersistent) {
-  console.warn("Running in-memory mode (disk unavailable)");
-}
-```
-
-#### `saveAsync(): Promise<void>`
-Async atomic save (temp file + rename). Cancels any pending auto-save before writing.
-
-```typescript
-tracker.set({ darkMode: true });
-await tracker.saveAsync(); // Immediate save, bypassing debounce
+tracker.set({ text: "Hello" }); // will auto-save after 300ms
+tracker.update({ cursor: 5 }); // cancels pending auto-save, re-schedules
 ```
 
-### State Mutations
+- `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
 
-#### `set(newState: T): void`
-Replace entire state and schedule auto-save.
+## Typed Migrations
 
-```typescript
-tracker.set({ darkMode: true, theme: "midnight" });
-// Auto-saves after configured delay (if autoSaveMs > 0)
-```
+Support legacy state formats with typed migrations.
 
-#### `update(changes: Partial<T>): void`
-Shallow merge for object types and schedule auto-save.
+### Migration Interface
 
 ```typescript
-tracker.update({ theme: "dark" }); // Preserves darkMode: true
+interface StateTrackerMigration<TCurrent, TLegacy = unknown> {
+  name?: string;
+  isLegacy(input: unknown): input is TLegacy;
+  migrate(legacy: TLegacy): TCurrent;
+}
 ```
 
-> **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
-```
+### Helper
 
-### File Management
+- `defineStateMigration<TCurrent, TLegacy>(migration)` — Type-safe migration builder
 
-#### `getFilePath(): string`
-Returns the full path to the state file.
+### Usage
 
 ```typescript
-console.log(tracker.getFilePath()); // "/home/user/.app-state/counter.json"
-```
-
-## Event System
-
-Events are emitted for internal operations via the optional `onEvent` callback.
+interface LegacyState { offset: number; completedIds: string[] }
+interface CurrentState { cursor: number; done: string[] }
 
-| 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) |
+const migration = defineStateMigration<CurrentState, LegacyState>({
+  name: "cursor-migration",
+  isLegacy(input): input is LegacyState {
+    return (
+      input &&
+      typeof input === "object" &&
+      "offset" in input &&
+      "completedIds" in input
+    );
+  },
+  migrate(legacy) {
+    return {
+      cursor: legacy.offset,
+      done: legacy.completedIds,
+    };
+  },
+});
 
-```typescript
 const tracker = new StateTracker({
-  key: "app",
-  default: {},
-  onEvent: (event) => {
-    console[event.level](`[${event.level}] ${event.message}`, event.context);
-  },
+  key: "tasks",
+  default: { cursor: 0, done: [] } as CurrentState,
 });
 
-await tracker.loadAsync();
-// Outputs: [info] Loaded state from disk { path: ".../app.json" }
+// Load with migration
+const value = tracker.loadOrDefault({ migrations: [migration] });
+// Legacy { offset: 3, completedIds: ["a", "b"] } → { cursor: 3, done: ["a", "b"] }
 ```
 
-## Persistence Format
+### Envelope Format
+
+Saved state uses a JSON envelope:
 
-### v2 (Envelope) Format
 ```json
 {
-  "value": { "theme": "dark", "notifications": true },
-  "lastUpdated": "2024-05-01T12:00:00.000Z",
-  "meta": { "source": "sync-script" }
+  "value": { /* your state */ },
+  "lastUpdated": "2025-04-05T12:34:56.789Z",
+  "meta": { /* optional metadata */ }
 }
 ```
 
-### 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" }
-```
+- `load()` and `loadAsync()` extract `value` and merge missing keys from `default`
+- Supports raw legacy objects (without envelope) with default-merge
 
-After the first `saveAsync()`, files are rewritten in the v2 envelope format.
+## Event Logging
 
-For custom legacy formats, use typed migrations with `defineStateMigration(...)`
-and pass them to `loadOrDefault({ migrations })`.
+Optionally track runtime events via the `onEvent` callback.
 
-## Auto-Save Behavior
+### Event Types
 
-When `autoSaveMs > 0`, state changes are debounced:
+- `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)
 
-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.
+### Example
 
 ```typescript
 const tracker = new StateTracker({
-  key: "debounced",
-  default: { x: 0 },
-  autoSaveMs: 500,
+  key: "my-state",
+  default: {},
+  onEvent: (event) => {
+    if (event.level === "error") console.error(event.message, event.context);
+  },
 });
 
-tracker.set({ x: 1 });
-tracker.set({ x: 2 }); // Timer resets
-await new Promise(r => setTimeout(r, 100));
-tracker.set({ x: 3 }); // Timer resets again
-
-// Only saved once after 500ms of inactivity with final value { x: 3 }
+await tracker.loadAsync();
+// emits info: "No existing state file" or "Loaded state from disk"
 ```
 
-Calling `save()` or `saveAsync()` cancels pending auto-saves and writes immediately.
+## Appendix: Key Sanitization
 
-## Types
+Keys must match `^[A-Za-z0-9_-]+$`. Invalid keys throw at construction:
 
 ```typescript
-export type StateTrackerEventLevel = "debug" | "info" | "warn" | "error";
+new StateTracker({ key: "../evil", default: 0 });
+// Error: StateTracker key contains invalid characters
 
-export interface StateTrackerEvent {
-  level: StateTrackerEventLevel;
-  message: string;
-  context?: Record<string, unknown>;
-}
+new StateTracker({ key: "", default: 0 });
+// Error: StateTracker key must be a non-empty string
 ```
 
+State files are written as `<key>.json` inside the state directory.
+
+## Exported API
+
+- `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
 
 - `STATE_TRACKER_DIR`: Overrides default state directory (`~/.app-state`)
@@ -291,4 +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
+
+## 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 |

package/package.json

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