use-poll

Hook de React para ejecutar operaciones de polling de forma controlada hasta que se cumpla una condición de finalización.

Diseñado para entornos de producción donde se prioriza comportamiento predecible, simplicidad y control explícito del flujo.

Instalación

npm install use-poll

Descripción

usePoll permite ejecutar una función asíncrona de forma repetida en intervalos definidos, deteniéndose automáticamente cuando una condición determinada se cumple.

El hook encapsula la gestión del intervalo, el ciclo de vida de las peticiones y la lógica de finalización, garantizando una ejecución segura frente a re-renderizados de React.

Uso

import { usePoll } from "use-poll";

function Example() {
  const { data, isLoading, isCompleted } = usePoll({
    interval: 3000,
    fetcher: async () => {
      const res = await fetch("/api/status");
      if (!res.ok) throw new Error("Request failed");
      return res.json();
    },
    stopCondition: (data) => data.completed === true
  });

  return (
    <div>
      <p>Loading: {String(isLoading)}</p>
      <p>Completed: {String(isCompleted)}</p>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}

API

usePoll(options)

Opciones

• enabled?: boolean Activa o desactiva el polling. Por defecto true.

• interval?: number Intervalo en milisegundos entre ejecuciones. Por defecto 2000.

• fetcher: () => Promise<T> Función asíncrona encargada de obtener los datos.

• stopCondition: (data: T) => boolean Determina cuándo debe detenerse el polling.

• onSuccess?: (data: T) => void Se ejecuta cuando se cumple la condición de finalización.

• onError?: (error: unknown) => void Se ejecuta cuando ocurre un error en la petición.

• initialData?: T Datos iniciales opcionales. Evita el estado de carga inicial y evalúa inmediatamente la condición.

Retorno

• data: T | null Últimos datos obtenidos correctamente.

• isLoading: boolean Indica si hay una petición en curso.

• error: Error | null Último error registrado.

• isCompleted: boolean Indica si el polling ha finalizado.

Comportamiento

• Garantiza una única petición activa en todo momento
• Detiene automáticamente el polling al cumplirse la condición
• Limpia el intervalo al desmontar el componente
• Evita problemas de closures obsoletos mediante referencias internas
• No requiere useCallback ni useMemo por parte del consumidor

Ejemplo con control dinámico

const { data } = usePoll({
  enabled: isActive,
  interval: 1000,
  fetcher: fetchData,
  stopCondition: (data) => data.status === "done"
});

Casos de uso

• Seguimiento de procesos asíncronos
• Consulta periódica de estado en backend
• Espera de consistencia eventual
• Actualización controlada de datos con criterio de finalización

Licencia

MIT