@hardlydifficult/state-tracker 2.0.8 → 2.0.9

package/README.md

@@ -34,13 +34,33 @@ store.set({ requestCount: 0, lastActiveAt: new Date().toISOString() }); // full
 await store.saveAsync(); // force immediate save
 ```
 
-## State Persistence
+## Key Sanitization
 
-The `StateTracker` class provides atomic JSON state persistence using file-based storage with graceful fallback to in-memory mode when disk access fails.
+StateTracker enforces strict key sanitization to prevent path traversal and invalid characters. Keys must match `/^[A-Za-z0-9_-]+$/`.
 
-### Sync API
+```typescript
+new StateTracker({ key: "../evil", default: 0 }); // throws: "invalid characters"
+new StateTracker({ key: "foo/bar", default: 0 }); // throws: "invalid characters"
+```
+
+## Persistence & Graceful Degradation
 
-For tools and scripts, use the synchronous API:
+If storage is unavailable (e.g., due to permissions or read-only filesystem), StateTracker automatically falls back to in-memory mode without throwing errors.
+
+```typescript
+const tracker = new StateTracker({
+  key: "failing",
+  default: { x: 1 },
+});
+
+await tracker.loadAsync(); // fails silently on unreadable dir
+console.log(tracker.isPersistent); // false
+console.log(tracker.state); // uses in-memory default
+```
+
+## Sync API: `load()` and `save()`
+
+V1-compatible synchronous operations for environments where async is not preferred or available.
 
 ```typescript
 import { StateTracker } from "@hardlydifficult/state-tracker";
