@hardlydifficult/poller 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/poller
 
-A generic polling utility that periodically fetches data and invokes a callback only when the result changes, using JSON-based deep equality comparison.
+A lightweight, generic polling utility with debounced triggers, overlapping request handling, and deep equality change detection.
 
 ## Installation
 
@@ -13,192 +13,132 @@ npm install @hardlydifficult/poller
 ```typescript
 import { Poller } from "@hardlydifficult/poller";
 
-// Create a poller that fetches mock API data every 5 seconds
+// Define a fetch function (e.g., API call)
+const fetchUser = async () => {
+  const res = await fetch("https://api.example.com/user");
+  return res.json();
+};
+
+// Create and start the poller
 const poller = new Poller(
-  async () => {
-    const response = await fetch("https://api.example.com/status");
-    return await response.json();
-  },
+  fetchUser,
   (current, previous) => {
-    console.log("Status changed:", current);
+    console.log("User updated:", current);
   },
-  5000,
-  (error) => {
-    console.error("Polling error:", error);
-  }
-);
-
-await poller.start();  // Begins polling immediately
-// ... later
-poller.stop();         // Stops polling
-```
-
-### Basic 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
+  5000 // Poll every 5 seconds
 );
 
 await poller.start();
+// Polls every 5s, fires onChange only when JSON data changes
 
-// Manual trigger with debounce (e.g. from a webhook)
-poller.trigger(1000);
+// Manually trigger a debounced poll (e.g., after user action)
+poller.trigger(1000); // Waits 1s, then polls once
 
-// Stop polling
+// Stop polling when no longer needed
 poller.stop();
 ```
 
-## Polling
-
-The `Poller` class fetches data at a configurable interval and invokes a callback when the result changes. It fetches immediately on `start()`, then at the configured interval.
+## Polling Lifecycle
 
-```typescript
-import { Poller } from "@hardlydifficult/poller";
+### Start and Stop
 
-const poller = new Poller(
-  async () => {
-    const response = await fetch("/api/status");
-    return response.json();
-  },
-  (current, previous) => {
-    console.log("Previous:", previous);
-    console.log("Current:", current);
-  },
-  10000 // poll every 10 seconds
-);
-
-await poller.start();
-// Fetches immediately, then every 10 seconds
-```
-
-### `start()`
-
-Starts polling. Fetches immediately, then at the configured interval. Calling `start()` multiple times is safe (idempotent).
+- `start()`: Begins polling at the configured interval. Idempotent—safe to call multiple times.
+- `stop()`: Cancels timers and clears any pending debounced trigger. Safe to call multiple times.
 
 ```typescript
-await poller.start(); // Fetches immediately
-await poller.start(); // No-op, already running
-```
-
-### `stop()`
-
-Stops polling and cleans up all timers.
+await poller.start();
+await poller.start(); // No-op
 
-```typescript
 poller.stop();
-// No more polls will fire
+poller.stop(); // No-op
 ```
 
 ## Change Detection
 
-Changes are detected using JSON serialization for deep equality. Structurally identical objects are considered unchanged—even if they are different references.
+### Deep Equality via JSON
 
-- On first poll, `onChange(current, undefined)` is invoked.
-- On subsequent polls, `onChange(current, previous)` is invoked only if the new value differs structurally.
+Change detection uses `JSON.stringify()` comparison, enabling structural equality checks for objects and arrays—even when references differ.
 
 ```typescript
-const poller = new Poller(
-  async () => ({ count: 5, items: [1, 2, 3] }),
-  (current, previous) => {
-    // Only fires when the JSON representation changes
-    console.log("Changed from", previous, "to", current);
-  },
-  5000
-);
+const fetchFn = async () => ({ items: [1, 2, 3] });
+const onChange = (current, previous) => {
+  // Fires only when structure changes
+};
 
-await poller.start();
+const poller = new Poller(fetchFn, onChange, 1000);
+// Even if new object reference returned, onChange won’t fire unless JSON differs
 ```
 
-## Manual Triggers
-
-Call `trigger()` to manually poll immediately, with optional debouncing. Multiple rapid triggers are coalesced into a single poll.
-
-- Accepts a `debounceMs` parameter (default: `1000`).
-- Multiple rapid calls reset the debounce timer — only the last trigger fires.
-- No-op if the poller is not running.
+### On Change Callback
 
 ```typescript
