@hardlydifficult/state-tracker 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# @hardlydifficult/state-tracker
+
+File-based state persistence for recovery across restarts.
+
+## Installation
+
+```bash
+npm install @hardlydifficult/state-tracker
+```
+
+## Quick Start
+
+```typescript
+import { StateTracker } from '@hardlydifficult/state-tracker';
+
+const tracker = new StateTracker({ key: 'last-sync', default: 0 });
+
+// Load persisted value (or default on first run)
+const lastSync = tracker.load();
+
+// Save updated value (atomic write)
+tracker.save(Date.now());
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `key` | Unique identifier for the state file (alphanumeric, hyphens, underscores) |
+| `default` | Default value returned when no state exists (also sets the type) |
+| `stateDirectory?` | Custom directory for state files (default: `~/.app-state` or `STATE_TRACKER_DIR` env) |
+
+## Features
+
+- **Type inference** from the default value
+- **Atomic writes** via temp file + rename to prevent corruption
+- **Key sanitization** to prevent path traversal

package/dist/StateTracker.d.ts

@@ -0,0 +1,16 @@
+export interface StateTrackerOptions<T> {
+    key: string;
+    default: T;
+    stateDirectory?: string;
+}
+export declare class StateTracker<T> {
+    private readonly filePath;
+    private readonly defaultValue;
+    private static sanitizeKey;
+    private static getDefaultStateDirectory;
+    constructor(options: StateTrackerOptions<T>);
+    load(): T;
+    save(value: T): void;
+    getFilePath(): string;
+}
+//# sourceMappingURL=StateTracker.d.ts.map

package/dist/StateTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateTracker.d.ts","sourceRoot":"","sources":["../src/StateTracker.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAI;IAEjC,OAAO,CAAC,MAAM,CAAC,WAAW;IAa1B,OAAO,CAAC,MAAM,CAAC,wBAAwB;gBAQ3B,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAY3C,IAAI,IAAI,CAAC;IAiBT,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAUpB,WAAW,IAAI,MAAM;CAGtB"}

package/dist/StateTracker.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateTracker = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+class StateTracker {
+    filePath;
+    defaultValue;
+    static sanitizeKey(key) {
+        const trimmed = key.trim();
+        if (trimmed === "") {
+            throw new Error("StateTracker key must be a non-empty string");
+        }
+        if (!/^[A-Za-z0-9_-]+$/.test(trimmed)) {
+            throw new Error("StateTracker key contains invalid characters (only alphanumeric, hyphens, and underscores allowed)");
+        }
+        return trimmed;
+    }
+    static getDefaultStateDirectory() {
+        const envDir = process.env.STATE_TRACKER_DIR;
+        if (envDir !== undefined && envDir !== "") {
+            return envDir;
+        }
+        return path.join(os.homedir(), ".app-state");
+    }
+    constructor(options) {
+        const sanitizedKey = StateTracker.sanitizeKey(options.key);
+        this.defaultValue = options.default;
+        const stateDirectory = options.stateDirectory ?? StateTracker.getDefaultStateDirectory();
+        if (!fs.existsSync(stateDirectory)) {
+            fs.mkdirSync(stateDirectory, { recursive: true });
+        }
+        this.filePath = path.join(stateDirectory, `${sanitizedKey}.json`);
+    }
+    load() {
+        if (!fs.existsSync(this.filePath)) {
+            return this.defaultValue;
+        }
+        try {
+            const data = fs.readFileSync(this.filePath, "utf-8");
+            const state = JSON.parse(data);
+            const { value } = state;
+            if (value === undefined) {
+                return this.defaultValue;
+            }
+            return value;
+        }
+        catch {
+            return this.defaultValue;
+        }
+    }
+    save(value) {
+        const state = {
+            value,
+            lastUpdated: new Date().toISOString(),
+        };
+        const tempFilePath = `${this.filePath}.tmp`;
+        fs.writeFileSync(tempFilePath, JSON.stringify(state, null, 2), "utf-8");
+        fs.renameSync(tempFilePath, this.filePath);
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+}
+exports.StateTracker = StateTracker;
+//# sourceMappingURL=StateTracker.js.map

package/dist/StateTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateTracker.js","sourceRoot":"","sources":["../src/StateTracker.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAQ7B,MAAa,YAAY;IACN,QAAQ,CAAS;IACjB,YAAY,CAAI;IAEzB,MAAM,CAAC,WAAW,CAAC,GAAW;QACpC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACb,oGAAoG,CACrG,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,MAAM,CAAC,wBAAwB;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAC1C,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED,YAAY,OAA+B;QACzC,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3D,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;QACpC,MAAM,cAAc,GAClB,OAAO,CAAC,cAAc,IAAI,YAAY,CAAC,wBAAwB,EAAE,CAAC;QAEpE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YACnC,EAAE,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,YAAY,OAAO,CAAC,CAAC;IACpE,CAAC;IAED,IAAI;QACF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,YAAY,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;YAC1D,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;YACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,IAAI,CAAC,YAAY,CAAC;YAC3B,CAAC;YACD,OAAO,KAAU,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,YAAY,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAQ;QACX,MAAM,KAAK,GAA4B;YACrC,KAAK;YACL,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;QACF,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,QAAQ,MAAM,CAAC;QAC5C,EAAE,CAAC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACxE,EAAE,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAnED,oCAmEC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { StateTracker, type StateTrackerOptions } from "./StateTracker";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateTracker = void 0;
+var StateTracker_1 = require("./StateTracker");
+Object.defineProperty(exports, "StateTracker", { enumerable: true, get: function () { return StateTracker_1.StateTracker; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+CAAwE;AAA/D,4GAAA,YAAY,OAAA"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hardlydifficult/state-tracker",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.31",
+    "typescript": "5.8.3",
+    "vitest": "1.6.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}