@hardlydifficult/poller 1.0.10 → 1.0.11

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/poller
 
-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,51 +13,73 @@ npm install @hardlydifficult/poller
 ```typescript
 import { Poller } from "@hardlydifficult/poller";
 
-const fetchFn = async () => {
-  const response = await fetch("https://api.example.com/status");
-  return response.json();
+const fetchUser = async () => {
+  const res = await fetch("https://api.example.com/user");
+  return res.json();
 };
 
 const poller = new Poller(
-  fetchFn,
-  (data, prev) => console.log("Data changed:", data),
-  5000 // 5-second interval
+  fetchUser,
+  (user, previousUser) => {
+    console.log("User changed:", user);
+  },
+  5000 // Poll every 5 seconds
 );
 
 await poller.start();
-// Polls every 5 seconds and logs only when data changes
+// Polling begins immediately and every 5 seconds
+
+// Optionally, manually trigger a poll with debounce
+poller.trigger(1000); // Fires after 1s of inactivity
 
-// Later, stop polling
+// Stop polling when no longer needed
 poller.stop();
 ```
 
 ## 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.
+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.
 
 ### Constructor Parameters
 
-| 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          |
+| 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 |
 
-### Poller API
+### `start(): Promise<void>`
+
+Begins polling immediately and at the configured interval.
 
 ```typescript
-// Start polling (idempotent — safe to call multiple times)
 await poller.start();
+// Polls once immediately, then every intervalMs ms
+```
 
-// Stop polling and clear timers
+### `stop(): void`
+
+Stops polling and clears any pending debounced triggers.
+
+```typescript
 poller.stop();
+// No further polls occur; timers cleared
+```
+
+### `trigger(debounceMs?: number): void`
 
-// Manually trigger a poll (debounced by default)
-poller.trigger(1000); // Debounced 1s (default 1000ms)
+Manually trigger a poll with debouncing to avoid excessive requests during rapid events.
+
+```typescript
+// Default debounce: 1000ms
+poller.trigger();
+
+// Custom debounce
+poller.trigger(2000); // Fires after 2 seconds of no other triggers
 ```
 
-### Debounced Manual Trigger
+## Debounced Manual Trigger
 
 The `trigger()` method allows manually forcing a poll while debouncing multiple rapid calls:
 
@@ -67,7 +89,7 @@ poller.trigger(500); // Schedules a poll after 500ms
 poller.trigger(500); // Resets debounce — only one poll fires
 ```
 
-### Error Handling
+## Error Handling
 
 Errors during polling do not halt the poller. They are optionally reported via `onError`, if provided.
 
@@ -90,11 +112,23 @@ await poller.start();
 The `Poller` skips new polls while a fetch is still in progress, preventing overlapping requests.
 
 ```typescript
-const fetchFn = vi.fn().mockImplementation(() => {
+const fetchFn = async () => {
   // Simulates slow network — never resolves before interval
-  return new Promise((resolve) => setTimeout(() => resolve("data"), 6000));
-});
+  await new Promise((resolve) => setTimeout(resolve, 6000));
+  return "data";
+};
 const poller = new Poller(fetchFn, () => {}, 1000);
 await poller.start();
 // 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.10",
+  "version": "1.0.11",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [