use-poller 0.0.1 → 0.1.0

package/README.md

@@ -1,20 +1,138 @@
 # use-poller
 
-Initial placeholder release for claiming the `use-poller` package name on npm.
+Polling done right for the cases where cache-oriented query tools are not the right fit.
 
-## Status
+`use-poller` is a tiny React hook for robust async polling with:
 
-`0.0.1` is intentionally minimal and does not provide the final polling hook API yet.
+- no request overlap,
+- abort on stop/unmount,
+- optional pause when tab is hidden/offline,
+- optional exponential backoff and stop-on-error,
+- stable control API (`start`, `stop`, `refresh`).
 
-## Why this exists
+## Behavior guarantees
 
-This release reserves the package name while the full implementation is being completed.
+- Next tick is scheduled only after the previous callback settles (no overlap).
+- Active request is aborted on `stop()` and unmount.
+- Polling can pause when the page is hidden or offline and resume on return.
+- `refresh()` runs now and re-aligns the next scheduled tick.
 
-## Roadmap
+## Install
 
-- Deliver production-ready `usePoller` hook
-- Add full test coverage for timing and lifecycle edge cases
-- Publish full docs and examples
+```bash
+npm i use-poller
+```
+
+## Quick start
+
+```ts
+import { usePoller } from "use-poller";
+
+const { data, error, isPolling, stop } = usePoller(
+  async ({ signal }) => {
+    const response = await fetch("/api/export/status", { signal });
+    const payload = await response.json();
+    if (payload.status === "done") {
+      stop();
+    }
+    return payload;
+  },
+  { interval: 2000 },
+);
+```
+
+## API
+
+```ts
+function usePoller<T>(
+  callback: PollerCallback<T>,
+  options?: UsePollerOptions<T>,
+): UsePollerResult<T>;
+```
+
+### `PollerCallback<T>`
+
+```ts
+type PollerCallback<T> = (ctx: {
+  signal: AbortSignal;
+  attempt: number;
+}) => T | Promise<T>;
+```
+
+Pass `signal` to your async work (for example `fetch(url, { signal })`) so the hook can cancel in-flight work safely during `stop`, unmount, or pause transitions.
+
+### `UsePollerOptions<T>`
+
+- `interval?: number | ((ctx: { data: T | undefined; attempt: number }) => number)` (default `5000`)
+- `enabled?: boolean` (default `true`)
+- `immediate?: boolean` (default `true`)
+- `pauseOnHidden?: boolean` (default `true`)
+- `pauseOnOffline?: boolean` (default `false`)
+- `backoff?: { factor: number; max: number } | false` (default `{ factor: 2, max: 30000 }`)
+- `stopOnError?: boolean | number` (default `false`, `true` means stop after first error)
+- `onSuccess?: (data: T) => void`
+- `onError?: (error: unknown) => void`
+
+### `UsePollerResult<T>`
+
+- `data: T | undefined`
+- `error: unknown | null`
+- `isPolling: boolean`
+- `isFetching: boolean`
+- `lastUpdated: number | null`
+- `start: () => void`
+- `stop: () => void`
+- `refresh: () => Promise<T | undefined>`
+
+## Recipes
+
+### Health check with backoff
+
+```ts
+usePoller(({ signal }) => fetch("/health", { signal }).then((r) => r.json()), {
+  interval: 5000,
+  backoff: { factor: 2, max: 60000 },
+  stopOnError: 5,
+});
+```
+
+### Dynamic interval
+
+```ts
+usePoller(fetchNotifications, {
+  interval: ({ data }) => (data?.unread ? 3000 : 15000),
+});
+```
+
+### Manual refresh
+
+```ts
+const poller = usePoller(fetchStatus, { interval: 5000 });
+
+await poller.refresh(); // run immediately and reset next tick countdown
+```
+
+### Pause when offline
+
+```ts
+usePoller(fetchStatus, {
+  interval: 3000,
+  pauseOnOffline: true,
+});
+```
+
+## `use-poller` vs TanStack Query
+
+- Use TanStack Query when data lifecycle is cache-centric and query-driven.
+- Use `use-poller` when you need imperative polling loops or side effects outside query cache semantics.
+
+They complement each other.
+
+## Compatibility
+
+- React `>=18`
+- SSR-safe (no `window`/`document` access during render)
+- StrictMode-safe cleanup
 
 ## License
 

