@hardlydifficult/poller 1.0.9 → 1.0.10

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/poller
 
-A lightweight polling utility with debounced triggers, overlapping request handling, and deep equality change detection.
+Lightweight polling utility with debounced triggers, overlapping request handling, and deep equality change detection.
 
 ## Installation
 
@@ -14,80 +14,87 @@ npm install @hardlydifficult/poller
 import { Poller } from "@hardlydifficult/poller";
 
 const fetchFn = async () => {
-  const response = await fetch("https://api.example.com/data");
+  const response = await fetch("https://api.example.com/status");
   return response.json();
 };
 
-const onChange = (current: unknown, previous: unknown) => {
-  console.log("Data changed:", current);
-};
-
-const poller = new Poller(fetchFn, onChange, 5000);
+const poller = new Poller(
+  fetchFn,
+  (data, prev) => console.log("Data changed:", data),
+  5000 // 5-second interval
+);
 
 await poller.start();
-// => Starts polling every 5 seconds, firing onChange on first fetch and any change
+// Polls every 5 seconds and logs only when data changes
 
-poller.trigger(1000);
-// => Triggers a debounced poll after 1 second (overriding any previous trigger call)
+// Later, stop polling
+poller.stop();
 ```
 
-## Poller Class
+## Polling with Change Detection
 
-A generic polling utility that periodically fetches data and invokes a callback when the result changes.
+The `Poller` class polls a fetch function periodically and invokes a callback only when the result changes. Change detection uses deep equality via `JSON.stringify` comparison, ensuring that structurally identical values (even with different object references) do not trigger redundant callbacks.
 
-### Constructor
+### Constructor Parameters
 
-| Parameter    | Type                              | Description                                  |
-|--------------|-----------------------------------|----------------------------------------------|
-| `fetchFn`    | `() => Promise<T>`                | Async function that fetches the latest data  |
-| `onChange`   | `(current: T, previous: T | undefined) => void` | Callback invoked when data changes         |
-| `intervalMs` | `number`                          | Polling interval in milliseconds             |
-| `onError?`   | `(error: unknown) => void`        | Optional callback invoked on fetch errors    |
+| Parameter   | Type                                | Description                                         |
+|-------------|-------------------------------------|-----------------------------------------------------|
+| `fetchFn`   | `() => Promise<T>`                  | Async function that returns the data to poll        |
+| `onChange`  | `(current: T, previous: T | undefined) => void` | Callback invoked when data changes                  |
+| `intervalMs`| `number`                            | Polling interval in milliseconds                    |
+| `onError?`  | `(error: unknown) => void` (optional) | Optional error handler for fetch failures          |
 
-### Methods
-
-#### `start(): Promise<void>`
-
-Starts polling at the configured interval. Does nothing if already running.
+### Poller API
 
 ```typescript
+// Start polling (idempotent — safe to call multiple times)
 await poller.start();
-// => Begins polling; invokes onChange immediately on first fetch
-```
-
-#### `stop(): void`
 
-Stops polling and clears all timers (including any pending debounced trigger).
-
-```typescript
+// Stop polling and clear timers
 poller.stop();
-// => Immediately halts polling and cancels pending triggers
+
+// Manually trigger a poll (debounced by default)
+poller.trigger(1000); // Debounced 1s (default 1000ms)
 ```
 
-#### `trigger(debounceMs = 1000): void`
+### Debounced Manual Trigger
 
-Triggers a debounced poll. Multiple rapid calls reset the debounce timer.
+The `trigger()` method allows manually forcing a poll while debouncing multiple rapid calls:
 
 ```typescript
-poller.trigger(500); // Debounce: 500 ms
-poller.trigger(200); // Resets to 200 ms from now
-// Only one poll fires after the last trigger delay
+await poller.start();
+poller.trigger(500); // Schedules a poll after 500ms
+poller.trigger(500); // Resets debounce — only one poll fires
 ```
 
-### Behavior
+### Error Handling
 
-- **Deep equality detection**: Uses `JSON.stringify` to detect structural changes, even with new object references.
-- **Overlapping request handling**: Skips polls while a fetch is in progress.
-- **Error resilience**: Continues polling on errors if `onError` is provided; otherwise, errors are silently ignored.
+Errors during polling do not halt the poller. They are optionally reported via `onError`, if provided.
 
 ```typescript
 const poller = new Poller(
-  async () => fetch("https://api.example.com/status").then(r => r.json()),
-  (current, previous) => console.log("Status changed:", current),
-  10000, // 10 seconds
-  (error) => console.error("Polling error:", error)
+  async () => {
+    throw new Error("Network failure");
+  },
+  (data) => console.log(data),
+  2000,
+  (error) => console.error("Poll failed:", error)
 );
+await poller.start();
+// Logs: Poll failed: Error: Network failure
+// Continues polling after each error
+```
+
+## Overlapping Request Handling
 
+The `Poller` skips new polls while a fetch is still in progress, preventing overlapping requests.
+
+```typescript
+const fetchFn = vi.fn().mockImplementation(() => {
+  // Simulates slow network — never resolves before interval
+  return new Promise((resolve) => setTimeout(() => resolve("data"), 6000));
+});
+const poller = new Poller(fetchFn, () => {}, 1000);
 await poller.start();
-poller.trigger(500); // Manual override after 0.5s if triggered again
+// Only one fetch runs at a time — subsequent intervals are skipped until it completes
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/poller",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [