usePolling

A React hook for implementing polling functionality with configurable intervals, conditions, and callbacks.

Installation

npm install @lonestone/usepolling
# or
yarn add @lonestone/usepolling
# or
pnpm add @lonestone/usepolling

Features

• 🔄 Automatic polling with configurable intervals
• ⏱️ Customizable polling conditions
• 🎯 Success and error callbacks
• ⚡ Immediate or delayed start options
• 🛑 Manual control over polling (start/stop)
• 💪 TypeScript support

Usage

import { usePolling } from '@lonestone/usepolling'

function MyComponent() {
  const { data, error, isLoading, startPolling, stopPolling } = usePolling({
    // Required: Function that returns a Promise
    fetcher: async () => {
      const response = await fetch('https://api.example.com/data')
      return response.json()
    },

    // Optional: Polling interval in milliseconds (default: 5000)
    interval: 3000,

    // Optional: Condition to stop polling (default: () => false)
    condition: (data) => data.status === 'completed',

    // Optional: Success callback
    onSuccess: (data) => {
      console.log('Data received:', data)
    },

    // Optional: Error callback
    onError: (error) => {
      console.error('Polling failed:', error)
    },

    // Optional: Start polling immediately (default: true)
    immediate: true,
  })

  if (isLoading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div>Error: {error.message}</div>
  }

  return (
    <div>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <button onClick={startPolling}>Start Polling</button>
      <button onClick={stopPolling}>Stop Polling</button>
    </div>
  )
}

API Reference

Options

| Option | Type | Required | Default | Description | | ----------- | ------------------------ | -------- | ------------- | -------------------------------------------- | | fetcher | () => Promise<T> | Yes | - | Async function that fetches data | | interval | number | No | 5000 | Polling interval in milliseconds | | condition | (data: T) => boolean | No | () => false | Function to determine when to stop polling | | onSuccess | (data: T) => void | No | - | Callback function called on successful fetch | | onError | (error: Error) => void | No | - | Callback function called on fetch error | | immediate | boolean | No | true | Whether to start polling immediately |

Return Value

| Property | Type | Description | | -------------- | --------------- | ----------------------------------------- | | data | T \| null | The latest data received from the fetcher | | error | Error \| null | Error object if the last fetch failed | | isLoading | boolean | Whether a fetch is in progress | | startPolling | () => void | Function to manually start polling | | stopPolling | () => void | Function to manually stop polling |

License

This project is licensed under the Unlicense.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.