-const poller = new Poller(
-  async () => await fetchData(),
-  (current, previous) => console.log("Updated:", current),
-  60000
-);
-
-await poller.start();
-
-// Trigger a poll with 1000ms debounce (default)
-poller.trigger();
-
-// Trigger with custom debounce
-poller.trigger(500);
-
-// Multiple rapid triggers coalesce into one poll
-poller.trigger(500);
-poller.trigger(500);
-poller.trigger(500); // Only one poll fires after 500ms
+onChange(current: T, previous: T | undefined): void
 ```
 
+- `current`: Most recently fetched value
+- `previous`: Prior value, or `undefined` on first poll
+
 ## Error Handling
 
-- Errors during fetch are caught and passed to the optional `onError` callback.
-- Polling continues after errors — no automatic retry logic is applied.
+### Optional Error Callback
+
+Provide an `onError` handler to manage fetch failures; polling continues regardless.
 
 ```typescript
 const poller = new Poller(
-  async () => await fetchData(),
-  (current, previous) => console.log("Updated:", current),
+  fetchFn,
+  onChange,
   5000,
   (error) => {
-    console.error("Fetch failed:", error);
-    // Polling continues automatically
+    console.warn("Polling error:", error);
   }
 );
-
-await poller.start();
 ```
 
-## Core Features
+- Errors do not halt the polling interval.
+- If `onError` is omitted, errors are silently suppressed.
+
+## Manual Triggering
+
+### Debounced Triggers
 
-### Polling Lifecycle
+- `trigger(debounceMs?: number)`: Schedules a one-time poll after a debounce delay (default: 1000ms).
+- Multiple rapid calls cancel previous timeouts—only the last one fires.
 
-The `Poller` manages its lifecycle with `start()` and `stop()` methods.
+```typescript
+poller.trigger(2000); // Polls in 2s
+poller.trigger(2000); // Cancelled, re-schedule to 2s from now
+poller.trigger(2000); // Cancelled again, final delay applies
+```
 
-- `start()`: Begins polling immediately and then at the configured interval. Idempotent — calling it multiple times has no effect after the first call.
-- `stop()`: Clears the polling timer and any pending debounced triggers. No-op if already stopped.
+- No-op if `poller` is not running.
 
-### Concurrent Fetch Handling
+## Overlap Handling
 
-Overlapping fetches (e.g., due to slow network) are automatically skipped:
-- If `poll()` is already running when the interval fires, the next poll is skipped until the current one completes.
+- Concurrent fetches are skipped—only one in-flight request is allowed at a time.
+- Prevents resource waste and race conditions during slow network calls.
+
+```typescript
+// Interval fires every 5s; if fetch takes 6s:
+// - Second interval fire is skipped
+// - Third interval fire executes after first completes
+```
 
 ## API Reference
 
-### `Poller<T>` Constructor
+### `Poller<T>`
 
-| Parameter   | Type                                  | Description                              |
-|-------------|---------------------------------------|------------------------------------------|
-| `fetchFn`   | `() => Promise<T>`                    | Async function returning the current state |
-| `onChange`  | `(current: T, previous: T | undefined) => void` | Callback invoked on state changes        |
-| `intervalMs`| `number`                              | Polling interval in milliseconds         |
-| `onError?`  | `(error: unknown) => void`            | Optional callback for fetch errors       |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fetchFn` | `() => Promise<T>` | Async function to fetch data |
+| `onChange` | `(current: T, previous: T \| undefined) => void` | Callback on value change |
+| `intervalMs` | `number` | Polling interval in milliseconds |
+| `onError?` | `(error: unknown) => void` | Optional error handler |
 
 ### Methods
 
-| Method       | Signature                              | Description                                  |
-|--------------|----------------------------------------|----------------------------------------------|
-| `start()`    | `(): Promise<void>`                    | Begins polling (immediate + interval-based) |
-| `stop()`     | `(): void`                             | Stops polling and clears timers              |
-| `trigger()`  | `(debounceMs?: number) => void`        | Triggers a debounced manual poll             |
-
-### Behavior
-
-- **Deep equality** — uses JSON serialization to detect structural 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
-- **Debounced triggers** — multiple `trigger()` calls coalesce into one poll
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `start` | `(): Promise<void>` | Begin polling immediately and then at `intervalMs` |
+| `stop` | `(): void` | Cancel all timers and pending triggers |
+| `trigger` | `(debounceMs?: number) => void` | Trigger a one-time poll after debounce delay |

package/package.json

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