@hardlydifficult/poller 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# @hardlydifficult/poller
+
+Generic state-change poller. Polls a function at an interval and fires a callback when the result changes.
+
+## Install
+
+```bash
+npm install @hardlydifficult/poller
+```
+
+## Usage
+
+```typescript
+import { Poller } from "@hardlydifficult/poller";
+
+const poller = new Poller(
+  async () => await fetchCurrentState(),
+  (current, previous) => console.log("State changed!", current),
+  5 * 60 * 1000 // poll every 5 minutes
+);
+
+await poller.start();
+
+// Manual trigger with debounce (e.g. from a webhook)
+poller.trigger(1000);
+
+// Stop polling
+poller.stop();
+```
+
+## API
+
+### `new Poller<T>(fetchFn, onChange, intervalMs, onError?)`
+
+| Parameter | Description |
+|-----------|-------------|
+| `fetchFn` | Async function that returns the current state |
+| `onChange` | Called with `(current, previous)` when state changes |
+| `intervalMs` | Polling interval in milliseconds |
+| `onError` | Optional error handler; polling continues on errors |
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Start polling (fetches immediately, then at interval) |
+| `stop()` | Stop polling and clean up timers |
+| `trigger(debounceMs?)` | Manually trigger a poll with debounce (default 1000ms) |
+
+### Behavior
+
+- **Deep equality** -- uses JSON serialization to detect changes
+- **Overlap prevention** -- skips a poll if the previous fetch is still running
+- **Error resilience** -- continues polling after fetch errors
+- **Idempotent start** -- calling `start()` multiple times is safe

package/dist/Poller.d.ts

@@ -0,0 +1,17 @@
+export declare class Poller<T> {
+    private readonly fetchFn;
+    private readonly onChange;
+    private readonly intervalMs;
+    private readonly onError?;
+    private timer;
+    private previous;
+    private running;
+    private fetching;
+    private triggerTimeout;
+    constructor(fetchFn: () => Promise<T>, onChange: (current: T, previous: T | undefined) => void, intervalMs: number, onError?: (error: unknown) => void);
+    start(): Promise<void>;
+    stop(): void;
+    trigger(debounceMs?: number): void;
+    private poll;
+}
+//# sourceMappingURL=Poller.d.ts.map

package/dist/Poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Poller.d.ts","sourceRoot":"","sources":["../src/Poller.ts"],"names":[],"mappings":"AAAA,qBAAa,MAAM,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA2B;IAEpD,OAAO,CAAC,KAAK,CAA6C;IAC1D,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAA4C;gBAGhE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,KAAK,IAAI,EACvD,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAQ9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,IAAI,IAAI,IAAI;IAYZ,OAAO,CAAC,UAAU,SAAO,GAAG,IAAI;YAalB,IAAI;CAuBnB"}

package/dist/Poller.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Poller = void 0;
+class Poller {
+    fetchFn;
+    onChange;
+    intervalMs;
+    onError;
+    timer;
+    previous;
+    running = false;
+    fetching = false;
+    triggerTimeout;
+    constructor(fetchFn, onChange, intervalMs, onError) {
+        this.fetchFn = fetchFn;
+        this.onChange = onChange;
+        this.intervalMs = intervalMs;
+        this.onError = onError;
+    }
+    async start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        await this.poll();
+        this.timer = setInterval(() => {
+            void this.poll();
+        }, this.intervalMs);
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.triggerTimeout) {
+            clearTimeout(this.triggerTimeout);
+            this.triggerTimeout = undefined;
+        }
+    }
+    trigger(debounceMs = 1000) {
+        if (!this.running) {
+            return;
+        }
+        if (this.triggerTimeout) {
+            clearTimeout(this.triggerTimeout);
+        }
+        this.triggerTimeout = setTimeout(() => {
+            this.triggerTimeout = undefined;
+            void this.poll();
+        }, debounceMs);
+    }
+    async poll() {
+        if (this.fetching) {
+            return;
+        }
+        this.fetching = true;
+        try {
+            const current = await this.fetchFn();
+            const currentJson = JSON.stringify(current);
+            const previousJson = JSON.stringify(this.previous);
+            if (currentJson !== previousJson) {
+                this.onChange(current, this.previous);
+                this.previous = current;
+            }
+        }
+        catch (error) {
+            if (this.onError) {
+                this.onError(error);
+            }
+        }
+        finally {
+            this.fetching = false;
+        }
+    }
+}
+exports.Poller = Poller;
+//# sourceMappingURL=Poller.js.map

package/dist/Poller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Poller.js","sourceRoot":"","sources":["../src/Poller.ts"],"names":[],"mappings":";;;AAAA,MAAa,MAAM;IACA,OAAO,CAAmB;IAC1B,QAAQ,CAAgD;IACxD,UAAU,CAAS;IACnB,OAAO,CAA4B;IAE5C,KAAK,CAA6C;IAClD,QAAQ,CAAgB;IACxB,OAAO,GAAG,KAAK,CAAC;IAChB,QAAQ,GAAG,KAAK,CAAC;IACjB,cAAc,CAA4C;IAElE,YACE,OAAyB,EACzB,QAAuD,EACvD,UAAkB,EAClB,OAAkC;QAElC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAClC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO,CAAC,UAAU,GAAG,IAAI;QACvB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;YAChC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAEnD,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;gBACjC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;YAC1B,CAAC;QACH,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAnFD,wBAmFC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Poller } from "./Poller.js";
+//# 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,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Poller = void 0;
+var Poller_js_1 = require("./Poller.js");
+Object.defineProperty(exports, "Poller", { enumerable: true, get: function () { return Poller_js_1.Poller; } });
+//# 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,yCAAqC;AAA5B,mGAAA,MAAM,OAAA"}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hardlydifficult/poller",
+  "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"
+  }
+}