package/dist/index.cjs

@@ -23,9 +23,316 @@ __export(index_exports, {
   usePoller: () => usePoller
 });
 module.exports = __toCommonJS(index_exports);
-function usePoller() {
-  throw new Error(
-    "use-poller@0.0.1 is a placeholder release. Full implementation is coming next."
+
+// src/usePoller.ts
+var import_react = require("react");
+var DEFAULT_INTERVAL = 5e3;
+var DEFAULT_BACKOFF = { factor: 2, max: 3e4 };
+var isBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+var toPositiveDelay = (value) => {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value;
+};
+var resolveInterval = (interval, data, attempt) => {
+  const raw = typeof interval === "function" ? interval({ data, attempt }) : interval;
+  return toPositiveDelay(raw);
+};
+var resolveStopOnError = (value) => {
+  if (value === true) {
+    return 1;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return 0;
+};
+function usePoller(callback, options = {}) {
+  const {
+    interval = DEFAULT_INTERVAL,
+    enabled = true,
+    immediate = true,
+    pauseOnHidden = true,
+    pauseOnOffline = false,
+    backoff = DEFAULT_BACKOFF,
+    stopOnError = false,
+    onSuccess,
+    onError
+  } = options;
+  const [data, setData] = (0, import_react.useState)(void 0);
+  const [error, setError] = (0, import_react.useState)(null);
+  const [isPolling, setIsPolling] = (0, import_react.useState)(enabled);
+  const [isFetching, setIsFetching] = (0, import_react.useState)(false);
+  const [lastUpdated, setLastUpdated] = (0, import_react.useState)(null);
+  const callbackRef = (0, import_react.useRef)(callback);
+  const onSuccessRef = (0, import_react.useRef)(onSuccess);
+  const onErrorRef = (0, import_react.useRef)(onError);
+  const intervalRef = (0, import_react.useRef)(interval);
+  const backoffRef = (0, import_react.useRef)(backoff);
+  const stopOnErrorRef = (0, import_react.useRef)(resolveStopOnError(stopOnError));
+  const pauseOnHiddenRef = (0, import_react.useRef)(pauseOnHidden);
+  const pauseOnOfflineRef = (0, import_react.useRef)(pauseOnOffline);
+  const enabledRef = (0, import_react.useRef)(enabled);
+  const dataRef = (0, import_react.useRef)(void 0);
+  const attemptRef = (0, import_react.useRef)(0);
+  const errorStreakRef = (0, import_react.useRef)(0);
+  const mountedRef = (0, import_react.useRef)(false);
+  const isFetchingRef = (0, import_react.useRef)(false);
+  const pollingRef = (0, import_react.useRef)(enabled);
+  const timerRef = (0, import_react.useRef)(null);
+  const activeAbortControllerRef = (0, import_react.useRef)(null);
+  callbackRef.current = callback;
+  onSuccessRef.current = onSuccess;
+  onErrorRef.current = onError;
+  intervalRef.current = interval;
+  backoffRef.current = backoff;
+  stopOnErrorRef.current = resolveStopOnError(stopOnError);
+  pauseOnHiddenRef.current = pauseOnHidden;
+  pauseOnOfflineRef.current = pauseOnOffline;
+  enabledRef.current = enabled;
+  const clearTimer = (0, import_react.useCallback)(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+  const abortActiveRequest = (0, import_react.useCallback)(() => {
+    if (activeAbortControllerRef.current !== null) {
+      activeAbortControllerRef.current.abort();
+      activeAbortControllerRef.current = null;
+      isFetchingRef.current = false;
+      if (mountedRef.current) {
+        setIsFetching(false);
+      }
+    }
+  }, []);
+  const shouldPause = (0, import_react.useCallback)(() => {
+    if (!isBrowser()) {
+      return false;
+    }
+    if (pauseOnHiddenRef.current && document.visibilityState === "hidden") {
+      return true;
+    }
+    if (pauseOnOfflineRef.current && typeof navigator.onLine === "boolean" && !navigator.onLine) {
+      return true;
+    }
+    return false;
+  }, []);
+  const computeNextDelay = (0, import_react.useCallback)(() => {
+    const baseDelay = resolveInterval(
+      intervalRef.current,
+      dataRef.current,
+      attemptRef.current
+    );
+    const currentBackoff = backoffRef.current;
+    if (currentBackoff === false || errorStreakRef.current === 0) {
+      return baseDelay;
+    }
+    const backoffFactor = Math.max(currentBackoff.factor, 1);
+    const multipliedDelay = baseDelay * backoffFactor ** errorStreakRef.current;
+    return Math.min(multipliedDelay, currentBackoff.max);
+  }, []);
+  const setPollingState = (0, import_react.useCallback)((nextValue) => {
+    pollingRef.current = nextValue;
+    setIsPolling(nextValue);
+  }, []);
+  const tickRef = (0, import_react.useRef)(void 0);
+  const maybeResumeTick = (0, import_react.useCallback)(() => {
+    if (!pollingRef.current) {
+      return;
+    }
+    if (shouldPause()) {
+      return;
+    }
+    if (isFetchingRef.current || activeAbortControllerRef.current !== null) {
+      return;
+    }
+    if (timerRef.current !== null) {
+      return;
+    }
+    void tickRef.current?.();
+  }, [shouldPause]);
+  const scheduleNext = (0, import_react.useCallback)(
+    (forcedDelay) => {
+      clearTimer();
+      if (!mountedRef.current || !pollingRef.current) {
+        return;
+      }
+      if (shouldPause()) {
+        return;
+      }
+      const delay = forcedDelay ?? computeNextDelay();
+      timerRef.current = setTimeout(() => {
+        void tickRef.current?.();
+      }, delay);
+    },
+    [clearTimer, computeNextDelay, shouldPause]
+  );
+  const tick = (0, import_react.useCallback)(async () => {
+    if (!mountedRef.current || !pollingRef.current || shouldPause()) {
+      return dataRef.current;
+    }
+    clearTimer();
+    abortActiveRequest();
+    const controller = new AbortController();
+    activeAbortControllerRef.current = controller;
+    isFetchingRef.current = true;
+    setIsFetching(true);
+    attemptRef.current += 1;
+    try {
+      const result = await callbackRef.current({
+        signal: controller.signal,
+        attempt: attemptRef.current
+      });
+      if (!mountedRef.current || controller.signal.aborted) {
+        return dataRef.current;
+      }
+      errorStreakRef.current = 0;
+      setError(null);
+      setData(result);
+      dataRef.current = result;
+      setLastUpdated(Date.now());
+      onSuccessRef.current?.(result);
+      scheduleNext();
+      return result;
+    } catch (caught) {
+      if (!mountedRef.current || controller.signal.aborted) {
+        return dataRef.current;
+      }
+      errorStreakRef.current += 1;
+      setError(caught);
+      onErrorRef.current?.(caught);
+      const maxErrors = stopOnErrorRef.current;
+      if (maxErrors > 0 && errorStreakRef.current >= maxErrors) {
+        setPollingState(false);
+        clearTimer();
+        return dataRef.current;
+      }
+      scheduleNext();
+      return dataRef.current;
+    } finally {
+      if (activeAbortControllerRef.current === controller) {
+        activeAbortControllerRef.current = null;
+      }
+      isFetchingRef.current = false;
+      if (mountedRef.current) {
+        setIsFetching(false);
+      }
+    }
+  }, [
+    abortActiveRequest,
+    clearTimer,
+    scheduleNext,
+    setPollingState,
+    shouldPause
+  ]);
+  tickRef.current = tick;
+  const stop = (0, import_react.useCallback)(() => {
+    setPollingState(false);
+    clearTimer();
+    abortActiveRequest();
+  }, [abortActiveRequest, clearTimer, setPollingState]);
+  const start = (0, import_react.useCallback)(() => {
+    if (!enabledRef.current) {
+      return;
+    }
+    setPollingState(true);
+    maybeResumeTick();
+  }, [maybeResumeTick, setPollingState]);
+  const refresh = (0, import_react.useCallback)(async () => {
+    if (!enabledRef.current || !pollingRef.current) {
+      return dataRef.current;
+    }
+    clearTimer();
+    const result = await tickRef.current?.();
+    clearTimer();
+    scheduleNext();
+    return result ?? dataRef.current;
+  }, [clearTimer, scheduleNext]);
+  (0, import_react.useEffect)(() => {
+    mountedRef.current = true;
+    pollingRef.current = enabled;
+    setIsPolling(enabled);
+    if (enabled && immediate && !shouldPause()) {
+      void tickRef.current?.();
+    } else if (enabled && !immediate) {
+      scheduleNext(resolveInterval(intervalRef.current, dataRef.current, attemptRef.current));
+    }
+    return () => {
+      mountedRef.current = false;
+      clearTimer();
+      abortActiveRequest();
+    };
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (enabled) {
+      if (!pollingRef.current) {
+        setPollingState(true);
+        if (shouldPause()) {
+          return;
+        }
+        if (immediate) {
+          void tickRef.current?.();
+        } else {
+          scheduleNext(resolveInterval(intervalRef.current, dataRef.current, attemptRef.current));
+        }
+      }
+      return;
+    }
+    stop();
+  }, [enabled, immediate, scheduleNext, setPollingState, shouldPause, stop]);
+  (0, import_react.useEffect)(() => {
+    if (!isBrowser()) {
+      return;
+    }
+    const onVisibilityChange = () => {
+      if (!pauseOnHiddenRef.current) {
+        return;
+      }
+      if (document.visibilityState === "hidden") {
+        clearTimer();
+        return;
+      }
+      if (document.visibilityState === "visible") {
+        maybeResumeTick();
+      }
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [clearTimer, maybeResumeTick]);
+  (0, import_react.useEffect)(() => {
+    if (!isBrowser() || !pauseOnOfflineRef.current) {
+      return;
+    }
+    const onOffline = () => {
+      clearTimer();
+      abortActiveRequest();
+    };
+    const onOnline = () => {
+      maybeResumeTick();
+    };
+    window.addEventListener("offline", onOffline);
+    window.addEventListener("online", onOnline);
+    return () => {
+      window.removeEventListener("offline", onOffline);
+      window.removeEventListener("online", onOnline);
+    };
+  }, [abortActiveRequest, clearTimer, maybeResumeTick]);
+  return (0, import_react.useMemo)(
+    () => ({
+      data,
+      error,
+      isPolling,
+      isFetching,
+      lastUpdated,
+      start,
+      stop,
+      refresh
+    }),
+    [data, error, isPolling, isFetching, lastUpdated, start, stop, refresh]
   );
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -1,7 +1,39 @@
-/**
- * Placeholder release to claim the package name on npm.
- * Full hook API is planned for upcoming versions.
- */
-declare function usePoller(): never;
+interface PollerContext {
+    signal: AbortSignal;
+    attempt: number;
+}
+type PollerCallback<T> = (ctx: PollerContext) => T | Promise<T>;
+type PollerIntervalContext<T> = {
+    data: T | undefined;
+    attempt: number;
+};
+type PollerInterval<T> = number | ((ctx: PollerIntervalContext<T>) => number);
+interface PollerBackoff {
+    factor: number;
+    max: number;
+}
+interface UsePollerOptions<T> {
+    interval?: PollerInterval<T>;
+    enabled?: boolean;
+    immediate?: boolean;
+    pauseOnHidden?: boolean;
+    pauseOnOffline?: boolean;
+    backoff?: PollerBackoff | false;
+    stopOnError?: boolean | number;
+    onSuccess?: (data: T) => void;
+    onError?: (error: unknown) => void;
+}
+interface UsePollerResult<T> {
+    data: T | undefined;
+    error: unknown | null;
+    isPolling: boolean;
+    isFetching: boolean;
+    lastUpdated: number | null;
+    start: () => void;
+    stop: () => void;
+    refresh: () => Promise<T | undefined>;
+}
 
-export { usePoller };
+declare function usePoller<T>(callback: PollerCallback<T>, options?: UsePollerOptions<T>): UsePollerResult<T>;
+
+export { type PollerBackoff, type PollerCallback, type PollerContext, type PollerInterval, type PollerIntervalContext, type UsePollerOptions, type UsePollerResult, usePoller };

package/dist/index.d.ts

@@ -1,7 +1,39 @@
-/**
- * Placeholder release to claim the package name on npm.
- * Full hook API is planned for upcoming versions.
- */
-declare function usePoller(): never;
+interface PollerContext {
+    signal: AbortSignal;
+    attempt: number;
+}
+type PollerCallback<T> = (ctx: PollerContext) => T | Promise<T>;
+type PollerIntervalContext<T> = {
+    data: T | undefined;
+    attempt: number;
+};
+type PollerInterval<T> = number | ((ctx: PollerIntervalContext<T>) => number);
+interface PollerBackoff {
+    factor: number;
+    max: number;
+}
+interface UsePollerOptions<T> {
+    interval?: PollerInterval<T>;
+    enabled?: boolean;
+    immediate?: boolean;
+    pauseOnHidden?: boolean;
+    pauseOnOffline?: boolean;
+    backoff?: PollerBackoff | false;
+    stopOnError?: boolean | number;
+    onSuccess?: (data: T) => void;
+    onError?: (error: unknown) => void;
+}
+interface UsePollerResult<T> {
+    data: T | undefined;
+    error: unknown | null;
+    isPolling: boolean;
+    isFetching: boolean;
+    lastUpdated: number | null;
+    start: () => void;
+    stop: () => void;
+    refresh: () => Promise<T | undefined>;
+}
 
-export { usePoller };
+declare function usePoller<T>(callback: PollerCallback<T>, options?: UsePollerOptions<T>): UsePollerResult<T>;
+
+export { type PollerBackoff, type PollerCallback, type PollerContext, type PollerInterval, type PollerIntervalContext, type UsePollerOptions, type UsePollerResult, usePoller };

package/dist/index.js

@@ -1,7 +1,312 @@
-// src/index.ts
-function usePoller() {
-  throw new Error(
-    "use-poller@0.0.1 is a placeholder release. Full implementation is coming next."
+// src/usePoller.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+var DEFAULT_INTERVAL = 5e3;
+var DEFAULT_BACKOFF = { factor: 2, max: 3e4 };
+var isBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+var toPositiveDelay = (value) => {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value;
+};
+var resolveInterval = (interval, data, attempt) => {
+  const raw = typeof interval === "function" ? interval({ data, attempt }) : interval;
+  return toPositiveDelay(raw);
+};
+var resolveStopOnError = (value) => {
+  if (value === true) {
+    return 1;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return 0;
+};
+function usePoller(callback, options = {}) {
+  const {
+    interval = DEFAULT_INTERVAL,
+    enabled = true,
+    immediate = true,
+    pauseOnHidden = true,
+    pauseOnOffline = false,
+    backoff = DEFAULT_BACKOFF,
+    stopOnError = false,
+    onSuccess,
+    onError
+  } = options;
+  const [data, setData] = useState(void 0);
+  const [error, setError] = useState(null);
+  const [isPolling, setIsPolling] = useState(enabled);
+  const [isFetching, setIsFetching] = useState(false);
+  const [lastUpdated, setLastUpdated] = useState(null);
+  const callbackRef = useRef(callback);
+  const onSuccessRef = useRef(onSuccess);
+  const onErrorRef = useRef(onError);
+  const intervalRef = useRef(interval);
+  const backoffRef = useRef(backoff);
+  const stopOnErrorRef = useRef(resolveStopOnError(stopOnError));
+  const pauseOnHiddenRef = useRef(pauseOnHidden);
+  const pauseOnOfflineRef = useRef(pauseOnOffline);
+  const enabledRef = useRef(enabled);
+  const dataRef = useRef(void 0);
+  const attemptRef = useRef(0);
+  const errorStreakRef = useRef(0);
+  const mountedRef = useRef(false);
+  const isFetchingRef = useRef(false);
+  const pollingRef = useRef(enabled);
+  const timerRef = useRef(null);
+  const activeAbortControllerRef = useRef(null);
+  callbackRef.current = callback;
+  onSuccessRef.current = onSuccess;
+  onErrorRef.current = onError;
+  intervalRef.current = interval;
+  backoffRef.current = backoff;
+  stopOnErrorRef.current = resolveStopOnError(stopOnError);
+  pauseOnHiddenRef.current = pauseOnHidden;
+  pauseOnOfflineRef.current = pauseOnOffline;
+  enabledRef.current = enabled;
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+  const abortActiveRequest = useCallback(() => {
+    if (activeAbortControllerRef.current !== null) {
+      activeAbortControllerRef.current.abort();
+      activeAbortControllerRef.current = null;
+      isFetchingRef.current = false;
+      if (mountedRef.current) {
+        setIsFetching(false);
+      }
+    }
+  }, []);
+  const shouldPause = useCallback(() => {
+    if (!isBrowser()) {
+      return false;
+    }
+    if (pauseOnHiddenRef.current && document.visibilityState === "hidden") {
+      return true;
+    }
+    if (pauseOnOfflineRef.current && typeof navigator.onLine === "boolean" && !navigator.onLine) {
+      return true;
+    }
+    return false;
+  }, []);
+  const computeNextDelay = useCallback(() => {
+    const baseDelay = resolveInterval(
+      intervalRef.current,
+      dataRef.current,
+      attemptRef.current
+    );
+    const currentBackoff = backoffRef.current;
+    if (currentBackoff === false || errorStreakRef.current === 0) {
+      return baseDelay;
+    }
+    const backoffFactor = Math.max(currentBackoff.factor, 1);
+    const multipliedDelay = baseDelay * backoffFactor ** errorStreakRef.current;
+    return Math.min(multipliedDelay, currentBackoff.max);
+  }, []);
+  const setPollingState = useCallback((nextValue) => {
+    pollingRef.current = nextValue;
+    setIsPolling(nextValue);
+  }, []);
+  const tickRef = useRef(void 0);
+  const maybeResumeTick = useCallback(() => {
+    if (!pollingRef.current) {
+      return;
+    }
+    if (shouldPause()) {
+      return;
+    }
+    if (isFetchingRef.current || activeAbortControllerRef.current !== null) {
+      return;
+    }
+    if (timerRef.current !== null) {
+      return;
+    }
+    void tickRef.current?.();
+  }, [shouldPause]);
+  const scheduleNext = useCallback(
+    (forcedDelay) => {
+      clearTimer();
+      if (!mountedRef.current || !pollingRef.current) {
+        return;
+      }
+      if (shouldPause()) {
+        return;
+      }
+      const delay = forcedDelay ?? computeNextDelay();
+      timerRef.current = setTimeout(() => {
+        void tickRef.current?.();
+      }, delay);
+    },
+    [clearTimer, computeNextDelay, shouldPause]
+  );
+  const tick = useCallback(async () => {
+    if (!mountedRef.current || !pollingRef.current || shouldPause()) {
+      return dataRef.current;
+    }
+    clearTimer();
+    abortActiveRequest();
+    const controller = new AbortController();
+    activeAbortControllerRef.current = controller;
+    isFetchingRef.current = true;
+    setIsFetching(true);
+    attemptRef.current += 1;
+    try {
+      const result = await callbackRef.current({
+        signal: controller.signal,
+        attempt: attemptRef.current
+      });
+      if (!mountedRef.current || controller.signal.aborted) {
+        return dataRef.current;
+      }
+      errorStreakRef.current = 0;
+      setError(null);
+      setData(result);
+      dataRef.current = result;
+      setLastUpdated(Date.now());
+      onSuccessRef.current?.(result);
+      scheduleNext();
+      return result;
+    } catch (caught) {
+      if (!mountedRef.current || controller.signal.aborted) {
+        return dataRef.current;
+      }
+      errorStreakRef.current += 1;
+      setError(caught);
+      onErrorRef.current?.(caught);
+      const maxErrors = stopOnErrorRef.current;
+      if (maxErrors > 0 && errorStreakRef.current >= maxErrors) {
+        setPollingState(false);
+        clearTimer();
+        return dataRef.current;
+      }
+      scheduleNext();
+      return dataRef.current;
+    } finally {
+      if (activeAbortControllerRef.current === controller) {
+        activeAbortControllerRef.current = null;
+      }
+      isFetchingRef.current = false;
+      if (mountedRef.current) {
+        setIsFetching(false);
+      }
+    }
+  }, [
+    abortActiveRequest,
+    clearTimer,
+    scheduleNext,
+    setPollingState,
+    shouldPause
+  ]);
+  tickRef.current = tick;
+  const stop = useCallback(() => {
+    setPollingState(false);
+    clearTimer();
+    abortActiveRequest();
+  }, [abortActiveRequest, clearTimer, setPollingState]);
+  const start = useCallback(() => {
+    if (!enabledRef.current) {
+      return;
+    }
+    setPollingState(true);
+    maybeResumeTick();
+  }, [maybeResumeTick, setPollingState]);
+  const refresh = useCallback(async () => {
+    if (!enabledRef.current || !pollingRef.current) {
+      return dataRef.current;
+    }
+    clearTimer();
+    const result = await tickRef.current?.();
+    clearTimer();
+    scheduleNext();
+    return result ?? dataRef.current;
+  }, [clearTimer, scheduleNext]);
+  useEffect(() => {
+    mountedRef.current = true;
+    pollingRef.current = enabled;
+    setIsPolling(enabled);
+    if (enabled && immediate && !shouldPause()) {
+      void tickRef.current?.();
+    } else if (enabled && !immediate) {
+      scheduleNext(resolveInterval(intervalRef.current, dataRef.current, attemptRef.current));
+    }
+    return () => {
+      mountedRef.current = false;
+      clearTimer();
+      abortActiveRequest();
+    };
+  }, []);
+  useEffect(() => {
+    if (enabled) {
+      if (!pollingRef.current) {
+        setPollingState(true);
+        if (shouldPause()) {
+          return;
+        }
+        if (immediate) {
+          void tickRef.current?.();
+        } else {
+          scheduleNext(resolveInterval(intervalRef.current, dataRef.current, attemptRef.current));
+        }
+      }
+      return;
+    }
+    stop();
+  }, [enabled, immediate, scheduleNext, setPollingState, shouldPause, stop]);
+  useEffect(() => {
+    if (!isBrowser()) {
+      return;
+    }
+    const onVisibilityChange = () => {
+      if (!pauseOnHiddenRef.current) {
+        return;
+      }
+      if (document.visibilityState === "hidden") {
+        clearTimer();
+        return;
+      }
+      if (document.visibilityState === "visible") {
+        maybeResumeTick();
+      }
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [clearTimer, maybeResumeTick]);
+  useEffect(() => {
+    if (!isBrowser() || !pauseOnOfflineRef.current) {
+      return;
+    }
+    const onOffline = () => {
+      clearTimer();
+      abortActiveRequest();
+    };
+    const onOnline = () => {
+      maybeResumeTick();
+    };
+    window.addEventListener("offline", onOffline);
+    window.addEventListener("online", onOnline);
+    return () => {
+      window.removeEventListener("offline", onOffline);
+      window.removeEventListener("online", onOnline);
+    };
+  }, [abortActiveRequest, clearTimer, maybeResumeTick]);
+  return useMemo(
+    () => ({
+      data,
+      error,
+      isPolling,
+      isFetching,
+      lastUpdated,
+      start,
+      stop,
+      refresh
+    }),
+    [data, error, isPolling, isFetching, lastUpdated, start, stop, refresh]
   );
 }
 export {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "use-poller",
-  "version": "0.0.1",
-  "description": "Initial placeholder release for the use-poller package name.",
+  "version": "0.1.0",
+  "description": "A tiny React hook for robust polling without request overlap.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,14 +20,24 @@
   ],
   "sideEffects": false,
   "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "size": "size-limit",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
     "react",
     "hook",
     "polling",
-    "use-poller"
+    "use-poller",
+    "interval",
+    "health-check",
+    "retry"
   ],
   "repository": {
     "type": "git",
@@ -43,10 +53,31 @@
     "react": ">=18"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.29.5",
+    "@eslint/js": "^9.32.0",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.9",
+    "@types/react-dom": "^19.1.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.32.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "size-limit": "^11.2.0",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.39.0",
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
-    "access": "public"
-  }
+    "access": "public",
+    "provenance": true
+  },
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "1.5 KB"
+    }
+  ]
 }