@yedoma-labs/ilyn-pages 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yedoma-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# @yedoma-labs/ilyn-pages
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<picture>
+  <source media="(max-width: 640px)" srcset="https://raw.githubusercontent.com/yedoma-labs/assets/main/resized/banner-resized-mobile.png">
+  <img src="https://raw.githubusercontent.com/yedoma-labs/assets/main/resized/banner-resized.png" alt="Project Header">
+</picture>
+
+[![CI](https://github.com/yedoma-labs/ilyn-pages/actions/workflows/ci.yml/badge.svg)](https://github.com/yedoma-labs/ilyn-pages/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@yedoma-labs/ilyn-pages.svg)](https://www.npmjs.com/package/@yedoma-labs/ilyn-pages)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **ilyn** (*ilyn*) — Yakutian (Sakha) for "(noch zu bestätigen)"
+
+Zero-dependency async iteration over every page of a paginated HTTP API, with guards against endless
+cursor loops, skipped or duplicated rows, rate limits in the middle of a run and hanging requests.
+
+Zero runtime dependencies. Uses only `fetch`, `URL`, `AbortController` and `Headers`, so it runs on
+Node.js 20+, Bun and Deno.
+
+## Why
+
+Fetching "all pages" of an API looks trivial and fails in production:
+
+- **Offset pagination** (`?offset=200&limit=100`) skips or repeats rows when data changes between two
+  requests. Rows inserted before the current offset shift everything down by one, and rows deleted
+  shift everything up.
+- **Cursor loops** never end when a server returns the same cursor again.
+- **No page limit** means a misbehaving server can keep a client reading forever.
+- **HTTP 429** in the middle of a loop aborts the whole run unless you handle it per page.
+- **Next links** appear in the body (`{ "next": "..." }`) for some APIs and in the `Link` header
+  (RFC 8288) for others. Each needs its own parsing code.
+- `@octokit/plugin-paginate-rest` solves this for GitHub only.
+
+`ilyn-pages` is the generic layer for the rest.
+
+## Installation
+
+```sh
+pnpm add @yedoma-labs/ilyn-pages
+```
+
+## Quick start
+
+### Next link in the `Link` header
+
+```ts
+import { createFetchPager, paginate } from "@yedoma-labs/ilyn-pages";
+
+interface Item {
+	id: string;
+}
+
+const pager = createFetchPager<Item>({
+	url: "https://api.example.com/items?per_page=100",
+	extract: (body) => (body as { items: Item[] }).items,
+	// The next URL comes from `Link: <...>; rel="next"` by default.
+});
+
+for await (const item of paginate({ fetchPage: pager, maxItems: 10_000 })) {
+	console.log(item.id);
+}
+```
+
+### Next link in the body
+
+```ts
+const pager = createFetchPager<Item>({
+	url: "https://api.example.com/items",
+	extract: (body) => (body as { data: Item[] }).data,
+	nextFromResponse: (_res, body) => (body as { meta: { next: string | null } }).meta.next,
+});
+```
+
+Relative next URLs are resolved against the URL of the current request.
+
+### Opaque cursors with your own `fetchPage`
+
+```ts
+import { paginate, type Page } from "@yedoma-labs/ilyn-pages";
+
+const items = paginate({
+	fetchPage: async (cursor, signal): Promise<Page<Item>> => {
+		const url = new URL("https://api.example.com/items");
+		if (cursor !== undefined) url.searchParams.set("cursor", cursor);
+		const res = await fetch(url, { signal });
+		if (!res.ok) throw new Error(`HTTP ${res.status}`);
+		const body = (await res.json()) as { items: Item[]; nextCursor?: string | null };
+		return { items: body.items, nextCursor: body.nextCursor };
+	},
+});
+```
+
+### Handling errors
+
+```ts
+import { PaginationError } from "@yedoma-labs/ilyn-pages";
+
+try {
+	for await (const item of pages) {
+		// ...
+	}
+} catch (error) {
+	if (error instanceof PaginationError) {
+		switch (error.code) {
+			case "CURSOR_LOOP":
+			case "EMPTY_PAGES_LOOP":
+				// The server is misbehaving. Report it and stop.
+				break;
+			case "PAGE_LIMIT":
+				// The result is larger than maxPages. Raise the limit or narrow the query.
+				break;
+			case "RATE_LIMITED":
+			case "TIMEOUT":
+				// Retry later, the items already yielded are kept by the caller.
+				break;
+			default:
+				throw error;
+		}
+		console.error(`failed on page ${error.page}: ${error.message}`);
+	} else {
+		throw error;
+	}
+}
+```
+
+Items that were yielded before an error are not rolled back. Keep what you need as you go.
+
+## Guards
+
+| Guard | Trigger | Result |
+| --- | --- | --- |
+| Cursor loop | A `nextCursor` was already used in this run | `CURSOR_LOOP` |
+| Empty-page loop | 3 consecutive pages without items that still have a cursor | `EMPTY_PAGES_LOOP` |
+| Page limit | More pages are available after `maxPages` (default 100) | `PAGE_LIMIT` |
+| Item limit | `maxItems` items were yielded | Stops without error |
+| Page timeout | One `fetchPage` call (including `Retry-After` waits) exceeds `timeoutMs` (default 30000) | `TIMEOUT` |
+| Total timeout | The whole iteration exceeds `totalTimeoutMs` (default: none) | `TIMEOUT` |
+| Abort | `signal` is aborted | `ABORTED` |
+| Early exit | `break` in `for await`, or `return()` | Open request signal is aborted |
+| Rate limit | HTTP 429 | Waits for `Retry-After` (seconds or HTTP date, capped at 60 s), retries the page up to 3 times, then `RATE_LIMITED` |
+| Foreign next URL | Next URL has another origin than the start URL | `INVALID_LINK` (unless `allowCrossOriginNext: true`) |
+| Broken `Link` header | Malformed link that mentions `rel="next"` and no valid next link | `INVALID_LINK` |
+
+Guard errors are `PaginationError` instances with a `code` and a `page` number (the page whose request or
+response caused the error). Error messages never contain query values or cursors.
+
+Other errors pass through unchanged: a non-2xx status from `createFetchPager` is a plain `Error`
+(`Request failed with HTTP 500`), a body that is not JSON is a plain `Error` that names the status,
+and errors from the injected `fetch` are rethrown as they are.
+
+## API
+
+### `paginate<T>(options): AsyncGenerator<T>`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `fetchPage(cursor, signal)` | required | Loads one page. `cursor` is `undefined` for the first page. |
+| `maxPages` | `100` | Maximum number of pages. A positive integer or `Infinity`. |
+| `maxItems` | `Infinity` | Stops without error after this many items. |
+| `timeoutMs` | `30000` | Timeout per `fetchPage` call. |
+| `totalTimeoutMs` | `Infinity` | Timeout for the whole iteration. |
+| `signal` | none | Aborts the iteration with `ABORTED`. |
+
+`fetchPage` returns `{ items: T[]; nextCursor?: string | null }`. `undefined`, `null` and `""` all
+mean that there is no next page.
+
+Options are validated when `paginate()` is called and throw a `RangeError` for invalid values.
+Iteration starts with the first `next()`.
+
+### `createFetchPager<T>(options): FetchPage<T>`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `url` | required | URL of the first page. |
+| `extract(body)` | required | Returns the items of the parsed JSON body. |
+| `nextFromResponse(res, body)` | `Link` header | Returns the next URL or `null`. |
+| `fetch` | `globalThis.fetch` | Injected fetch implementation. |
+| `allowCrossOriginNext` | `false` | Allows next URLs on another origin. |
+
+### `parseLinkHeader(value): Record<string, string>`
+
+Parses an RFC 8288 `Link` header. Handles quoted and unquoted `rel`, several relations in one `rel`,
+several links, extra parameters, and URIs that contain commas or semicolons. Relation names are
+lower-cased. The first link wins for duplicate relations. Malformed link values are skipped.
+
+### `nextFromLinkHeader(headers): string | undefined`
+
+Returns the `rel="next"` URI from a `Headers` object. The URI may be relative.
+
+## Offset pagination
+
+Offset pagination is not consistent under concurrent writes. Between two requests, rows inserted
+before the offset shift the window and the same row appears on two pages. Rows deleted before the
+offset cause a row to be skipped. The library cannot detect this, because each page is correct for
+the data at the moment it was read.
+
+Prefer cursor or keyset pagination. Keyset pagination uses the last sort key, for example
+`?after_id=123`, and keeps working when rows change. If the API only offers offsets, sort by a
+stable unique key, accept that the result is a snapshot per page, and compare the total count before
+and after the run.
+
+## Security
+
+The next URL comes from the server and is untrusted. By default, `createFetchPager` follows a next
+URL only when its origin matches the origin of the start URL. A next URL on another host, or on
+`http` for an `https` start URL, raises `INVALID_LINK` and is not requested. This stops a compromised
+or misconfigured server from sending the client to a foreign host, where your tokens could leak.
+Enable `allowCrossOriginNext` only if the API documents cross-origin next links.
+
+Error messages mask query values (`?token=***`). Credentials and fragments are removed from URLs in
+errors.
+
+See [SECURITY.md](SECURITY.md) for the full security model and known limitations.
+
+## Runtime support
+
+Node.js 20+, Bun and Deno. The package is ESM with a CommonJS build. Tests use an injected `fetch`
+and never touch the network.
+
+## Development
+
+```sh
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,409 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/errors.ts
+/**
+* Error raised by the pagination guards.
+*
+* `page` is the 1-based number of the page whose request or response caused the error.
+* Adapters such as `createFetchPager` do not know the page number and use `0`; `paginate()`
+* replaces it with the real number before the error reaches the caller.
+*/
+var PaginationError = class extends Error {
+	code;
+	page;
+	constructor(code, page, message, options) {
+		super(message, options);
+		this.name = "PaginationError";
+		this.code = code;
+		this.page = page;
+	}
+};
+// src/link-header.ts
+const TOKEN_CHAR = /[!#$%&'*+\-.^_`|~0-9A-Za-z]/;
+const NEXT_MENTION = /\brel\s*=\s*"?[^";,]*\bnext\b/i;
+function isTokenChar(ch) {
+	return TOKEN_CHAR.test(ch);
+}
+/**
+* Tokenizer for RFC 8288 Link headers. URI references are read between `<` and `>`, so commas and
+* semicolons inside a URL are not treated as separators. Quoted parameter values support backslash
+* escapes. Malformed link-values are skipped; the scan resumes at the next `<`.
+*/
+function scanLinkHeader(value) {
+	const links = {};
+	let malformedNext = false;
+	const n = value.length;
+	let i = 0;
+	const skipSpaces = () => {
+		while (i < n && (value.charAt(i) === " " || value.charAt(i) === "	")) i += 1;
+	};
+	while (i < n) {
+		skipSpaces();
+		if (i >= n) break;
+		if (value.charAt(i) === ",") {
+			i += 1;
+			continue;
+		}
+		const linkStart = i;
+		let target;
+		if (value.charAt(i) === "<") {
+			const close = value.indexOf(">", i + 1);
+			if (close !== -1) {
+				target = value.slice(i + 1, close).trim();
+				i = close + 1;
+			}
+		}
+		let ok = target !== void 0;
+		const rels = [];
+		while (ok) {
+			skipSpaces();
+			if (i >= n) break;
+			const ch = value.charAt(i);
+			if (ch === ",") {
+				i += 1;
+				break;
+			}
+			if (ch !== ";") {
+				ok = false;
+				break;
+			}
+			i += 1;
+			skipSpaces();
+			const nameStart = i;
+			while (i < n && isTokenChar(value.charAt(i))) i += 1;
+			const name = value.slice(nameStart, i).toLowerCase();
+			if (name === "") {
+				ok = false;
+				break;
+			}
+			skipSpaces();
+			let paramValue;
+			if (value.charAt(i) === "=") {
+				i += 1;
+				skipSpaces();
+				if (value.charAt(i) === "\"") {
+					i += 1;
+					let quoted = "";
+					let closed = false;
+					while (i < n) {
+						const c = value.charAt(i);
+						if (c === "\\" && i + 1 < n) {
+							quoted += value.charAt(i + 1);
+							i += 2;
+							continue;
+						}
+						i += 1;
+						if (c === "\"") {
+							closed = true;
+							break;
+						}
+						quoted += c;
+					}
+					if (!closed) {
+						ok = false;
+						break;
+					}
+					paramValue = quoted;
+				} else {
+					const valueStart = i;
+					while (i < n && isTokenChar(value.charAt(i))) i += 1;
+					if (i === valueStart) {
+						ok = false;
+						break;
+					}
+					paramValue = value.slice(valueStart, i);
+				}
+			}
+			if (name === "rel" && paramValue !== void 0) rels.push(...paramValue.split(/\s+/).filter((rel) => rel !== ""));
+		}
+		if (ok && target !== void 0) for (const rel of rels) {
+			const key = rel.toLowerCase();
+			if (key !== "__proto__" && !Object.hasOwn(links, key)) links[key] = target;
+		}
+		else {
+			malformedNext = malformedNext || NEXT_MENTION.test(value.slice(linkStart));
+			const nextLink = value.indexOf("<", linkStart + 1);
+			i = nextLink === -1 ? n : nextLink;
+		}
+	}
+	return {
+		links,
+		malformedNext
+	};
+}
+/**
+* Parses an RFC 8288 `Link` header value into a map from relation type to URI reference.
+*
+* Handles quoted and unquoted `rel` values, several relation types in one `rel`, several links
+* separated by commas, additional parameters and URIs that contain commas or semicolons.
+* Relation names are lower-cased. For duplicate relations the first link wins. Malformed
+* link-values are ignored.
+*/
+function parseLinkHeader(value) {
+	return scanLinkHeader(value).links;
+}
+/**
+* Returns the URI reference of the `rel="next"` link from a `Link` header, or `undefined`.
+* The URI may be relative; resolve it against the request URL.
+*
+* Throws a `PaginationError` with code `INVALID_LINK` when a malformed link-value mentions
+* `rel="next"` and no valid next link was found. Otherwise a broken header would look like the
+* last page and silently truncate the data.
+*/
+function nextFromLinkHeader(headers) {
+	const raw = headers.get("link");
+	if (raw === null) return;
+	const { links, malformedNext } = scanLinkHeader(raw);
+	if (Object.hasOwn(links, "next")) return links.next;
+	if (malformedNext) throw new PaginationError("INVALID_LINK", 0, "Malformed Link header: rel=\"next\" could not be parsed");
+}
+// src/mask-url.ts
+/**
+* Returns a URL that is safe to put into an error message: credentials are removed, query values
+* are replaced with `***` (keys are kept) and fragments are dropped.
+*/
+function maskUrl(input) {
+	let url;
+	try {
+		url = new URL(input);
+	} catch {
+		return "<invalid URL>";
+	}
+	const origin = url.origin === "null" ? url.protocol : url.origin;
+	const keys = [...new Set(url.searchParams.keys())];
+	const query = keys.length > 0 ? `?${keys.map((key) => `${encodeURIComponent(key)}=***`).join("&")}` : "";
+	return `${origin}${url.pathname}${query}`;
+}
+// src/fetch-pager.ts
+const MAX_RETRIES = 3;
+const DEFAULT_RETRY_AFTER_MS = 1e3;
+const MAX_RETRY_AFTER_MS = 6e4;
+/**
+* Parses the `Retry-After` value (delay in seconds or HTTP date) into milliseconds, capped at
+* 60 seconds. A missing or unparsable value falls back to one second.
+*/
+function retryAfterMs(header, now) {
+	if (header === null) return DEFAULT_RETRY_AFTER_MS;
+	const value = header.trim();
+	let ms;
+	if (/^\d+$/.test(value)) ms = Number(value) * 1e3;
+	else {
+		const date = Date.parse(value);
+		if (Number.isNaN(date)) return DEFAULT_RETRY_AFTER_MS;
+		ms = Math.max(0, date - now);
+	}
+	return Math.min(ms, MAX_RETRY_AFTER_MS);
+}
+/** Waits for `ms`, rejecting with the signal's reason if the signal aborts first. */
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Creates a `fetchPage` function for `paginate()` that follows URL-based cursors.
+*
+* - Next URLs come from the `Link` header (RFC 8288) or from `nextFromResponse`.
+* - Next URLs on a different origin than `url` are rejected with `INVALID_LINK`, unless
+*   `allowCrossOriginNext` is set.
+* - HTTP 429 waits for `Retry-After` (seconds or HTTP date, capped at 60 s) and retries the same
+*   page up to 3 times, then throws `RATE_LIMITED`. The wait counts towards the page timeout.
+* - Other non-2xx responses throw a plain `Error` that contains only the status code.
+*
+* Errors thrown here have `page: 0`; `paginate()` sets the real page number.
+*/
+function createFetchPager(options) {
+	const doFetch = options.fetch ?? globalThis.fetch;
+	if (typeof doFetch !== "function") throw new TypeError("No fetch implementation available; pass options.fetch");
+	const startUrl = new URL(options.url);
+	const startOrigin = startUrl.origin;
+	const allowCrossOrigin = options.allowCrossOriginNext === true;
+	const extract = options.extract;
+	const nextFromResponse = options.nextFromResponse;
+	const resolveNext = (raw, base) => {
+		if (raw === null || raw === void 0 || raw === "") return null;
+		let next;
+		try {
+			next = new URL(raw, base);
+		} catch {
+			throw new PaginationError("INVALID_LINK", 0, "Next link is not a valid URL");
+		}
+		if (!allowCrossOrigin && next.origin !== startOrigin) throw new PaginationError("INVALID_LINK", 0, `Next link points to another origin (${next.origin}) and was not followed. Set allowCrossOriginNext to allow it. Link: ${maskUrl(next.href)}`);
+		return next.href;
+	};
+	return async (cursor, signal) => {
+		const target = cursor === void 0 ? startUrl.href : cursor;
+		let retries = 0;
+		for (;;) {
+			const res = await doFetch(target, { signal });
+			if (res.status === 429) {
+				await res.body?.cancel().catch(() => void 0);
+				if (retries >= MAX_RETRIES) throw new PaginationError("RATE_LIMITED", 0, `Still rate limited (HTTP 429) after ${MAX_RETRIES} retries`);
+				retries += 1;
+				await sleep(retryAfterMs(res.headers.get("retry-after"), Date.now()), signal);
+				continue;
+			}
+			if (!res.ok) throw new Error(`Request failed with HTTP ${res.status}`);
+			let body;
+			try {
+				body = await res.json();
+			} catch (error) {
+				if (error instanceof SyntaxError) throw new Error(`Response of HTTP ${res.status} is not valid JSON`, { cause: error });
+				throw error;
+			}
+			const items = extract(body);
+			if (!Array.isArray(items)) throw new TypeError("extract() must return an array of items");
+			const raw = nextFromResponse ? nextFromResponse(res, body) : nextFromLinkHeader(res.headers);
+			return {
+				items,
+				nextCursor: resolveNext(raw, target)
+			};
+		}
+	};
+}
+// src/paginate.ts
+const DEFAULT_MAX_PAGES = 100;
+const DEFAULT_TIMEOUT_MS = 3e4;
+const MAX_EMPTY_PAGES = 3;
+function resolveLimits(options) {
+	const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+	const maxItems = options.maxItems ?? Number.POSITIVE_INFINITY;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const totalTimeoutMs = options.totalTimeoutMs ?? Number.POSITIVE_INFINITY;
+	if (!(maxPages === Number.POSITIVE_INFINITY || Number.isInteger(maxPages) && maxPages >= 1)) throw new RangeError("maxPages must be a positive integer or Infinity");
+	if (!(maxItems === Number.POSITIVE_INFINITY || Number.isInteger(maxItems) && maxItems >= 0)) throw new RangeError("maxItems must be a non-negative integer or Infinity");
+	if (!(timeoutMs > 0)) throw new RangeError("timeoutMs must be greater than 0");
+	if (!(totalTimeoutMs > 0)) throw new RangeError("totalTimeoutMs must be greater than 0");
+	return {
+		maxPages,
+		maxItems,
+		timeoutMs,
+		totalTimeoutMs
+	};
+}
+/** `undefined`, `null` and `""` mean "no next page". */
+function normalizeCursor(value) {
+	return value === void 0 || value === null || value === "" ? void 0 : value;
+}
+/** Adapters without page context throw with page 0; this fills in the real page number. */
+function withPage(error, page) {
+	if (error instanceof PaginationError && error.page === 0) return new PaginationError(error.code, page, error.message, { cause: error });
+	return error;
+}
+async function* iterate(fetchPage, limits, userSignal) {
+	const run = new AbortController();
+	const inflight = {};
+	const seen = /* @__PURE__ */ new Set();
+	let pageNo = 1;
+	let cursor;
+	let emitted = 0;
+	let emptyStreak = 0;
+	let totalTimer;
+	const onUserAbort = () => {
+		run.abort(new PaginationError("ABORTED", pageNo, "Pagination was aborted", { cause: userSignal?.reason }));
+	};
+	/**
+	* Requests one page. The page signal is aborted when the run is aborted (user signal, total
+	* timeout or iterator return) and after `timeoutMs`. The promise rejects as soon as the signal
+	* fires, even if `fetchPage` ignores the signal.
+	*/
+	const request = (pageCursor, page) => new Promise((resolve, reject) => {
+		if (run.signal.aborted) {
+			reject(run.signal.reason);
+			return;
+		}
+		const ctl = new AbortController();
+		inflight.ctl = ctl;
+		let timer;
+		const onParentAbort = () => ctl.abort(run.signal.reason);
+		const onPageAbort = () => settle(() => reject(ctl.signal.reason));
+		const settle = (done) => {
+			clearTimeout(timer);
+			run.signal.removeEventListener("abort", onParentAbort);
+			ctl.signal.removeEventListener("abort", onPageAbort);
+			done();
+		};
+		run.signal.addEventListener("abort", onParentAbort, { once: true });
+		ctl.signal.addEventListener("abort", onPageAbort, { once: true });
+		if (Number.isFinite(limits.timeoutMs)) timer = setTimeout(() => {
+			ctl.abort(new PaginationError("TIMEOUT", page, `Page ${page} timed out after ${limits.timeoutMs} ms`));
+		}, limits.timeoutMs);
+		let work;
+		try {
+			work = Promise.resolve(fetchPage(pageCursor, ctl.signal));
+		} catch (error) {
+			work = Promise.reject(error);
+		}
+		work.then((result) => settle(() => resolve(result)), (error) => settle(() => reject(withPage(error, page))));
+	});
+	if (userSignal?.aborted) onUserAbort();
+	else userSignal?.addEventListener("abort", onUserAbort, { once: true });
+	if (Number.isFinite(limits.totalTimeoutMs)) totalTimer = setTimeout(() => {
+		run.abort(new PaginationError("TIMEOUT", pageNo, `Total timeout of ${limits.totalTimeoutMs} ms exceeded`));
+	}, limits.totalTimeoutMs);
+	try {
+		while (emitted < limits.maxItems) {
+			if (run.signal.aborted) throw run.signal.reason;
+			const result = await request(cursor, pageNo);
+			if (!Array.isArray(result.items)) throw new TypeError("fetchPage must resolve to an object with an items array");
+			const next = normalizeCursor(result.nextCursor);
+			if (next !== void 0 && seen.has(next)) throw new PaginationError("CURSOR_LOOP", pageNo, `Server returned a cursor that was already used (page ${pageNo}); stopping`);
+			if (result.items.length === 0) {
+				if (next !== void 0) {
+					emptyStreak += 1;
+					if (emptyStreak >= MAX_EMPTY_PAGES) throw new PaginationError("EMPTY_PAGES_LOOP", pageNo, `${MAX_EMPTY_PAGES} consecutive empty pages with a next cursor (page ${pageNo}); stopping`);
+				}
+			} else emptyStreak = 0;
+			for (const item of result.items) {
+				if (run.signal.aborted) throw run.signal.reason;
+				yield item;
+				emitted += 1;
+				if (emitted >= limits.maxItems) return;
+			}
+			if (next === void 0) return;
+			if (pageNo >= limits.maxPages) throw new PaginationError("PAGE_LIMIT", pageNo, `Page limit of ${limits.maxPages} reached while more pages are available`);
+			seen.add(next);
+			cursor = next;
+			pageNo += 1;
+		}
+	} finally {
+		clearTimeout(totalTimer);
+		userSignal?.removeEventListener("abort", onUserAbort);
+		inflight.ctl?.abort();
+		run.abort();
+	}
+}
+/**
+* Iterates over all items of a paginated API.
+*
+* Guards: repeated cursors (`CURSOR_LOOP`), a page limit (`PAGE_LIMIT`), endless empty pages
+* (`EMPTY_PAGES_LOOP`), per-page and total timeouts (`TIMEOUT`) and an abort signal (`ABORTED`).
+* Reaching `maxItems` stops without error.
+*
+* Breaking out of a `for await` loop calls `return()`, which aborts the signal of any request
+* that is still open.
+*
+* Options are validated when `paginate()` is called. Iteration starts on the first `next()`.
+*/
+function paginate(options) {
+	if (typeof options.fetchPage !== "function") throw new TypeError("fetchPage must be a function");
+	return iterate(options.fetchPage, resolveLimits(options), options.signal);
+}
+exports.PaginationError = PaginationError;
+exports.createFetchPager = createFetchPager;
+exports.nextFromLinkHeader = nextFromLinkHeader;
+exports.paginate = paginate;
+exports.parseLinkHeader = parseLinkHeader;
+
+//# sourceMappingURL=index.cjs.map