fetch-paginate

library6.1.0jsnpmunverified

A lightweight library for fetching multiple pages from paginated REST APIs using `fetch`. Supports Link headers (e.g., GitHub), page/offset/limit query parameters, and custom pagination logic. Version 6.1.0 is the current stable release. Ships TypeScript types. Provides both promise-based (`fetchPaginate`) and async iterator (`fetchPaginateIterator`) APIs. Isomorphic (works in Node.js with a fetch polyfill and in the browser). Allows custom `fetch` wrappers for caching. Key differentiator: simple, unopinionated, and works with any fetch-compatible environment.

devops

npm install fetch-paginate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-PAGINATE

fetch-paginate

devopsjavascriptv6.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetchPaginate

✓ import { fetchPaginate } from 'fetch-paginate'

✗ import fetchPaginate from 'fetch-paginate'

Named export, not default. ESM only; CommonJS users must use dynamic import or a bundler.

fetchPaginateIterator

✓ import { fetchPaginateIterator } from 'fetch-paginate'

✗ import { fetchPaginateIterator } from 'fetch-paginate/iterator'

Also a named export from the main entry. No separate subpath.

FetchPaginateOptions

✓ import type { FetchPaginateOptions } from 'fetch-paginate'

✗ import { FetchPaginateOptions } from 'fetch-paginate'

Use `import type` for TypeScript types to avoid runtime overhead.

Shows basic usage of fetchPaginate with a GitHub API endpoint, specifying perPage and a getItems function to extract the array from the response body.

import { fetchPaginate } from 'fetch-paginate'; async function getAllItems() { try { const { items, pages, responses } = await fetchPaginate('https://api.github.com/repos/octocat/hello-world/issues', { perPage: 100, getItems: (body) => body, }); console.log(`Fetched ${items.length} items from ${pages.length} pages`); } catch (error) { console.error('Pagination failed:', error); } } getAllItems();

Debug

Known issues

gotchaRequires a `fetch` polyfill in Node.js (e.g., `node-fetch`, `isomorphic-fetch`) — does not bundle one.

fix

Install and import a fetch polyfill: `npm install node-fetch` then `import fetch from 'node-fetch'` before using fetch-paginate.

affects: >=1.0.0

gotchaThe `items` array may include duplicates if the server returns overlapping pages. No deduplication built-in.

fix

Implement a deduplication function and pass it as the `merge` option, or process items after fetch.

affects: >=1.0.0

breakingVersion 5.x dropped support for CommonJS `require()`. The package is ESM-only since v5.

fix

Use `import` syntax or use dynamic `import('fetch-paginate')`. If you must use `require`, stay on v4.x.

affects: >=5.0.0

deprecatedThe `page` option may be deprecated in future versions in favor of `offset`/`limit` style pagination. Check the docs for deprecation notices.

fix

Prefer `offset` and `limit` options if your API supports them; fallback to `page` is still functional.

affects: >=6.0.0

gotchaThe `getFetch` option expects a factory that returns a function, not a fetch function directly. Many users mistakenly pass `fetch` itself.

fix

Wrap fetch in a function: `getFetch: () => async (url, init) => fetch(url, init)` or return a cached response.

affects: >=6.0.0

Errors

Common errors & fixes

Cannot find module 'fetch-paginate' or its corresponding type declarations.

Missing `node_modules` or TypeScript not configured to resolve ESM packages.

fix

Ensure `fetch-paginate` is installed (`npm install fetch-paginate`). For TypeScript, set `moduleResolution` to `node16`, `nodenext`, or `bundler` in tsconfig.json.

TypeError: fetch is not a function

Running in Node.js without a fetch polyfill.

fix

Install `node-fetch` and import/require it before using fetch-paginate, or use Node.js 18+ (which has global fetch).

The requested module 'fetch-paginate' does not provide an export named 'default'

Using default import instead of named import.

fix

Change `import fetchPaginate from 'fetch-paginate'` to `import { fetchPaginate } from 'fetch-paginate'`.

TypeScript: 'fetchPaginate' cannot be used as a value because it was imported using 'import type'

Using `import type` for a runtime value.

fix

Remove `type` from the import: `import { fetchPaginate } from 'fetch-paginate'`.

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/AndersDJohnson/fetch-paginate ↗

packagefetch-paginate ↗

homepagehttps://github.com/AndersDJohnson/fetch-paginate#readme ↗