@hardlydifficult/poller 1.0.8 → 1.0.10

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/poller
 
-A lightweight, generic 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
 
@@ -13,132 +13,88 @@ npm install @hardlydifficult/poller
 ```typescript
 import { Poller } from "@hardlydifficult/poller";
 
-// Define a fetch function (e.g., API call)
-const fetchUser = async () => {
-  const res = await fetch("https://api.example.com/user");
-  return res.json();
+const fetchFn = async () => {
+  const response = await fetch("https://api.example.com/status");
+  return response.json();
 };
 
-// Create and start the poller
 const poller = new Poller(
-  fetchUser,
-  (current, previous) => {
-    console.log("User updated:", current);
-  },
-  5000 // Poll every 5 seconds
+  fetchFn,
+  (data, prev) => console.log("Data changed:", data),
+  5000 // 5-second interval
 );
 
 await poller.start();
-// Polls every 5s, fires onChange only when JSON data changes
-
-// Manually trigger a debounced poll (e.g., after user action)
-poller.trigger(1000); // Waits 1s, then polls once
+// Polls every 5 seconds and logs only when data changes
 
-// Stop polling when no longer needed
+// Later, stop polling
 poller.stop();
 ```
 
-## Polling Lifecycle
+## Polling with Change Detection
+
+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 Parameters
 
-### Start and Stop
+| 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          |
 
-- `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.
+### Poller API
 
 ```typescript
+// Start polling (idempotent — safe to call multiple times)
 await poller.start();
-await poller.start(); // No-op
 
+// Stop polling and clear timers
 poller.stop();
-poller.stop(); // No-op
-```
-
-## Change Detection
-
-### Deep Equality via JSON
-
-Change detection uses `JSON.stringify()` comparison, enabling structural equality checks for objects and arrays—even when references differ.
 
-```typescript
-const fetchFn = async () => ({ items: [1, 2, 3] });
-const onChange = (current, previous) => {
-  // Fires only when structure changes
-};
-
-const poller = new Poller(fetchFn, onChange, 1000);
-// Even if new object reference returned, onChange won’t fire unless JSON differs
+// Manually trigger a poll (debounced by default)
+poller.trigger(1000); // Debounced 1s (default 1000ms)
 ```
 
-### On Change Callback
+### Debounced Manual Trigger
+
+The `trigger()` method allows manually forcing a poll while debouncing multiple rapid calls:
 
 ```typescript
-onChange(current: T, previous: T | undefined): void
+await poller.start();
+poller.trigger(500); // Schedules a poll after 500ms
+poller.trigger(500); // Resets debounce — only one poll fires
 ```
 
-- `current`: Most recently fetched value
-- `previous`: Prior value, or `undefined` on first poll
-
-## Error Handling
+### Error Handling
 
-### Optional Error Callback
-
-Provide an `onError` handler to manage fetch failures; polling continues regardless.
+Errors during polling do not halt the poller. They are optionally reported via `onError`, if provided.
 
 ```typescript
 const poller = new Poller(
-  fetchFn,
-  onChange,
-  5000,
-  (error) => {
-    console.warn("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
 ```
 
-- Errors do not halt the polling interval.
-- If `onError` is omitted, errors are silently suppressed.
-
-## Manual Triggering
+## Overlapping Request Handling
 
-### Debounced Triggers
-
-- `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` skips new polls while a fetch is still in progress, preventing overlapping requests.
 
 ```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
-```
-
-- No-op if `poller` is not running.
-
-## Overlap Handling
-
-- 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>`
-
-| 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>` | 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 |
+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();
+// 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.8",
+  "version": "1.0.10",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [