@hardlydifficult/poller 1.0.9 → 1.0.11

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/poller
 
-A lightweight polling utility with debounced triggers, overlapping request handling, and deep equality change detection.
+A lightweight polling utility with debounced manual triggers, overlapping request handling, and deep equality change detection.
 
 ## Installation
 
@@ -13,81 +13,122 @@ npm install @hardlydifficult/poller
 ```typescript
 import { Poller } from "@hardlydifficult/poller";
 
-const fetchFn = async () => {
-  const response = await fetch("https://api.example.com/data");
-  return response.json();
-};
-
-const onChange = (current: unknown, previous: unknown) => {
-  console.log("Data changed:", current);
+const fetchUser = async () => {
+  const res = await fetch("https://api.example.com/user");
+  return res.json();
 };
 
-const poller = new Poller(fetchFn, onChange, 5000);
+const poller = new Poller(
+  fetchUser,
+  (user, previousUser) => {
+    console.log("User changed:", user);
+  },
+  5000 // Poll every 5 seconds
+);
 
 await poller.start();
-// => Starts polling every 5 seconds, firing onChange on first fetch and any change
+// Polling begins immediately and every 5 seconds
 
-poller.trigger(1000);
-// => Triggers a debounced poll after 1 second (overriding any previous trigger call)
-```
+// Optionally, manually trigger a poll with debounce
+poller.trigger(1000); // Fires after 1s of inactivity
 
-## Poller Class
+// Stop polling when no longer needed
+poller.stop();
+```
 
-A generic polling utility that periodically fetches data and invokes a callback when the result changes.
+## Polling with Change Detection
 
-### Constructor
+The `Poller` class periodically fetches data using a user-provided async function and invokes a callback only when the result changes. Change detection uses deep equality via `JSON.stringify`, ensuring structurally identical values (even with different object references) do not trigger redundant callbacks.
 
-| 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    |
+### Constructor Parameters
 
-### Methods
+| Parameter | Type | Description |
+|------|--|---------|
+| `fetchFn` | `() => Promise<T>` | Async function that fetches the data to poll |
+| `onChange` | `(current: T, previous: T \| undefined) => void` | Callback invoked when data changes (using deep equality) |
+| `intervalMs` | `number` | Polling interval in milliseconds |
+| `onError?` | `(error: unknown) => void` | Optional callback for fetch errors |
 
-#### `start(): Promise<void>`
+### `start(): Promise<void>`
 
-Starts polling at the configured interval. Does nothing if already running.
+Begins polling immediately and at the configured interval.
 
 ```typescript
 await poller.start();
-// => Begins polling; invokes onChange immediately on first fetch
+// Polls once immediately, then every intervalMs ms
 ```
 
-#### `stop(): void`
+### `stop(): void`
 
-Stops polling and clears all timers (including any pending debounced trigger).
+Stops polling and clears any pending debounced triggers.
 
 ```typescript
 poller.stop();
-// => Immediately halts polling and cancels pending triggers
+// No further polls occur; timers cleared
 ```
 
-#### `trigger(debounceMs = 1000): void`
+### `trigger(debounceMs?: number): void`
 
-Triggers a debounced poll. Multiple rapid calls reset the debounce timer.
+Manually trigger a poll with debouncing to avoid excessive requests during rapid events.
 
 ```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
+// Default debounce: 1000ms
+poller.trigger();
+
+// Custom debounce
+poller.trigger(2000); // Fires after 2 seconds of no other triggers
 ```
 
-### Behavior
+## Debounced Manual Trigger
 
-- **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.
+The `trigger()` method allows manually forcing a poll while debouncing multiple rapid calls:
+
+```typescript
+await poller.start();
+poller.trigger(500); // Schedules a poll after 500ms
+poller.trigger(500); // Resets debounce — only one poll fires
+```
+
+## Error Handling
+
+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 = async () => {
+  // Simulates slow network — never resolves before interval
+  await new Promise((resolve) => setTimeout(resolve, 6000));
+  return "data";
+};
+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
+```
+
+## Deep Equality Detection
+
+The `Poller` uses `JSON.stringify` to compare current and previous values, enabling detection of structural changes in objects and arrays.
+
+```typescript
+const fetchCount = async () => ({ value: 1 });
+const poller = new Poller(fetchCount, (curr, prev) => {
+  // Fires only when value changes
+}, 1000);
 ```

package/package.json

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