@@ -54,9 +74,9 @@ const count = store.load(); // returns current state
 store.save(count + 1); // writes entire state atomically
 ```
 
-### Async API
+## Async API: `loadAsync()` and `saveAsync()`
 
-For long-running servers, use the async API with auto-save:
+Async operations that gracefully degrade to in-memory mode on errors.
 
 ```typescript
 const store = new StateTracker<AppState>({
@@ -71,15 +91,107 @@ store.set({ version: 2 });
 await store.saveAsync(); // Force immediate save
 ```
 
+## State Manipulation
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `set(newState)` | Replace entire state, triggers auto-save | `tracker.set({ count: 5 })` |
+| `update(changes)` | Shallow merge (object state only), triggers auto-save | `tracker.update({ count: 5 })` |
+| `reset()` | Restore to default, triggers auto-save | `tracker.reset()` |
+| `state` (getter) | Read-only current state | `tracker.state` |
+| `isPersistent` (getter) | Whether storage is available | `tracker.isPersistent` |
+
+```typescript
+const tracker = new StateTracker({
+  key: "manip",
+  default: { a: 1, b: 2 },
+});
+
+tracker.set({ a: 10, b: 20 }); // replaces all
+tracker.update({ b: 200 }); // merges: { a: 10, b: 200 }
+tracker.reset(); // back to { a: 1, b: 2 }
+```
+
+### `update()` on Primitive Types
+
+Calling `update()` on a primitive or array state throws:
+
+```typescript
+const primitive = new StateTracker<number>({ key: "num", default: 0 });
+primitive.update(100 as never); // throws: "update() can only be used when state is a non-array object"
+```
+
+## Auto-Save with Debouncing
+
+Configure automatic debounced saving via `autoSaveMs`. Any state change (`set`, `update`, `reset`) will schedule a save after the delay; rapid changes only trigger one save.
+
+```typescript
+const tracker = new StateTracker({
+  key: "auto",
+  default: { count: 0 },
+  autoSaveMs: 500,
+});
+
+tracker.set({ count: 1 }); // schedules save in 500ms
+tracker.set({ count: 2 }); // cancels previous, schedules new save
+tracker.set({ count: 3 }); // cancels again, only this save triggers after 500ms
+```
+
+## Event Logging
+
+Optionally receive events for debugging, monitoring, or diagnostics.
+
+```typescript
+const tracker = new StateTracker({
+  key: "events",
+  default: { x: 1 },
+  onEvent: (event) => {
+    console.log(`[${event.level}] ${event.message}`, event.context);
+  },
+});
+
+await tracker.loadAsync();
+// Outputs: [info] No existing state file, using defaults { path: ".../x.json" }
+```
+
+### Event Type Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `level` | `"debug" \| "info" \| "warn" \| "error"` | Severity level |
+| `message` | `string` | Human-readable message |
+| `context`? | `Record<string, unknown>` | Additional metadata (e.g., `path`, `error`) |
+
+## File Format
+
+StateTracker uses an envelope format for storage:
+
+```json
+{
+  "value": <your-state>,
+  "lastUpdated": "2025-04-05T12:34:56.789Z"
+}
+```
+
+### Migration
+
+Legacy raw JSON objects (without envelope) are automatically loaded and merged with defaults, then rewritten in envelope format on next `saveAsync()`.
+
+```typescript
+// Old format: { "count": 10 }
+await tracker.loadAsync(); // merges with defaults
+await tracker.saveAsync(); // writes: { "value": { "count": 10 }, "lastUpdated": "..." }
+```
+
 ## Options
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `key` | `string` | Unique identifier for the state file (required) |
-| `default` | `T` | Default value when no state file exists (required) |
-| `stateDirectory` | `string` | Directory for state files (default: `$STATE_TRACKER_DIR` or `~/.app-state`) |
-| `autoSaveMs` | `number` | Auto-save interval after `update()`/`set()`/`reset()` (default: 0 = disabled) |
-| `onEvent` | `(event: StateTrackerEvent) => void` | Event callback for logging (`{ level, message, context }`) |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `key` | `string` | — | Unique identifier (alphanumeric, hyphens, underscores only) |
+| `default` | `T` | — | Default value used on missing/corrupt storage |
+| `stateDirectory`? | `string` | `~/.app-state` | Custom directory for state files |
+| `autoSaveMs`? | `number` | `0` | Debounce delay for auto-save (ms); `0` disables |
+| `onEvent`? | `(e: StateTrackerEvent) => void` | — | Event callback for logging |
 
 ## Properties
 
@@ -101,50 +213,14 @@ await store.saveAsync(); // Force immediate save
 | `reset()` | Restore to defaults, triggers auto-save |
 | `getFilePath()` | Returns the full path to the state file |
 
-### `update()`
-
-For object state types, `update()` merges partial changes:
-
-```typescript
-const store = new StateTracker<{ count: number; name: string }>({
-  key: "demo",
-  default: { count: 0, name: "initial" },
-});
-
-store.update({ count: 42 });
-console.log(store.state); // { count: 42, name: "initial" }
-```
-
-Calling `update()` on a primitive state throws:
-
-```typescript
-const primitive = new StateTracker<number>({ key: "num", default: 0 });
-primitive.update(100 as never); // throws: "update() can only be used when state is a non-array object"
-```
+## Environment Variable
 
-## Event Handling
+- `STATE_TRACKER_DIR`: Overrides default state directory (`~/.app-state`)
 
-Events are emitted for key lifecycle operations with configurable logging:
-
-```typescript
-const store = new StateTracker<AppState>({
-  key: "app",
-  default: { version: 1 },
-  onEvent: ({ level, message, context }) => {
-    console.log(`[${level}] ${message}`, context);
-  },
-});
-
-await store.loadAsync();
-// Example output: [info] No existing state file, using defaults { path: ".../app.json" }
-
-store.set({ version: 2 });
-await store.saveAsync();
-// Example output: [debug] Saved state to disk { path: ".../app.json" }
+```bash
+STATE_TRACKER_DIR=/custom/path npm start
 ```
 
-Event levels: `"debug"`, `"info"`, `"warn"`, `"error"`
-
 ## Features
 
 - **Type inference** from the default value
@@ -154,20 +230,6 @@ Event levels: `"debug"`, `"info"`, `"warn"`, `"error"`
 - **Auto-save** — debounced saves after state mutations
 - **Legacy format support** — reads both v1 envelope format and legacy PersistentStore formats
 
-## Legacy Format Migration
-
-The library transparently handles migration from legacy formats:
-
-```typescript
-// If disk contains legacy format: { count: 42 }
-// Load merges with defaults: { count: 42, extra: true }
-await store.loadAsync();
-
-// Subsequent save writes new envelope format:
-// { value: { count: 42, extra: true }, lastUpdated: "2025-01-01T..." }
-await store.saveAsync();
-```
-
 ## Exported Types
 
 The package also exports the following types for advanced usage:

package/package.json

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