diff --git a/.changeset/phase6c-pagination.md b/.changeset/phase6c-pagination.md new file mode 100644 index 0000000..984a996 --- /dev/null +++ b/.changeset/phase6c-pagination.md @@ -0,0 +1,6 @@ +--- +'@dexpace/core': minor +--- + +Add pagination support: `Paginator` (items and pages views), `Page` with `AsyncDisposable` support, built-in strategies (`cursorStrategy`, `pageNumberStrategy`, `linkHeaderStrategy`), and `paginateWithFetchers`. Note: TypeScript consumers utilizing Explicit Resource Management (`await using`) against `Page` should ensure `"ESNext.Disposable"` (or `esnext`) is included in their compiler `lib`. + diff --git a/docs/knowledge/pagination.md b/docs/knowledge/pagination.md index d954388..4311f3c 100644 --- a/docs/knowledge/pagination.md +++ b/docs/knowledge/pagination.md @@ -81,7 +81,7 @@ design · `docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md:7-10` · high · sha:d546f9973c4e - Close-on-abandon for pagination relies on JavaScript's iterator protocol automatically calling `.return()` on an async iterator when a `for await...of` loop exits early via break, return, or exception, resuming execution at the enclosing `finally` block, unlike Kotlin's `Iterator`/`Sequence` protocol which has no built-in early-termination cleanup hook and requires a bespoke `CloseablePages` wrapper. design · `docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md:12-19` · high · sha:d546f9973c4e -- The page-level view's two-outstanding-pages buffering requirement is implemented as a one-slot look-ahead buffer held in the generator's own closure, released via the same `finally` mechanism. +- The page-level view holds the currently delivered page in the generator's `held` binding, releasing it upon advancing before dispatching the next request and releasing the last held page at exhaustion or early termination via the enclosing `finally` block. design · `docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md:32-34` · high · sha:d546f9973c4e - The port rejects `URLSearchParams` for verbatim query-parameter splicing because it re-serializes the entire query string through its own canonical encoding on every mutation, reordering and re-encoding untouched parameters and encoding space as `+` rather than the RFC 3986 `%20` the port's query model otherwise standardizes on. design · `docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md:36-41` · high · sha:d546f9973c4e diff --git a/docs/open-items.md b/docs/open-items.md index 2ca2430..d553a22 100644 --- a/docs/open-items.md +++ b/docs/open-items.md @@ -1049,6 +1049,63 @@ value equality (`hashCode`); value equality is provided via `sseEventsEqual()` ( --- +## Section J — Phase 6c (Pagination) + +Recorded at implementation and review time. Everything here is either an intentional design clarification, a requirement clause satisfied with documented deviation/erratum, or an accepted runtime consideration. + +### J1 — `PAGE-11` close-before-yield precedence over §7.1 illustrative snippet — **RESOLVED WITH ERRATUM** + +`sdk-design-nodejs/07-pagination-sse-and-serialization.md` §7.1 shows an illustrative generator snippet with `try { yield* page.items } finally { await page.close() }`. +`PAGE-11` (MUST) mandates closing *before* yielding any items on the page (`const items = page.items; await page.close(); yield* items;`). Materialized items survive close (`PAGE-2`), so closing before yielding releases the underlying response immediately and ensures an abandoned item iteration cannot strand an open response connection. +An erratum callout was added to `07-pagination-sse-and-serialization.md` §7.1 and documented in the Deferred Items Log. + +**Trigger:** none. + +### J2 — `PAGE-5` / `PAGE-29` asynchronous `PaginationStrategy.parse` signature — **RESOLVED WITH SPEC CLARIFICATION** + +`PAGE-5` describes `parse` as reading what it needs "synchronously inside parse". In Node.js / Web Standards HTTP domain models, response bodies arrive as asynchronous streams (`ReadableStream`), making synchronous stream consumption impossible without prior full buffering. +`PaginationStrategy.parse` returns `Promise>`, fulfilling all intended semantics of `PAGE-5` and `PAGE-29` (isolated, non-mutating parse) while maintaining compatibility with async body decoders. + +**Trigger:** none. + +### J3 — `Page` implements `AsyncDisposable` with `Symbol.asyncDispose` — **RESOLVED** + +`Page` implements `AsyncDisposable` unconditionally (`[Symbol.asyncDispose](): Promise`), delegating to `close()`. Consumers utilizing Explicit Resource Management (`await using`) against `Page` must include `"ESNext.Disposable"` in their compiler `lib`. + +**Trigger:** none. + +### J4 — WHATWG encode-set boundary & verbatim query splice (PAGE-21, PAGE-22) — **RESOLVED BY DESIGN** + +`URLSearchParams` re-serializes full query strings, reorders parameters, and encodes space as `+` rather than RFC 3986 `%20`. `query-splice.ts` implements hand-rolled tokenization operating directly on the raw query substring, preserving untargeted parameters byte-for-byte. + +**Trigger:** none. + +### J5 — Transport-direct pagination without internal resilience loop — **RESOLVED BY DESIGN** + +`Paginator` operates directly over `Transport` and `Request`. Resilience (retry, redirect, auth) is composed externally at the pipeline / `Runtime` layer (`PIPE-9`), keeping the pagination engine modular and transport-agnostic (§12). + +**Trigger:** none. + +### J6 — `items()` vs `pages()` single-use asymmetry (PAGE-8, PAGE-14) — **RESOLVED BY DESIGN** + +`Paginator.items()` allows multiple independent iterations because each iteration starts a fresh walk and closes each page before yielding. `Paginator.pages()` is single-use because yielded `Page` objects hold live connection ownership, where re-iteration would cause double-consumption of unclosed resources. + +**Trigger:** none. + +### J7 — Iterative generator drive without trampoline (PAGE-31) — **RESOLVED BY DESIGN** + +`PAGE-31` sanctions native loop models without recursion. `Paginator.#walk` and `driveFetchers` are implemented as `async function*` generator loops, guaranteeing constant stack space across thousands of pages without explicit trampoline structures. + +**Trigger:** none. + +### J8 — Error unwrapping and root cause propagation (PAGE-28) — **RESOLVED BY DESIGN** + +`PaginationError` is reserved strictly for engine misuse and precondition violations (`maxPages <= 0`, single-use iterator re-use). Transport, parse, and network failures propagate unwrapped with original causes preserved. + +**Trigger:** none. + +--- + ## Maintaining this file Add an entry the moment a gap is found, not when it is fixed — the failure mode this file prevents is a diff --git a/docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md b/docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md index df0fb6a..7fd7b41 100644 --- a/docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md +++ b/docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md @@ -27,6 +27,10 @@ async function* items(): AsyncGenerator { } ``` +> [!NOTE] +> **Erratum on close ordering (PAGE-11 vs illustrative snippet):** The snippet above illustrates JavaScript's automatic `.return()`-on-abandon via `finally`, but closes *after* yielding items. **PAGE-11** (MUST) mandates closing *before* yielding any items on the page (`const items = page.items; await page.close(); yield* items;`). Materialized items survive close (**PAGE-2**), so closing before yielding releases the underlying response immediately and ensures an abandoned item iteration cannot strand an open response. + + and an early `break` out of the consumer's `for await` loop drives the `finally` — and therefore `page.close()` — automatically, with no wrapper type and no documented "must remember to close" convention required from callers. The page-level view's two-outstanding-pages buffering (**PAGE-12**: a `hasNext()` probe eagerly runs the next diff --git a/docs/superpowers/plans/2026-07-28-phase6c-pagination-checklist.md b/docs/superpowers/plans/2026-07-28-phase6c-pagination-checklist.md new file mode 100644 index 0000000..498efa8 --- /dev/null +++ b/docs/superpowers/plans/2026-07-28-phase6c-pagination-checklist.md @@ -0,0 +1,85 @@ +# Phase 6c — Pagination Implementation Plan — Checklist + +Verification of pagination requirements (`PAGE-1`–`PAGE-36`) from `docs/product-spec/16-pagination.md` and `docs/sdk-design-nodejs/07-pagination-sse-and-serialization.md`, as dispositioned by `docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md`. + +**Status: EXECUTED (2026-08-27).** All tasks implemented, tested, and reviewed. Deviations and design ledger rows are recorded in `docs/open-items.md` §I. + +**Legend:** ✅ Implemented and tested — ✅(t) Satisfied by construction or type test — 🚫 Not built — ⏳ Deferred — N/A Not applicable. + +--- + +## §16.1 — Core Data Model & Strategy Contract (`PAGE-1`–`PAGE-5`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-1 | MUST | Items and pages views over one walk, server order preserved across page boundaries | ✅ | `Page`, `Paginator` in `packages/core/src/pagination/page.ts`, `paginator.ts`, tested in `paginator.test.ts` | +| PAGE-2 | MUST | Materialized items frozen, survive close; items never null | ✅ | `packages/core/src/pagination/page.ts`, tested in `page.test.ts` | +| PAGE-3 | MUST | Exactly one owned response per page; idempotent close delegates to `Response.close()` | ✅ | `packages/core/src/pagination/page.ts`, `Page.close()`, `Page[Symbol.asyncDispose]()`, tested in `page.test.ts` | +| PAGE-4 | MUST | `PageInfo` carries items + nextRequest; `undefined` signals end of stream | ✅ | `packages/core/src/pagination/page.ts` (`pageInfo`), tested in `page.test.ts` | +| PAGE-5 | MUST | `PaginationStrategy.parse` contract returning `Promise>` | ✅ | `packages/core/src/pagination/strategy.ts`, tested in `strategy.test.ts` (ledger row I2) | + +--- + +## §16.2 — Paginator Lifecycle & Consumption Views (`PAGE-6`–`PAGE-15`, `PAGE-27`, `PAGE-31`–`PAGE-33`, `PAGE-36`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-6 | MUST | Page-lazy: zero wire exchanges before first probe | ✅ | `Paginator.#walk`, tested in `paginator.test.ts` | +| PAGE-7 | MUST | Forward-only walk, idempotent end probes | ✅ | `Paginator.#walk`, tested in `paginator.test.ts` | +| PAGE-8 | MUST | Independent iterations over item-level view (`items()`) | ✅ | `Paginator.items()`, tested in `paginator.test.ts` | +| PAGE-9 | MUST | `maxPages` cap: positive integer at construction, stops walk | ✅ | `Paginator`, `paginateWithFetchers`, tested in `paginator.test.ts`, `fetchers.test.ts` | +| PAGE-10 | MUST | Capped walk delivers exactly capped count even when strategy supplies nextRequest | ✅ | `Paginator.#walk`, tested in `paginator.test.ts` | +| PAGE-11 | MUST | Close response BEFORE yielding items on `items()` view | ✅ | `Paginator.items()`, tested in `lifecycle.test.ts` (ledger row I1) | +| PAGE-12 | MUST | Auto-close on abandon / break / exhaustion, scoped construct (`await using`) support | ✅ | `Page[Symbol.asyncDispose]`, `Paginator.#walk`, tested in `page.test.ts`, `lifecycle.test.ts` | +| PAGE-13 | MUST | Parse failure closes inline, close error suppressed | ✅ | `parseOrClose` in `paginator.ts`, tested in `lifecycle.test.ts` | +| PAGE-14 | MUST | Page-level view (`pages()`) is single-use; subsequent iterator throws | ✅ | `Paginator.pages()`, `paginateWithFetchers`, tested in `lifecycle.test.ts`, `fetchers.test.ts` | +| PAGE-15 | MUST | Close errors surface when walk or release fails | ✅ | `releaseHeldOnFailure`, `suppress()`, tested in `lifecycle.test.ts`, `fetchers.test.ts` | +| PAGE-27 | MUST | Every response closed exactly once (no double-close, no leak) | ✅ | `lifecycle.test.ts` (`test.each`), `test/node-conformance/pagination.test.mjs` | +| PAGE-28 | MUST | Underlying causes propagated unwrapped | ✅ | `lifecycle.test.ts`, `errors.test.ts` | +| PAGE-29 | MUST | Async parse boundary (`Promise>`) | ✅(t) | `strategy.ts`, `strategy.test.ts` | +| PAGE-30 | MUST | Synchronous item array within page | ✅(t) | `page.ts`, `strategy.test.ts` | +| PAGE-31 | MUST | Stack safety across thousands of pages (iterative generator drive) | ✅ | `cancellation.test.ts` (5000 pages test) | +| PAGE-32 | MUST | Consumer throw discards return-phase close error, keeping consumer error primary | ✅ | `Paginator.#walk` finally, tested in `lifecycle.test.ts` | +| PAGE-33 | MUST | Race between abort and arrival drops and closes response | ✅ | `Paginator.#walk`, tested in `cancellation.test.ts` | +| PAGE-36 | MUST | Per-operation RequestOptions passed to every page exchange | ✅ | `Paginator.#walk`, tested in `paginator.test.ts` | + +--- + +## §16.3 — Built-in Strategies & Parsing (`PAGE-16`–`PAGE-20`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-16 | MUST | Built-in cursor strategy (single body read, null/empty/undefined ends) | ✅ | `packages/core/src/pagination/strategies.ts` (`cursorStrategy`), tested in `strategies.test.ts` | +| PAGE-17 | MUST | Built-in page number strategy (empty items ends, start page fallback) | ✅ | `packages/core/src/pagination/strategies.ts` (`pageNumberStrategy`), tested in `strategies.test.ts` | +| PAGE-18 | MUST | Built-in link header strategy (RFC 8288, case-insensitive `rel="next"`) | ✅ | `packages/core/src/pagination/strategies.ts`, `link-header.ts`, tested in `strategies.test.ts`, `link-header.test.ts` | +| PAGE-19 | MUST | Unresolvable Link header URL throws | ✅ | `packages/core/src/pagination/strategies.ts`, tested in `strategies.test.ts` | +| PAGE-20 | MUST | Multiple Link headers parsed and combined | ✅ | `packages/core/src/pagination/link-header.ts`, tested in `link-header.test.ts`, `strategies.test.ts` | + +--- + +## §16.4 — Verbatim Query Splicing (`PAGE-21`–`PAGE-24`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-21 | MUST | Verbatim query splice without URLSearchParams; untargeted params preserved byte-for-byte | ✅ | `packages/core/src/pagination/query-splice.ts`, tested in `query-splice.test.ts`, `query-splice.property.test.ts` | +| PAGE-22 | MUST | RFC 3986 percent-encoding in query components (`+` is data, not space) | ✅ | `packages/core/src/http/query-params.ts`, `query-splice.ts`, tested in `query-splice.test.ts` | +| PAGE-23 | MUST | Replace-first, append, remove query parameter maintaining order | ✅ | `packages/core/src/pagination/query-splice.ts`, tested in `query-splice.test.ts`, `query-splice.property.test.ts` | +| PAGE-24 | MUST | Non-query URL components preserved verbatim | ✅ | `packages/core/src/pagination/query-splice.ts`, tested in `query-splice.test.ts` | + +--- + +## §16.5 — Cancellation Integration (`PAGE-25`–`PAGE-26`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-25 | MUST | AbortSignal threaded into every exchange | ✅ | `Paginator.#walk`, tested in `cancellation.test.ts`, `test/node-conformance/pagination.test.mjs` | +| PAGE-26 | MUST | Page-granular cancellation (abort stops walk, in-flight response closed and dropped) | ✅ | `Paginator.#walk`, tested in `cancellation.test.ts`, `test/node-conformance/pagination.test.mjs` | + +--- + +## §16.6 — Fetcher-Based Front-End (`PAGE-34`–`PAGE-35`) + +| ID | Level | Requirement gist | Status | Where | +|---|---|---|---|---| +| PAGE-34 | MUST | Fetcher pagination (`first` once, `next` keys off link/token, returns `Page`) | ✅ | `packages/core/src/pagination/fetchers.ts` (`paginateWithFetchers`), tested in `fetchers.test.ts` | +| PAGE-35 | MUST | Mutable shared options bag threaded across fetcher calls | ✅ | `packages/core/src/pagination/fetchers.ts` (`PagingOptions`), tested in `fetchers.test.ts` | diff --git a/docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md b/docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md index 815ed76..60e2f4f 100644 --- a/docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md +++ b/docs/superpowers/specs/2026-07-23-nodejs-sdk-v1-roadmap-design.md @@ -152,8 +152,8 @@ permanent simplification, not a postponement. | Phase 6 split into 6a (Serde, `§14`) / 6b (SSE, `§13`) / 6c (Pagination, `§12`) | Phase 6 brainstorm (2026-07-28) | — | 107 combined normative IDs (`PAGE` 36, `SSE` 41, `SERDE` 30), between the ~76–79 that forced the Phase 3 and Phase 4 splits and Phase 5's 111. Cut along the spec's own section boundaries because **the spec forbids the couplings that would cross them**: `SSE-37` (MUST) bars any serde dependency from core SSE, and `§12`'s preamble declares pagination serde-agnostic — so the cross-segment contract surface is empty by mandate, which is exactly the property whose absence caused the 5b/5c drift below. **No segment depends on another; the 6a→6b→6c order is convenience, not dependency**, and any sub-phase may execute out of order. 6a leads only because it scaffolds the workspace's second package and is the one segment that reshapes an already-published seam (`SEAM-21`); 6c trails because it is the most coupled to *earlier* phases (4c's `Runtime`, 5a's `StepContext.options`, 3b's `Response` body). Full rationale, per-segment ownership, and the collapsed-ID clusters in the [Phase 6 segmentation design](./2026-07-28-phase6-segmentation-design.md) | | Collapsed-requirement disposition tables for Phase 6 — `PAGE-25`–`PAGE-33` (§12.9's async engine: this port has one async model, so the async generator *is* the engine), `SSE-18`/`SSE-31` (threading re-expressed against the event loop), `SERDE-8`/`SERDE-21`/`SERDE-22`/`SERDE-25`/`SERDE-26` (codec-engine configuration with no configurable engine to configure) | Phase 6 brainstorm | Each owning sub-phase's design (6c, **Resolved for 6b in Phase 6b design**, 6a) | Same service 5a's `RECOV-17`–`RECOV-34` table performs: without a row-by-row disposition, a naive appendix-B sweep reads ~18 collapsed requirements as uncovered. The segmentation design identifies the clusters and what does **not** collapse inside each — notably `PAGE-26`/`PAGE-27`/`PAGE-32`'s close-exactly-once obligations (re-expressed as `finally`-block obligations on the single generator), `SSE-18` re-expressed against the event loop, and `SSE-31`'s close-during-in-flight-read branch (re-expressed and tested, **not** collapsed), both documented in the [Phase 6b design](./2026-07-28-phase6b-sse-design.md). **Note (Phase 9 design, 2026-07-28):** Phase 9's actual design scopes to `§19`/`§20` (`XCUT`/`NFR`) only — it does not re-verify `PAGE`/`SSE`/`SERDE` disposition, which stays each owning sub-phase's own responsibility as this row already states (6c, 6b, 6a respectively) | | 3a's `readUtf8Line()` is unusable for SSE (`IO-14` keeps a lone `\r` as content, `SSE-2` requires it to terminate) | Phase 6b | **Resolved in Phase 6b** — closed 2026-08-27 | 6b owns `src/sse/line-reader.ts` instead of reshaping a frozen Phase 3a surface. Recorded so Phase 10's deviation review does not read the duplication as accidental | -| `sdk-design-nodejs/07` §7.1's item-view snippet closes the page *after* yielding its items; `PAGE-11` (MUST) requires closing *before* | Phase 6 brainstorm | **Phase 6c** (erratum against `sdk-design-nodejs/07` **and** `docs/knowledge/pagination.md`) | The 2026-07-28 plans review found the erratum was being written into `sdk-design-nodejs/07` only, while `docs/knowledge/pagination.md` carries the *same* wrong ordering in its Reference section directly beside the correct MUST in its Rules section. The knowledge corpus is the standing tie-breaker every later phase consults, so an erratum that skips it leaves the contradiction live; 6c's plan now amends both. Recorded because **the conformance test is weaker than the requirement**: the snippet's `finally` still passes `PAGE-11`'s stated check (an early `break` drives `.return()`, hence the close), so following the design doc ships a violation the appendix-B checklist would not catch. Resolution per the standing tie-breaker (normative spec + knowledge corpus win over an illustrative snippet): `PAGE-11` governs — copy items, close, *then* yield. Costs nothing, since materialized items survive close per `PAGE-2`. The snippet remains correct about the thing §7.1 is actually arguing (JavaScript's automatic `.return()`-on-abandon), just not about close ordering | -| `PAGE-5`'s "strategy MUST read everything it needs from the response **synchronously** inside parse" | Phase 6 brainstorm | **Phase 6c** (design must state the re-expression) | Node has no synchronous body read, so the literal reading is unimplementable and `parse` returns a promise. Every part of the requirement's actual intent survives: single-use-body discipline, no retention of the response or its body past the call, no close, no mutation. Flagged so an async signature does not later read as an oversight or get "fixed" back toward a literal reading | +| `sdk-design-nodejs/07` §7.1's item-view snippet closes the page *after* yielding its items; `PAGE-11` (MUST) requires closing *before* | Phase 6 brainstorm | **Resolved in Phase 6c** — closed 2026-08-27 | The 2026-07-28 plans review found the erratum was being written into `sdk-design-nodejs/07` only, while `docs/knowledge/pagination.md` carries the *same* wrong ordering in its Reference section directly beside the correct MUST in its Rules section. The knowledge corpus is the standing tie-breaker every later phase consults, so an erratum that skips it leaves the contradiction live; 6c amends both. Resolution per the standing tie-breaker (normative spec + knowledge corpus win over an illustrative snippet): `PAGE-11` governs — copy items, close, *then* yield. Costs nothing, since materialized items survive close per `PAGE-2`. The snippet remains correct about the thing §7.1 is actually arguing (JavaScript's automatic `.return()`-on-abandon), just not about close ordering. **Closed in Phase 6c.** | +| `PAGE-5`'s "strategy MUST read everything it needs from the response **synchronously** inside parse" | Phase 6 brainstorm | **Resolved in Phase 6c** — closed 2026-08-27 | Node has no synchronous body read, so the literal reading is unimplementable and `parse` returns a promise. Every part of the requirement's actual intent survives: single-use-body discipline, no retention of the response or its body past the call, no close, no mutation. Flagged so an async signature does not later read as an oversight or get "fixed" back toward a literal reading. **Closed in Phase 6c.** | | `SSE-41` — reactive SSE adapter (backpressure-honoring `Observable` view, fatal/non-fatal split, source-ownership documentation) | Phase 6 brainstorm | **Phase 8b** (`@dexpace/rx`) | `MAY`. 6b ships the pull-based `AsyncGenerator` surface `SSE-39` mandates; the reactive view is a bridge package, and the roadmap scopes `§18`'s async-runtime adapters to 8b specifically (not 8a's transports) as of the 2026-07-28 [Phase 8 segmentation design](./2026-07-28-phase8-segmentation-design.md). `sdk-design-nodejs/02` identifies RxJS's push-based `Observable` as the one async shape in the Node ecosystem worth bridging at all. Is `ASYNC-21` restated — the segmentation design's §5.2 names it 8b's marquee deliverable | | Appendix C `RECOV-17`–`RECOV-34` reconciliation (18 rows filed under "Recovery-chain pipeline primitives" that `§8.2`'s prose never defines — it stops at `RECOV-16`) | Phase 4 sizing review | **Resolved in Phase 5a** | They are retry-engine requirements stated a second time for the reference's second retry stack. Since this port collapses both stacks into one engine (`RETRY-28`, `sdk-design/06`), 16 of the 18 collapse onto the same implementation as their `§9` twin (e.g. `RECOV-21` restates `RETRY-9`/`10`/`11`'s backoff formula verbatim); `RECOV-34`'s settings-object validation is partially new; `RECOV-32` and `RECOV-33` have **no** `§9` twin and are genuinely new work. The full row-by-row mapping table lives in the [Phase 5a design](./2026-07-26-phase5a-retry-design.md) — a naive appendix-B sweep should read it rather than re-deriving it, or it will read 18 requirements as uncovered. **Note (Phase 9 design, 2026-07-28):** `RECOV-*` is outside Phase 9's actual `XCUT`/`NFR`-scoped design; its disposition stays 5a's own responsibility per the table this row already points to | | Real W3C Trace Context generation (trace-id/span-id byte generation, hex encoding, `traceparent`/`tracestate` parsing) — `InstrumentationBundle`'s actual tracing backend | Phase 4a | **Resolved in Phase 7b (design)** | 4a ships only `CTX-14`'s bundle shape and `CTX-15`'s no-op default. 7b's design generates real W3C/Datadog/no-op trace and span ids via `globalThis.crypto.getRandomValues` and lets a caller-supplied `tracerFactory` flow into `InstrumentationBundle` at pipeline-build time, without changing its already-frozen shape. Lands when 7b's plan executes | diff --git a/packages/core/etc/core.api.md b/packages/core/etc/core.api.md index 73cc9cc..123a988 100644 --- a/packages/core/etc/core.api.md +++ b/packages/core/etc/core.api.md @@ -1,976 +1,1069 @@ -## API Report File for "@dexpace/core" - -> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). - -```ts - -// @public -export function absent(): Tristate; - -// @public -export class ApiKeyCredential { - [INSPECT](): string; - constructor(key: string); - toString(): string; -} - -// @public -export interface ApiKeyCredentialConfig { - readonly credential: ApiKeyCredential | NameKeyCredential; - readonly headerName?: string | undefined; - readonly prefix?: string | undefined; -} - -// @public -export interface AuthCredentialSet { - readonly apiKey?: ApiKeyCredentialConfig | undefined; - readonly basic?: BasicCredential | undefined; - readonly bearer?: BearerCredential | undefined; - readonly digest?: DigestCredential | undefined; -} - -// @public -export interface AuthDescriptor { - readonly allowsAnonymous: boolean; - readonly requirements: readonly AuthRequirement[]; -} - -// @public -export interface AuthRequirement { - readonly params: ReadonlyMap; - readonly scheme: AuthScheme; - readonly scopes: readonly string[]; -} - -// @public -export function authRequirementsEqual(a: AuthRequirement, b: AuthRequirement): boolean; - -// @public -export class AuthResolutionError extends DexpaceError { - constructor(message: string, requiredSchemes?: readonly string[], availableSchemes?: readonly string[]); - readonly availableSchemes: readonly string[] | undefined; - readonly requiredSchemes: readonly string[] | undefined; - static unsatisfiable(requiredSchemes: readonly string[], availableSchemes: readonly string[]): AuthResolutionError; -} - -// @public -export type AuthScheme = 'OAUTH2' | 'API_KEY' | 'BASIC' | 'DIGEST' | 'NO_AUTH'; - -// @public -export function authStep(settings: AuthStepSettings): StepDescriptor; - -// @public -export interface AuthStepSettings { - readonly bearerMarginMs?: number | undefined; - readonly challengeHook?: ChallengeHook | undefined; - readonly clock?: Pick | undefined; - readonly credentials: AuthCredentialSet; - readonly tiers: AuthTiers; -} - -// @public -export interface AuthTiers { - readonly client?: AuthDescriptor | undefined; - readonly operation?: AuthDescriptor | undefined; - readonly perCall?: AuthDescriptor | undefined; -} - -// @public -export interface BackoffSettings { - readonly fixedDelayMs?: number | undefined; - readonly initialDelayMs: number; - readonly jitter: number; - readonly maxDelayMs: number; - readonly multiplier: number; -} - -// @public -export interface BasicCredential { - readonly password: string; - readonly username: string; -} - -// @public -export interface BearerCredential { - readonly marginMs?: number | undefined; - readonly provider: TokenProvider; -} - -// @public -export class BearerToken { - [INSPECT](): string; - readonly expiresAt: number | undefined; - get token(): string; - toString(): string; -} - -// @public -export function bearerTokensEqual(a: BearerToken, b: BearerToken): boolean; - -// @public -interface Body_2 { - readonly contentLength: number; - readonly kind: 'byte-array' | 'string' | 'stream' | 'form-urlencoded' | 'multipart'; - readonly mediaType: string | undefined; - readonly replayable: boolean; - writeTo(sink: WritableStream): Promise; -} -export { Body_2 as Body } - -// @public -export interface Builder { - build(): T; -} - -// @public -export function buildRequest(baseUrl: string | URL, operation: OperationDescriptor): Request_2; - -// @public -export class ByteArrayBody implements Body_2 { - constructor(bytes: Uint8Array, mediaType?: string); - readonly contentLength: number; - readonly kind: "byte-array"; - readonly mediaType: string | undefined; - readonly replayable = true; - writeTo(sink: WritableStream): Promise; -} - -// @public -export function byteArrayBody(bytes: Uint8Array, mediaType?: string): ByteArrayBody; - -// @public -export class CancellationError extends DexpaceError { - constructor(message: string, options?: ErrorOptions); -} - -// @public -export type ChallengeHook = (response: Response_2, request: Request_2, options?: { - readonly signal?: AbortSignal | undefined; -}) => Promise; - -// @public -export interface Clock { - monotonic(): number; - now(): number; - sleep(ms: number, signal?: AbortSignal): Promise; -} - -// @public -export function composeSignal(userSignal?: AbortSignal, timeoutMs?: number): AbortSignal | undefined; - -// @public -export class ConsumedBodyError extends DexpaceError { - constructor(bodyKind: string, options?: ErrorOptions); - readonly bodyKind: string; -} - -// @public -export function createAuthDescriptor(requirements: readonly AuthRequirement[]): AuthDescriptor; - -// @public -export function createAuthRequirement(scheme: AuthScheme, scopes?: readonly string[], params?: ReadonlyMap): AuthRequirement; - -// @public -export function createBearerToken(token: string, expiresAt?: number): BearerToken; - -// @public -export function decodeResponse(response: Response_2, deserializer: Deserializer, target: DecodeTarget): Promise; - -// @public -export function decodeSuccessResponse(response: Response_2, deserializer: Deserializer, target: DecodeTarget): Promise; - -// @public -export interface DecodeTarget { - readonly schema: Schema; - readonly typeName?: string | undefined; -} - -// @public -export class DeserializationError extends DexpaceError { - constructor(message: string, options?: DeserializationErrorOptions); - readonly etag: string | null; - readonly location: string | null; - readonly status: number | undefined; -} - -// @public -export interface DeserializationErrorOptions extends SerdeErrorOptions { - readonly etag?: string | null | undefined; - readonly location?: string | null | undefined; - readonly status?: number | undefined; -} - -// @public -export interface Deserializer { - deserialize(data: Uint8Array, schema: Schema, typeName?: string): T; - deserializeFrom(source: ReadableStream, schema: Schema, typeName?: string): Promise; -} - -// @public -export class DexpaceError extends Error { - constructor(message: string, options?: ErrorOptions); -} - -// @public -export type DigestAlgorithm = 'MD5' | 'MD5-sess' | 'SHA-256' | 'SHA-256-sess'; - -// @public -export interface DigestCredential { - readonly algorithmPreference?: readonly DigestAlgorithm[] | undefined; - readonly password: string; - readonly username: string; -} - -// @public -export interface DispatchContext { - readonly instrumentation: InstrumentationBundle; - readonly key: symbol; - readonly kind: 'dispatch'; -} - -// @public -export class DomainModelError extends DexpaceError { -} - -// @public -export class ETag { - static readonly ANY: ETag; - get isAny(): boolean; - get isWeak(): boolean; - get opaque(): string | undefined; - static parse(raw: string): ETag | undefined; - get raw(): string; -} - -// @public -export class EtagParseError extends DomainModelError { -} - -// @public -export interface ExchangeContext { - readonly instrumentation: InstrumentationBundle; - readonly key: symbol; - readonly kind: 'exchange'; - readonly operationName: string | undefined; - readonly request: Request_2; - readonly response: Response_2; -} - -// @public -export type ExecutionContext = DispatchContext | RequestContext | ExchangeContext; - -// @public -export function foldTristate(tristate: Tristate, branches: TristateBranches): R; - -// @public -export class FormBodyValidationError extends DexpaceError { - constructor(field: string, value: unknown, options?: ErrorOptions); - readonly field: string; -} - -// @public -export class FormUrlEncodedBody implements Body_2 { - constructor(input: FormUrlEncodedInput); - readonly contentLength: number; - readonly kind: "form-urlencoded"; - readonly mediaType = "application/x-www-form-urlencoded"; - readonly params: QueryParams; - readonly replayable = true; - writeTo(sink: WritableStream): Promise; -} - -// @public -export function formUrlEncodedBody(input: FormUrlEncodedInput): FormUrlEncodedBody; - -// @public -export type FormUrlEncodedInput = QueryParams | ReadonlyMap | Record | readonly (readonly [string, FormUrlEncodedValue])[]; - -// @public -export type FormUrlEncodedValue = string | number | boolean | bigint | null; - -// @public -export class HeaderName { - equals(other: HeaderName): boolean; - get lowerCased(): string; - static of(raw: string): HeaderName; - get raw(): string; -} - -// @public -class Headers_2 { - entries(): readonly (readonly [string, string])[]; - equals(other: Headers_2): boolean; - get(name: string | HeaderName): string | undefined; - getAll(name: string | HeaderName): readonly string[]; - has(name: string | HeaderName): boolean; - names(): readonly string[]; - static newBuilder(): HeadersBuilder; - newBuilder(): HeadersBuilder; -} -export { Headers_2 as Headers } - -// @public -export class HeadersBuilder implements Builder { - add(name: string | HeaderName, value: string): this; - addInbound(name: string | HeaderName, value: string): this; - build(): Headers_2; - set(name: string | HeaderName, value: string | null): this; - setInbound(name: string | HeaderName, value: string | null): this; -} - -// @public -export class HeaderValidationError extends DomainModelError { - constructor(kind: 'name' | 'value', offendingName: string, _offendingValue: string | undefined); - readonly escapedName: string; - readonly kind: 'name' | 'value'; -} - -// @public -export class HttpRange { - static bounded(start: number, length: number): HttpRange; - get kind(): RangeKind; - get length(): number | undefined; - static open(start: number): HttpRange; - static parse(raw: string): HttpRange; - get raw(): string; - get start(): number | undefined; - static suffix(suffixLength: number): HttpRange; - get suffixLength(): number | undefined; -} - -// @public -export class HttpRangeValidationError extends DomainModelError { -} - -// @public -export class HttpStatusError extends DexpaceError { - constructor(status: number, bodyBytes: Uint8Array | undefined, mediaType: string | undefined, options?: ErrorOptions); - body(): Body_2 | undefined; - preview(charset?: string): string | null; - readonly status: number; -} - -// @public -export interface InstrumentationBundle { - readonly activeSpan: unknown; - readonly isRemote: boolean; - readonly isValid: boolean; - readonly spanId: string; - readonly traceFlags: number; - readonly traceId: string; - readonly traceIdEncoding: string; - readonly tracerFactory: (operationName: string) => unknown; - readonly traceState: string; -} - -// @public -export function isAbsent(tristate: Tristate): tristate is { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'absent'; -}; - -// @public -export function isBodyError(error: unknown): error is ConsumedBodyError | MultipartBoundaryError | FormBodyValidationError; - -// @public -export function isNull(tristate: Tristate): tristate is { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'null'; -}; - -// @public -export function isPresent(tristate: Tristate): tristate is { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'present'; - readonly value: T; -}; - -// @public -export function isSerdeError(e: unknown): e is SerializationError | DeserializationError; - -// @public -export function isSseEventEmpty(event: SseEvent): boolean; - -// @public -export function isTimeoutSignal(signal: AbortSignal): boolean; - -// @public -export function isTristate(value: unknown): value is Tristate; - -// @public -export function makeSseEvent(fields: SseEventFields): SseEvent; - -// @public -export const MAPPER_DONE: MapperOutcome; - -// @public -export const MAPPER_SKIP: MapperOutcome; - -// @public -export type MapperOutcome = { - readonly kind: 'value'; - readonly value: T; -} | { - readonly kind: 'skip'; -} | { - readonly kind: 'done'; -}; - -// @public -export function mapperValue(value: T): MapperOutcome; - -// @public -export function materialize(body: Body_2): Promise; - -// @public -export class MediaType { - get charset(): string | undefined; - equals(other: MediaType): boolean; - matches(pattern: MediaType): boolean; - static of(type: string, subtype: string, parameters?: ReadonlyMap): MediaType; - parameter(key: string): string | undefined; - static parse(raw: string): MediaType; - render(): string; - get subtype(): string; - get type(): string; -} - -// @public -export class MediaTypeParseError extends DomainModelError { -} - -// @public -export type Method = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH'; - -// @public -export class MultipartBody implements Body_2 { - constructor(parts: readonly MultipartPart[], boundary?: string); - readonly contentLength: number; - readonly kind: "multipart"; - readonly mediaType: string; - static newBuilder(): MultipartBodyBuilder; - newBuilder(): MultipartBodyBuilder; - readonly replayable: boolean; - writeTo(sink: WritableStream): Promise; -} - -// @public -export function multipartBody(parts: readonly MultipartPart[], boundary?: string): MultipartBody; - -// @public -export class MultipartBodyBuilder implements Builder { - addPart(part: MultipartPart): this; - boundary(boundary: string | undefined): this; - build(): MultipartBody; - parts(parts: readonly MultipartPart[]): this; -} - -// @public -export class MultipartBoundaryError extends DexpaceError { - constructor(boundary: string, options?: ErrorOptions); - readonly boundary: string; -} - -// @public -export interface MultipartPart { - readonly body: Body_2; - readonly filename?: string | undefined; - readonly name: string; -} - -// @public -export class NameKeyCredential { - [INSPECT](): string; - constructor(name: string, key: string); - readonly name: string; - toString(): string; -} - -// @public -export type Next = (request?: Request_2) => Promise; - -// @public -export function nullValue(): Tristate; - -// @public -export function ofNullable(value: T | null | undefined): Tristate; - -// @public -export class OperationAssemblyError extends DexpaceError { - constructor(message: string, parameterName: string); - readonly parameterName: string; -} - -// @public -export interface OperationDescriptor { - readonly body?: Body_2 | undefined; - readonly headers?: Headers_2 | undefined; - readonly method: Method; - readonly pathParams?: Readonly> | undefined; - readonly pathTemplate: string; - readonly query?: QueryParams | undefined; -} - -// @public -export const PILLAR_STAGES: ReadonlySet; - -// @public -export class PipelineBuilder { - constructor(transport: Transport); - append(descriptor: StepDescriptor): this; - appendAll(descriptors: readonly StepDescriptor[]): this; - build(): Runtime; - insertAfter(anchorType: symbol, descriptor: StepDescriptor): this; - insertBefore(anchorType: symbol, descriptor: StepDescriptor): this; - prepend(descriptor: StepDescriptor): this; - prependAll(descriptors: readonly StepDescriptor[]): this; - reload(descriptors: readonly StepDescriptor[]): this; - remove(type: symbol): this; - replace(anchorType: symbol, descriptor: StepDescriptor): this; - static seedFrom(runtime: Runtime, mode: 'flatten' | 'nest'): PipelineBuilder; -} - -// @public -export class PlaintextCredentialError extends DexpaceError { - constructor(stepName: string, scheme: string); - readonly scheme: string; - readonly stepName: string; -} - -// @public -export function present(value: NonNullable): Tristate; - -// @public -export class Protocol { - equals(other: Protocol): boolean; - static readonly HTTP_1_1: Protocol; - static readonly HTTP_2: Protocol; - static parse(raw: string): Protocol; - get token(): string; -} - -// @public -export class ProtocolParseError extends DomainModelError { -} - -// @public -export class QueryParams { - encode(): string; - equals(other: QueryParams): boolean; - get(name: string): string | undefined; - getAll(name: string): readonly string[]; - has(name: string): boolean; - static newBuilder(): QueryParamsBuilder; - newBuilder(): QueryParamsBuilder; - static parse(raw: string | null | undefined): QueryParams; -} - -// @public -export class QueryParamsBuilder implements Builder { - add(name: string, value: string | null): this; - build(): QueryParams; -} - -// @public -export type RangeKind = 'bounded' | 'suffix' | 'open'; - -// @public -export interface RedirectCondition { - readonly redirectsFollowed: number; - readonly response: Response_2; - readonly visited: ReadonlySet; -} - -// @public -export type RedirectPredicate = (condition: Readonly) => boolean; - -// @public -export interface RedirectSettings { - readonly allow303: boolean; - readonly allowedMethods: ReadonlySet; - readonly allowSchemeDowngrade: boolean; - readonly locationHeader: string; - readonly maxHops: number; - readonly predicate?: RedirectPredicate | undefined; -} - -// @public -export function redirectStep(overrides?: Partial): StepDescriptor; - -// @public -class Request_2 { - get body(): Body_2 | undefined; - equals(other: Request_2): boolean; - get headers(): Headers_2; - get method(): Method; - static newBuilder(): RequestBuilder; - newBuilder(): RequestBuilder; - get url(): URL; -} -export { Request_2 as Request } - -// @public -export class RequestBodyNotAllowedError extends DomainModelError { - constructor(method: string); -} - -// @public -export class RequestBuilder implements Builder { - body(body: Body_2 | undefined): this; - build(): Request_2; - headers(headers: Headers_2): this; - method(method: Method): this; - url(url: string | URL): this; -} - -// @public -export class RequestConditions { - applyTo(headers: Headers_2): Headers_2; - static newBuilder(): RequestConditionsBuilder; - newBuilder(): RequestConditionsBuilder; -} - -// @public -export class RequestConditionsBuilder implements Builder { - build(): RequestConditions; - ifMatch(etag: ETag): this; - ifModifiedSince(date: Date): this; - ifNoneMatch(etag: ETag): this; - ifUnmodifiedSince(date: Date): this; -} - -// @public -export class RequestConditionsValidationError extends DomainModelError { -} - -// @public -export interface RequestContext { - readonly instrumentation: InstrumentationBundle; - readonly key: symbol; - readonly kind: 'request'; - readonly operationName: string | undefined; - readonly request: Request_2; -} - -// @public -export class RequestOptions { - get auth(): AuthDescriptor | undefined; - static readonly EMPTY: RequestOptions; - get maxRetries(): number | undefined; - static newBuilder(): RequestOptionsBuilder; - newBuilder(): RequestOptionsBuilder; - tag(key: string): string | undefined; - get timeoutMs(): number | undefined; -} - -// @public -export class RequestOptionsBuilder implements Builder { - auth(descriptor: AuthDescriptor | undefined): this; - build(): RequestOptions; - maxRetries(value: number | undefined): this; - tags(entries: ReadonlyMap): this; - timeoutMs(value: number | undefined): this; -} - -// @public -export class RequestOptionsValidationError extends DomainModelError { -} - -// @public -export class RequiredFieldError extends DomainModelError { - constructor(fieldName: string); - readonly fieldName: string; -} - -// @public -class Response_2 { - get body(): ReadableStream | null; - bytes(): Promise; - close(): Promise; - get headers(): Headers_2; - static newBuilder(): ResponseBuilder; - newBuilder(): ResponseBuilder; - get protocol(): Protocol; - get reasonPhrase(): string | undefined; - get request(): Request_2; - get status(): Status; - text(): Promise; -} -export { Response_2 as Response } - -// @public -export class ResponseBuilder implements Builder { - body(body: ReadableStream | null): this; - build(): Response_2; - headers(headers: Headers_2): this; - protocol(protocol: Protocol): this; - reasonPhrase(reasonPhrase: string | undefined): this; - request(request: Request_2): this; - status(status: Status): this; -} - -// @public -export interface RetrySettings extends BackoffSettings { - readonly attemptHeaderName?: string | undefined; - readonly maxAttempts: number; - readonly retryableStatuses: ReadonlySet; - readonly totalTimeoutMs?: number | undefined; -} - -// @public -export function retryStep(options?: RetryStepOptions): StepDescriptor; - -// @public -export interface RetryStepOptions { - readonly clock?: Clock | undefined; - readonly delayOverride?: ((attempt: number) => number | undefined) | undefined; - readonly random?: (() => number) | undefined; - readonly settings?: Partial | undefined; -} - -// @public -export class Runtime implements Transport { - close(): Promise; - send(request: Request_2, options?: RequestOptions, signal?: AbortSignal): Promise; - get steps(): readonly StepDescriptor[]; - get transport(): Transport; -} - -// @public -export interface Schema { - parse(input: unknown): T; -} - -// @public -export interface Serde { - readonly deserializer: Deserializer; - readonly mediaType: string; - readonly serializer: Serializer; -} - -// @public -export function serdeBody(value: unknown, serde: Serde, mediaType?: string): Body_2; - -// @public -export interface SerdeErrorOptions { - readonly cause?: unknown; -} - -// @public -export class SerializationError extends DexpaceError { - constructor(message: string, options?: SerdeErrorOptions); -} - -// @public -export interface Serializer { - serialize(value: unknown): Uint8Array; - serializeInto(value: unknown, target: Uint8Array, offset?: number): number; - serializeTo(value: unknown, sink: WritableStream): Promise; - serializeToString(value: unknown): string; -} - -// @public -export interface SseEvent { - // (undocumented) - readonly comment: string | undefined; - readonly data: readonly string[]; - // (undocumented) - readonly event: string | undefined; - // (undocumented) - readonly id: string | undefined; - // (undocumented) - readonly retryMs: number | undefined; -} - -// @public -export interface SseEventFields { - // (undocumented) - readonly comment?: string | undefined; - // (undocumented) - readonly data?: readonly string[] | undefined; - // (undocumented) - readonly event?: string | undefined; - // (undocumented) - readonly id?: string | undefined; - // (undocumented) - readonly retryMs?: number | undefined; -} - -// @public -export function sseEventsEqual(a: SseEvent, b: SseEvent): boolean; - -// @public -export function sseEventToString(event: SseEvent): string; - -// @public -export class SseLineTooLongError extends DexpaceError { - constructor(limitBytes: number, options?: ErrorOptions); - readonly limitBytes: number; -} - -// @public -export type SseMapper = (eventName: string | undefined, joinedData: string) => MapperOutcome; - -// @public -export class SseStream implements AsyncIterable { - [Symbol.asyncIterator](): AsyncIterator; - close(): Promise; -} - -// @public -export class SseStreamError extends DexpaceError { - constructor(message: string, options?: ErrorOptions); -} - -// @public -export function sseStreamFrom(response: Response_2, options?: SseStreamFromOptions): SseStream; - -// @public -export interface SseStreamFromOptions extends SseStreamOptions { - readonly maxLineBytes?: number | undefined; - readonly signal?: AbortSignal | undefined; -} - -// @public -export interface SseStreamOptions { - readonly onReleaseFailure?: ((error: unknown) => void) | undefined; -} - -// @public -export type Stage = 'PRE_REDIRECT' | 'REDIRECT' | 'POST_REDIRECT' | 'PRE_RETRY' | 'RETRY' | 'POST_RETRY' | 'PRE_AUTH' | 'AUTH' | 'POST_AUTH' | 'PRE_LOGGING' | 'LOGGING' | 'POST_LOGGING' | 'PRE_SERDE' | 'SERDE' | 'POST_SERDE' | 'SEND'; - -// @public -export const STAGE_ORDER: readonly Stage[]; - -// @public -export function standardResilience(transport: Transport, options?: StandardResilienceOptions): Runtime; - -// @public -export interface StandardResilienceOptions { - readonly auth?: AuthStepSettings | undefined; - readonly redirect?: Partial | undefined; - readonly retry?: RetryStepOptions | undefined; -} - -// @public -export class Status { - get code(): number; - equals(other: Status): boolean; - get isClientError(): boolean; - get isError(): boolean; - get isInformational(): boolean; - get isRecognized(): boolean; - get isRedirect(): boolean; - get isServerError(): boolean; - get isSuccess(): boolean; - get name(): string | undefined; - static of(code: number): Status; - static recognized(code: number): Status | undefined; -} - -// @public -export type Step = (request: Request_2, ctx: StepContext) => Promise; - -// @public -export interface StepContext { - readonly context: ExecutionContext; - readonly fork?: (() => Next) | undefined; - readonly next: Next; - readonly options?: RequestOptions | undefined; - readonly signal?: AbortSignal | undefined; -} - -// @public -export interface StepDescriptor { - readonly fn: Step; - readonly stage: Stage; - readonly type: symbol; -} - -// @public -export class StreamBody implements Body_2 { - constructor(stream: ReadableStream, mediaType?: string, contentLength?: number); - readonly contentLength: number; - readonly kind: "stream"; - readonly mediaType: string | undefined; - readonly replayable = false; - writeTo(sink: WritableStream): Promise; -} - -// @public -export function streamBody(stream: ReadableStream, mediaType?: string, contentLength?: number): StreamBody; - -// @public -export class StringBody implements Body_2 { - constructor(text: string, mediaType?: string); - readonly contentLength: number; - readonly kind: "string"; - readonly mediaType: string; - readonly replayable = true; - readonly text: string; - writeTo(sink: WritableStream): Promise; -} - -// @public -export function stringBody(text: string, mediaType?: string): StringBody; - -// @public -export function toHttpError(response: Response_2): Promise; - -// @public -export type TokenProvider = () => Promise; - -// @public -export interface Transport { - close(): Promise; - send(request: Request_2, options?: RequestOptions, signal?: AbortSignal): Promise; -} - -// @public -export type Tristate = { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'absent'; -} | { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'null'; -} | { - readonly [TRISTATE_BRAND]: true; - readonly kind: 'present'; - readonly value: T; -}; - -// @public -export const TRISTATE_BRAND: unique symbol; - -// @public -export interface TristateBranches { - readonly onAbsent: () => R; - readonly onNull: () => R; - readonly onPresent: (value: T) => R; -} - -// @public -export function tristateToString(tristate: Tristate): string; - -// @public -export class TypedResponse { - constructor(response: Response_2, parse: (response: Response_2) => Promise); - get headers(): Response_2['headers']; - get protocol(): string; - get reason(): string | undefined; - get request(): Request_2; - get status(): Response_2['status']; - value(): Promise; -} - -// @public -export function typedSseStream(stream: SseStream, mapper: SseMapper): AsyncIterable; - -// @public -export class UrlConstructionError extends DomainModelError { -} - -// @public -export function valueOrNull(tristate: Tristate): T | null; - -``` +## API Report File for "@dexpace/core" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public +export function absent(): Tristate; + +// @public +export class ApiKeyCredential { + [INSPECT](): string; + constructor(key: string); + toString(): string; +} + +// @public +export interface ApiKeyCredentialConfig { + readonly credential: ApiKeyCredential | NameKeyCredential; + readonly headerName?: string | undefined; + readonly prefix?: string | undefined; +} + +// @public +export interface AuthCredentialSet { + readonly apiKey?: ApiKeyCredentialConfig | undefined; + readonly basic?: BasicCredential | undefined; + readonly bearer?: BearerCredential | undefined; + readonly digest?: DigestCredential | undefined; +} + +// @public +export interface AuthDescriptor { + readonly allowsAnonymous: boolean; + readonly requirements: readonly AuthRequirement[]; +} + +// @public +export interface AuthRequirement { + readonly params: ReadonlyMap; + readonly scheme: AuthScheme; + readonly scopes: readonly string[]; +} + +// @public +export function authRequirementsEqual(a: AuthRequirement, b: AuthRequirement): boolean; + +// @public +export class AuthResolutionError extends DexpaceError { + constructor(message: string, requiredSchemes?: readonly string[], availableSchemes?: readonly string[]); + readonly availableSchemes: readonly string[] | undefined; + readonly requiredSchemes: readonly string[] | undefined; + static unsatisfiable(requiredSchemes: readonly string[], availableSchemes: readonly string[]): AuthResolutionError; +} + +// @public +export type AuthScheme = 'OAUTH2' | 'API_KEY' | 'BASIC' | 'DIGEST' | 'NO_AUTH'; + +// @public +export function authStep(settings: AuthStepSettings): StepDescriptor; + +// @public +export interface AuthStepSettings { + readonly bearerMarginMs?: number | undefined; + readonly challengeHook?: ChallengeHook | undefined; + readonly clock?: Pick | undefined; + readonly credentials: AuthCredentialSet; + readonly tiers: AuthTiers; +} + +// @public +export interface AuthTiers { + readonly client?: AuthDescriptor | undefined; + readonly operation?: AuthDescriptor | undefined; + readonly perCall?: AuthDescriptor | undefined; +} + +// @public +export interface BackoffSettings { + readonly fixedDelayMs?: number | undefined; + readonly initialDelayMs: number; + readonly jitter: number; + readonly maxDelayMs: number; + readonly multiplier: number; +} + +// @public +export interface BasicCredential { + readonly password: string; + readonly username: string; +} + +// @public +export interface BearerCredential { + readonly marginMs?: number | undefined; + readonly provider: TokenProvider; +} + +// @public +export class BearerToken { + [INSPECT](): string; + readonly expiresAt: number | undefined; + get token(): string; + toString(): string; +} + +// @public +export function bearerTokensEqual(a: BearerToken, b: BearerToken): boolean; + +// @public +interface Body_2 { + readonly contentLength: number; + readonly kind: 'byte-array' | 'string' | 'stream' | 'form-urlencoded' | 'multipart'; + readonly mediaType: string | undefined; + readonly replayable: boolean; + writeTo(sink: WritableStream): Promise; +} +export { Body_2 as Body } + +// @public +export interface Builder { + build(): T; +} + +// @public +export function buildRequest(baseUrl: string | URL, operation: OperationDescriptor): Request_2; + +// @public +export class ByteArrayBody implements Body_2 { + constructor(bytes: Uint8Array, mediaType?: string); + readonly contentLength: number; + readonly kind: "byte-array"; + readonly mediaType: string | undefined; + readonly replayable = true; + writeTo(sink: WritableStream): Promise; +} + +// @public +export function byteArrayBody(bytes: Uint8Array, mediaType?: string): ByteArrayBody; + +// @public +export class CancellationError extends DexpaceError { + constructor(message: string, options?: ErrorOptions); +} + +// @public +export type ChallengeHook = (response: Response_2, request: Request_2, options?: { + readonly signal?: AbortSignal | undefined; +}) => Promise; + +// @public +export interface Clock { + monotonic(): number; + now(): number; + sleep(ms: number, signal?: AbortSignal): Promise; +} + +// @public +export function composeSignal(userSignal?: AbortSignal, timeoutMs?: number): AbortSignal | undefined; + +// @public +export class ConsumedBodyError extends DexpaceError { + constructor(bodyKind: string, options?: ErrorOptions); + readonly bodyKind: string; +} + +// @public +export function createAuthDescriptor(requirements: readonly AuthRequirement[]): AuthDescriptor; + +// @public +export function createAuthRequirement(scheme: AuthScheme, scopes?: readonly string[], params?: ReadonlyMap): AuthRequirement; + +// @public +export function createBearerToken(token: string, expiresAt?: number): BearerToken; + +// @public +export function cursorStrategy(init: { + extract: (response: Response_2) => Promise<{ + items: readonly T[]; + cursor?: string | null | undefined; + }>; + parameterName?: string | undefined; +}): PaginationStrategy; + +// @public +export function decodeResponse(response: Response_2, deserializer: Deserializer, target: DecodeTarget): Promise; + +// @public +export function decodeSuccessResponse(response: Response_2, deserializer: Deserializer, target: DecodeTarget): Promise; + +// @public +export interface DecodeTarget { + readonly schema: Schema; + readonly typeName?: string | undefined; +} + +// @public +export class DeserializationError extends DexpaceError { + constructor(message: string, options?: DeserializationErrorOptions); + readonly etag: string | null; + readonly location: string | null; + readonly status: number | undefined; +} + +// @public +export interface DeserializationErrorOptions extends SerdeErrorOptions { + readonly etag?: string | null | undefined; + readonly location?: string | null | undefined; + readonly status?: number | undefined; +} + +// @public +export interface Deserializer { + deserialize(data: Uint8Array, schema: Schema, typeName?: string): T; + deserializeFrom(source: ReadableStream, schema: Schema, typeName?: string): Promise; +} + +// @public +export class DexpaceError extends Error { + constructor(message: string, options?: ErrorOptions); +} + +// @public +export type DigestAlgorithm = 'MD5' | 'MD5-sess' | 'SHA-256' | 'SHA-256-sess'; + +// @public +export interface DigestCredential { + readonly algorithmPreference?: readonly DigestAlgorithm[] | undefined; + readonly password: string; + readonly username: string; +} + +// @public +export interface DispatchContext { + readonly instrumentation: InstrumentationBundle; + readonly key: symbol; + readonly kind: 'dispatch'; +} + +// @public +export class DomainModelError extends DexpaceError { +} + +// @public +export class ETag { + static readonly ANY: ETag; + get isAny(): boolean; + get isWeak(): boolean; + get opaque(): string | undefined; + static parse(raw: string): ETag | undefined; + get raw(): string; +} + +// @public +export class EtagParseError extends DomainModelError { +} + +// @public +export interface ExchangeContext { + readonly instrumentation: InstrumentationBundle; + readonly key: symbol; + readonly kind: 'exchange'; + readonly operationName: string | undefined; + readonly request: Request_2; + readonly response: Response_2; +} + +// @public +export type ExecutionContext = DispatchContext | RequestContext | ExchangeContext; + +// @public +export interface FetcherPage { + readonly continuationToken?: string | undefined; + readonly nextLink?: string | undefined; + readonly page: Page; +} + +// @public +export interface FetcherPaginationInit { + first: (options: PagingOptions) => Promise | undefined>; + maxPages?: number | undefined; + next: (key: string, options: PagingOptions) => Promise | undefined>; +} + +// @public +export function foldTristate(tristate: Tristate, branches: TristateBranches): R; + +// @public +export class FormBodyValidationError extends DexpaceError { + constructor(field: string, value: unknown, options?: ErrorOptions); + readonly field: string; +} + +// @public +export class FormUrlEncodedBody implements Body_2 { + constructor(input: FormUrlEncodedInput); + readonly contentLength: number; + readonly kind: "form-urlencoded"; + readonly mediaType = "application/x-www-form-urlencoded"; + readonly params: QueryParams; + readonly replayable = true; + writeTo(sink: WritableStream): Promise; +} + +// @public +export function formUrlEncodedBody(input: FormUrlEncodedInput): FormUrlEncodedBody; + +// @public +export type FormUrlEncodedInput = QueryParams | ReadonlyMap | Record | readonly (readonly [string, FormUrlEncodedValue])[]; + +// @public +export type FormUrlEncodedValue = string | number | boolean | bigint | null; + +// @public +export class HeaderName { + equals(other: HeaderName): boolean; + get lowerCased(): string; + static of(raw: string): HeaderName; + get raw(): string; +} + +// @public +class Headers_2 { + entries(): readonly (readonly [string, string])[]; + equals(other: Headers_2): boolean; + get(name: string | HeaderName): string | undefined; + getAll(name: string | HeaderName): readonly string[]; + has(name: string | HeaderName): boolean; + names(): readonly string[]; + static newBuilder(): HeadersBuilder; + newBuilder(): HeadersBuilder; +} +export { Headers_2 as Headers } + +// @public +export class HeadersBuilder implements Builder { + add(name: string | HeaderName, value: string): this; + addInbound(name: string | HeaderName, value: string): this; + build(): Headers_2; + set(name: string | HeaderName, value: string | null): this; + setInbound(name: string | HeaderName, value: string | null): this; +} + +// @public +export class HeaderValidationError extends DomainModelError { + constructor(kind: 'name' | 'value', offendingName: string, _offendingValue: string | undefined); + readonly escapedName: string; + readonly kind: 'name' | 'value'; +} + +// @public +export class HttpRange { + static bounded(start: number, length: number): HttpRange; + get kind(): RangeKind; + get length(): number | undefined; + static open(start: number): HttpRange; + static parse(raw: string): HttpRange; + get raw(): string; + get start(): number | undefined; + static suffix(suffixLength: number): HttpRange; + get suffixLength(): number | undefined; +} + +// @public +export class HttpRangeValidationError extends DomainModelError { +} + +// @public +export class HttpStatusError extends DexpaceError { + constructor(status: number, bodyBytes: Uint8Array | undefined, mediaType: string | undefined, options?: ErrorOptions); + body(): Body_2 | undefined; + preview(charset?: string): string | null; + readonly status: number; +} + +// @public +export interface InstrumentationBundle { + readonly activeSpan: unknown; + readonly isRemote: boolean; + readonly isValid: boolean; + readonly spanId: string; + readonly traceFlags: number; + readonly traceId: string; + readonly traceIdEncoding: string; + readonly tracerFactory: (operationName: string) => unknown; + readonly traceState: string; +} + +// @public +export function isAbsent(tristate: Tristate): tristate is { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'absent'; +}; + +// @public +export function isBodyError(error: unknown): error is ConsumedBodyError | MultipartBoundaryError | FormBodyValidationError; + +// @public +export function isNull(tristate: Tristate): tristate is { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'null'; +}; + +// @public +export function isPresent(tristate: Tristate): tristate is { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'present'; + readonly value: T; +}; + +// @public +export function isSerdeError(e: unknown): e is SerializationError | DeserializationError; + +// @public +export function isSseEventEmpty(event: SseEvent): boolean; + +// @public +export function isTimeoutSignal(signal: AbortSignal): boolean; + +// @public +export function isTristate(value: unknown): value is Tristate; + +// @public +export function linkHeaderStrategy(init: { + extract: (response: Response_2) => Promise; + headerName?: string | undefined; +}): PaginationStrategy; + +// @public +export function makeSseEvent(fields: SseEventFields): SseEvent; + +// @public +export const MAPPER_DONE: MapperOutcome; + +// @public +export const MAPPER_SKIP: MapperOutcome; + +// @public +export type MapperOutcome = { + readonly kind: 'value'; + readonly value: T; +} | { + readonly kind: 'skip'; +} | { + readonly kind: 'done'; +}; + +// @public +export function mapperValue(value: T): MapperOutcome; + +// @public +export function materialize(body: Body_2): Promise; + +// @public +export class MediaType { + get charset(): string | undefined; + equals(other: MediaType): boolean; + matches(pattern: MediaType): boolean; + static of(type: string, subtype: string, parameters?: ReadonlyMap): MediaType; + parameter(key: string): string | undefined; + static parse(raw: string): MediaType; + render(): string; + get subtype(): string; + get type(): string; +} + +// @public +export class MediaTypeParseError extends DomainModelError { +} + +// @public +export type Method = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH'; + +// @public +export class MultipartBody implements Body_2 { + constructor(parts: readonly MultipartPart[], boundary?: string); + readonly contentLength: number; + readonly kind: "multipart"; + readonly mediaType: string; + static newBuilder(): MultipartBodyBuilder; + newBuilder(): MultipartBodyBuilder; + readonly replayable: boolean; + writeTo(sink: WritableStream): Promise; +} + +// @public +export function multipartBody(parts: readonly MultipartPart[], boundary?: string): MultipartBody; + +// @public +export class MultipartBodyBuilder implements Builder { + addPart(part: MultipartPart): this; + boundary(boundary: string | undefined): this; + build(): MultipartBody; + parts(parts: readonly MultipartPart[]): this; +} + +// @public +export class MultipartBoundaryError extends DexpaceError { + constructor(boundary: string, options?: ErrorOptions); + readonly boundary: string; +} + +// @public +export interface MultipartPart { + readonly body: Body_2; + readonly filename?: string | undefined; + readonly name: string; +} + +// @public +export class NameKeyCredential { + [INSPECT](): string; + constructor(name: string, key: string); + readonly name: string; + toString(): string; +} + +// @public +export type Next = (request?: Request_2) => Promise; + +// @public +export function nullValue(): Tristate; + +// @public +export function ofNullable(value: T | null | undefined): Tristate; + +// @public +export class OperationAssemblyError extends DexpaceError { + constructor(message: string, parameterName: string); + readonly parameterName: string; +} + +// @public +export interface OperationDescriptor { + readonly body?: Body_2 | undefined; + readonly headers?: Headers_2 | undefined; + readonly method: Method; + readonly pathParams?: Readonly> | undefined; + readonly pathTemplate: string; + readonly query?: QueryParams | undefined; +} + +// @public +export class Page implements AsyncDisposable { + [Symbol.asyncDispose](): Promise; + constructor(response: Response_2, items: readonly T[]); + close(): Promise; + readonly headers: Headers_2; + readonly items: readonly T[]; + readonly request: Request_2; + readonly status: Status; +} + +// @public +export interface PageInfo { + readonly items: readonly T[]; + readonly nextRequest: Request_2 | undefined; +} + +// @public +export function pageInfo(items: readonly T[], nextRequest?: Request_2): PageInfo; + +// @public +export function pageNumberStrategy(init: { + extract: (response: Response_2) => Promise; + parameterName?: string | undefined; + startPage?: number | undefined; +}): PaginationStrategy; + +// @public +export function paginateWithFetchers(init: FetcherPaginationInit): AsyncIterable>; + +// @public +export class PaginationError extends DexpaceError { + constructor(message: string, options?: ErrorOptions); +} + +// @public +export interface PaginationStrategy { + parse(response: Response_2, template: Request_2): Promise>; +} + +// @public +export class Paginator { + constructor(init: PaginatorInit); + items(): AsyncIterable; + pages(): AsyncIterable>; +} + +// @public +export interface PaginatorInit { + readonly initialRequest: Request_2; + readonly maxPages?: number | undefined; + readonly options?: RequestOptions | undefined; + readonly signal?: AbortSignal | undefined; + readonly strategy: PaginationStrategy; + readonly transport: Transport; +} + +// @public +export interface PagingOptions { + [key: string]: unknown; + continuationToken?: string | undefined; + nextLink?: string | undefined; +} + +// @public +export const PILLAR_STAGES: ReadonlySet; + +// @public +export class PipelineBuilder { + constructor(transport: Transport); + append(descriptor: StepDescriptor): this; + appendAll(descriptors: readonly StepDescriptor[]): this; + build(): Runtime; + insertAfter(anchorType: symbol, descriptor: StepDescriptor): this; + insertBefore(anchorType: symbol, descriptor: StepDescriptor): this; + prepend(descriptor: StepDescriptor): this; + prependAll(descriptors: readonly StepDescriptor[]): this; + reload(descriptors: readonly StepDescriptor[]): this; + remove(type: symbol): this; + replace(anchorType: symbol, descriptor: StepDescriptor): this; + static seedFrom(runtime: Runtime, mode: 'flatten' | 'nest'): PipelineBuilder; +} + +// @public +export class PlaintextCredentialError extends DexpaceError { + constructor(stepName: string, scheme: string); + readonly scheme: string; + readonly stepName: string; +} + +// @public +export function present(value: NonNullable): Tristate; + +// @public +export class Protocol { + equals(other: Protocol): boolean; + static readonly HTTP_1_1: Protocol; + static readonly HTTP_2: Protocol; + static parse(raw: string): Protocol; + get token(): string; +} + +// @public +export class ProtocolParseError extends DomainModelError { +} + +// @public +export class QueryParams { + encode(): string; + equals(other: QueryParams): boolean; + get(name: string): string | undefined; + getAll(name: string): readonly string[]; + has(name: string): boolean; + static newBuilder(): QueryParamsBuilder; + newBuilder(): QueryParamsBuilder; + static parse(raw: string | null | undefined): QueryParams; +} + +// @public +export class QueryParamsBuilder implements Builder { + add(name: string, value: string | null): this; + build(): QueryParams; +} + +// @public +export type RangeKind = 'bounded' | 'suffix' | 'open'; + +// @public +export interface RedirectCondition { + readonly redirectsFollowed: number; + readonly response: Response_2; + readonly visited: ReadonlySet; +} + +// @public +export type RedirectPredicate = (condition: Readonly) => boolean; + +// @public +export interface RedirectSettings { + readonly allow303: boolean; + readonly allowedMethods: ReadonlySet; + readonly allowSchemeDowngrade: boolean; + readonly locationHeader: string; + readonly maxHops: number; + readonly predicate?: RedirectPredicate | undefined; +} + +// @public +export function redirectStep(overrides?: Partial): StepDescriptor; + +// @public +class Request_2 { + get body(): Body_2 | undefined; + equals(other: Request_2): boolean; + get headers(): Headers_2; + get method(): Method; + static newBuilder(): RequestBuilder; + newBuilder(): RequestBuilder; + get url(): URL; +} +export { Request_2 as Request } + +// @public +export class RequestBodyNotAllowedError extends DomainModelError { + constructor(method: string); +} + +// @public +export class RequestBuilder implements Builder { + body(body: Body_2 | undefined): this; + build(): Request_2; + headers(headers: Headers_2): this; + method(method: Method): this; + url(url: string | URL): this; +} + +// @public +export class RequestConditions { + applyTo(headers: Headers_2): Headers_2; + static newBuilder(): RequestConditionsBuilder; + newBuilder(): RequestConditionsBuilder; +} + +// @public +export class RequestConditionsBuilder implements Builder { + build(): RequestConditions; + ifMatch(etag: ETag): this; + ifModifiedSince(date: Date): this; + ifNoneMatch(etag: ETag): this; + ifUnmodifiedSince(date: Date): this; +} + +// @public +export class RequestConditionsValidationError extends DomainModelError { +} + +// @public +export interface RequestContext { + readonly instrumentation: InstrumentationBundle; + readonly key: symbol; + readonly kind: 'request'; + readonly operationName: string | undefined; + readonly request: Request_2; +} + +// @public +export class RequestOptions { + get auth(): AuthDescriptor | undefined; + static readonly EMPTY: RequestOptions; + get maxRetries(): number | undefined; + static newBuilder(): RequestOptionsBuilder; + newBuilder(): RequestOptionsBuilder; + tag(key: string): string | undefined; + get timeoutMs(): number | undefined; +} + +// @public +export class RequestOptionsBuilder implements Builder { + auth(descriptor: AuthDescriptor | undefined): this; + build(): RequestOptions; + maxRetries(value: number | undefined): this; + tags(entries: ReadonlyMap): this; + timeoutMs(value: number | undefined): this; +} + +// @public +export class RequestOptionsValidationError extends DomainModelError { +} + +// @public +export class RequiredFieldError extends DomainModelError { + constructor(fieldName: string); + readonly fieldName: string; +} + +// @public +class Response_2 { + get body(): ReadableStream | null; + bytes(): Promise; + close(): Promise; + get headers(): Headers_2; + static newBuilder(): ResponseBuilder; + newBuilder(): ResponseBuilder; + get protocol(): Protocol; + get reasonPhrase(): string | undefined; + get request(): Request_2; + get status(): Status; + text(): Promise; +} +export { Response_2 as Response } + +// @public +export class ResponseBuilder implements Builder { + body(body: ReadableStream | null): this; + build(): Response_2; + headers(headers: Headers_2): this; + protocol(protocol: Protocol): this; + reasonPhrase(reasonPhrase: string | undefined): this; + request(request: Request_2): this; + status(status: Status): this; +} + +// @public +export interface RetrySettings extends BackoffSettings { + readonly attemptHeaderName?: string | undefined; + readonly maxAttempts: number; + readonly retryableStatuses: ReadonlySet; + readonly totalTimeoutMs?: number | undefined; +} + +// @public +export function retryStep(options?: RetryStepOptions): StepDescriptor; + +// @public +export interface RetryStepOptions { + readonly clock?: Clock | undefined; + readonly delayOverride?: ((attempt: number) => number | undefined) | undefined; + readonly random?: (() => number) | undefined; + readonly settings?: Partial | undefined; +} + +// @public +export class Runtime implements Transport { + close(): Promise; + send(request: Request_2, options?: RequestOptions, signal?: AbortSignal): Promise; + get steps(): readonly StepDescriptor[]; + get transport(): Transport; +} + +// @public +export interface Schema { + parse(input: unknown): T; +} + +// @public +export interface Serde { + readonly deserializer: Deserializer; + readonly mediaType: string; + readonly serializer: Serializer; +} + +// @public +export function serdeBody(value: unknown, serde: Serde, mediaType?: string): Body_2; + +// @public +export interface SerdeErrorOptions { + readonly cause?: unknown; +} + +// @public +export class SerializationError extends DexpaceError { + constructor(message: string, options?: SerdeErrorOptions); +} + +// @public +export interface Serializer { + serialize(value: unknown): Uint8Array; + serializeInto(value: unknown, target: Uint8Array, offset?: number): number; + serializeTo(value: unknown, sink: WritableStream): Promise; + serializeToString(value: unknown): string; +} + +// @public +export interface SseEvent { + // (undocumented) + readonly comment: string | undefined; + readonly data: readonly string[]; + // (undocumented) + readonly event: string | undefined; + // (undocumented) + readonly id: string | undefined; + // (undocumented) + readonly retryMs: number | undefined; +} + +// @public +export interface SseEventFields { + // (undocumented) + readonly comment?: string | undefined; + // (undocumented) + readonly data?: readonly string[] | undefined; + // (undocumented) + readonly event?: string | undefined; + // (undocumented) + readonly id?: string | undefined; + // (undocumented) + readonly retryMs?: number | undefined; +} + +// @public +export function sseEventsEqual(a: SseEvent, b: SseEvent): boolean; + +// @public +export function sseEventToString(event: SseEvent): string; + +// @public +export class SseLineTooLongError extends DexpaceError { + constructor(limitBytes: number, options?: ErrorOptions); + readonly limitBytes: number; +} + +// @public +export type SseMapper = (eventName: string | undefined, joinedData: string) => MapperOutcome; + +// @public +export class SseStream implements AsyncIterable { + [Symbol.asyncIterator](): AsyncIterator; + close(): Promise; +} + +// @public +export class SseStreamError extends DexpaceError { + constructor(message: string, options?: ErrorOptions); +} + +// @public +export function sseStreamFrom(response: Response_2, options?: SseStreamFromOptions): SseStream; + +// @public +export interface SseStreamFromOptions extends SseStreamOptions { + readonly maxLineBytes?: number | undefined; + readonly signal?: AbortSignal | undefined; +} + +// @public +export interface SseStreamOptions { + readonly onReleaseFailure?: ((error: unknown) => void) | undefined; +} + +// @public +export type Stage = 'PRE_REDIRECT' | 'REDIRECT' | 'POST_REDIRECT' | 'PRE_RETRY' | 'RETRY' | 'POST_RETRY' | 'PRE_AUTH' | 'AUTH' | 'POST_AUTH' | 'PRE_LOGGING' | 'LOGGING' | 'POST_LOGGING' | 'PRE_SERDE' | 'SERDE' | 'POST_SERDE' | 'SEND'; + +// @public +export const STAGE_ORDER: readonly Stage[]; + +// @public +export function standardResilience(transport: Transport, options?: StandardResilienceOptions): Runtime; + +// @public +export interface StandardResilienceOptions { + readonly auth?: AuthStepSettings | undefined; + readonly redirect?: Partial | undefined; + readonly retry?: RetryStepOptions | undefined; +} + +// @public +export class Status { + get code(): number; + equals(other: Status): boolean; + get isClientError(): boolean; + get isError(): boolean; + get isInformational(): boolean; + get isRecognized(): boolean; + get isRedirect(): boolean; + get isServerError(): boolean; + get isSuccess(): boolean; + get name(): string | undefined; + static of(code: number): Status; + static recognized(code: number): Status | undefined; +} + +// @public +export type Step = (request: Request_2, ctx: StepContext) => Promise; + +// @public +export interface StepContext { + readonly context: ExecutionContext; + readonly fork?: (() => Next) | undefined; + readonly next: Next; + readonly options?: RequestOptions | undefined; + readonly signal?: AbortSignal | undefined; +} + +// @public +export interface StepDescriptor { + readonly fn: Step; + readonly stage: Stage; + readonly type: symbol; +} + +// @public +export class StreamBody implements Body_2 { + constructor(stream: ReadableStream, mediaType?: string, contentLength?: number); + readonly contentLength: number; + readonly kind: "stream"; + readonly mediaType: string | undefined; + readonly replayable = false; + writeTo(sink: WritableStream): Promise; +} + +// @public +export function streamBody(stream: ReadableStream, mediaType?: string, contentLength?: number): StreamBody; + +// @public +export class StringBody implements Body_2 { + constructor(text: string, mediaType?: string); + readonly contentLength: number; + readonly kind: "string"; + readonly mediaType: string; + readonly replayable = true; + readonly text: string; + writeTo(sink: WritableStream): Promise; +} + +// @public +export function stringBody(text: string, mediaType?: string): StringBody; + +// @public +export function toHttpError(response: Response_2): Promise; + +// @public +export type TokenProvider = () => Promise; + +// @public +export interface Transport { + close(): Promise; + send(request: Request_2, options?: RequestOptions, signal?: AbortSignal): Promise; +} + +// @public +export type Tristate = { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'absent'; +} | { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'null'; +} | { + readonly [TRISTATE_BRAND]: true; + readonly kind: 'present'; + readonly value: T; +}; + +// @public +export const TRISTATE_BRAND: unique symbol; + +// @public +export interface TristateBranches { + readonly onAbsent: () => R; + readonly onNull: () => R; + readonly onPresent: (value: T) => R; +} + +// @public +export function tristateToString(tristate: Tristate): string; + +// @public +export class TypedResponse { + constructor(response: Response_2, parse: (response: Response_2) => Promise); + get headers(): Response_2['headers']; + get protocol(): string; + get reason(): string | undefined; + get request(): Request_2; + get status(): Response_2['status']; + value(): Promise; +} + +// @public +export function typedSseStream(stream: SseStream, mapper: SseMapper): AsyncIterable; + +// @public +export class UrlConstructionError extends DomainModelError { +} + +// @public +export function valueOrNull(tristate: Tristate): T | null; + +``` diff --git a/packages/core/src/body/response-body-logging.ts b/packages/core/src/body/response-body-logging.ts index 7563b2e..a5ebc0a 100644 --- a/packages/core/src/body/response-body-logging.ts +++ b/packages/core/src/body/response-body-logging.ts @@ -9,11 +9,8 @@ import {ConsumedBodyError} from './errors.js'; /** * A lazily-draining, bounded capture wrapper over a raw response body stream (BODY-22..29). * - * Teardown is `close()` only. `[Symbol.asyncDispose]` is deliberately absent: it postdates the declared - * `engines.node` floor (`>=18.17`), where the computed key evaluates to `undefined` and binds the method - * to the string `"undefined"` instead -- wrong, silent, and only at run time. This matches the decision - * every Phase 3a resource already ships with. Revisit when the checkpoint's floor bump lands and adds it - * to all of them at once, rather than to two classes out of seven. + * Teardown is `close()` only. Revisit when a project-wide explicit resource management pass lands + * across all Phase 2/3a resource classes. * * @internal */ diff --git a/packages/core/src/http/query-params.test.ts b/packages/core/src/http/query-params.test.ts index 7a71853..2865794 100644 --- a/packages/core/src/http/query-params.test.ts +++ b/packages/core/src/http/query-params.test.ts @@ -4,7 +4,11 @@ // HTTP-30 (order-sensitive equality, empty-list dropped), HTTP-31 (lenient parse) import {describe, expect, test} from 'bun:test'; import fc from 'fast-check'; -import {QueryParams} from './query-params.js'; +import { + QueryParams, + decodeQueryComponent, + encodeQueryComponent, +} from './query-params.js'; describe('case-sensitive names and multi-value (HTTP-28)', () => { test('page and Page are distinct names', () => { @@ -124,3 +128,24 @@ describe('newBuilder derivation (HTTP-3)', () => { expect(original.getAll('x')).toEqual(['1', '2']); }); }); + +// PAGE-22 restates HTTP-29's rule. These assertions pin the shared function so the pagination splice can rely +// on it instead of restating the rule and drifting. +test('the component encoder is directly reachable and follows RFC 3986 (HTTP-29, reused by PAGE-22)', () => { + expect(encodeQueryComponent('a b')).toBe('a%20b'); + expect(encodeQueryComponent('a+b')).toBe('a%2Bb'); + expect(encodeQueryComponent('a/b')).toBe('a%2Fb'); + expect(encodeQueryComponent('a=b')).toBe('a%3Db'); + expect(encodeQueryComponent('a*b')).toBe('a%2Ab'); + expect(encodeQueryComponent('AZaz09-._~')).toBe('AZaz09-._~'); +}); + +test('the component decoder treats a literal + as data, not a space (HTTP-29, PAGE-22)', () => { + expect(decodeQueryComponent('a+b')).toBe('a+b'); + expect(decodeQueryComponent('a%20b')).toBe('a b'); + expect(decodeQueryComponent('a%2Bb')).toBe('a+b'); +}); + +test('the decoder falls back to raw text on malformed percent-encoding (HTTP-31)', () => { + expect(decodeQueryComponent('a%zzb')).toBe('a%zzb'); +}); diff --git a/packages/core/src/http/query-params.ts b/packages/core/src/http/query-params.ts index 0510f3f..a990680 100644 --- a/packages/core/src/http/query-params.ts +++ b/packages/core/src/http/query-params.ts @@ -3,7 +3,24 @@ import type {Builder} from './builder.js'; import {encodeRfc3986Component} from './rfc3986.js'; -function safeDecodeComponent(value: string): string { +/** + * @internal + * RFC 3986 component encoding (HTTP-29): space → `%20` (never `+`), literal `+` → `%2B`, everything outside + * the unreserved set `A–Z a–z 0–9 - . _ ~` percent-encoded. + * + * Exported so `src/pagination/query-splice.ts` can reuse it. `PAGE-22` restates this exact rule, and two + * encoders in one codebase is a drift bug waiting to happen — there is exactly one. + */ +export function encodeQueryComponent(value: string): string { + return encodeRfc3986Component(value); +} + +/** + * @internal + * RFC 3986 component decoding (HTTP-29/HTTP-31): a literal `+` reads back as `+`, `%20` as a space, and + * malformed percent-encoding falls back to raw text rather than throwing. + */ +export function decodeQueryComponent(value: string): string { try { return decodeURIComponent(value); } catch { @@ -99,7 +116,10 @@ export class QueryParams { const eqIndex = segment.indexOf('='); const rawName = eqIndex === -1 ? segment : segment.slice(0, eqIndex); const rawValue = eqIndex === -1 ? '' : segment.slice(eqIndex + 1); - builder.add(safeDecodeComponent(rawName), safeDecodeComponent(rawValue)); + builder.add( + decodeQueryComponent(rawName), + decodeQueryComponent(rawValue), + ); } return builder.build(); } diff --git a/packages/core/src/http/response.ts b/packages/core/src/http/response.ts index 4f2b0b3..1f3b95e 100644 --- a/packages/core/src/http/response.ts +++ b/packages/core/src/http/response.ts @@ -25,12 +25,8 @@ let createResponse: ( * Status-range classification is reached through {@link Response.status} — `response.status.isSuccess`, * `response.status.isError`, and the rest (HTTP-11). * - * Owns the body's connection, released by {@link Response.close}. Teardown is `close()` only, with no - * `[Symbol.asyncDispose]`: the symbol postdates the declared `engines.node` floor (`>=18.17`), where the - * computed key evaluates to `undefined` and binds the method to the string `"undefined"` — wrong, - * silent, and only at run time — and its type reaches this package only through a dev-only global, so a - * consumer compiling against the published `.d.ts` on the same `lib` this package declares cannot build. - * Matches every Phase 2/3a resource-owning class. Revisit when the checkpoint's floor bump lands. + * Owns the body's connection, released by {@link Response.close}. Teardown is `close()` only. + * Revisit when a project-wide explicit resource management pass lands across all Phase 2/3a resource classes. * * @public */ diff --git a/packages/core/src/index.public.test.ts b/packages/core/src/index.public.test.ts index e8ca5ac..a020427 100644 --- a/packages/core/src/index.public.test.ts +++ b/packages/core/src/index.public.test.ts @@ -62,9 +62,65 @@ test('the SSE surface is publicly importable', async () => { } }); +test('the pagination surface is publicly importable', async () => { + const barrel = await import('./index.js'); + for (const name of [ + 'Paginator', + 'Page', + 'pageInfo', + 'cursorStrategy', + 'pageNumberStrategy', + 'linkHeaderStrategy', + 'paginateWithFetchers', + 'PaginationError', + ]) { + expect(barrel).toHaveProperty(name); + } +}); + test('the SSE parser internals stay private — publishing them would publish a way to break SSE-17', async () => { const barrel = await import('./index.js'); for (const name of ['SseParser', 'SseLineReader']) { expect(barrel).not.toHaveProperty(name); } }); + +test('the URL-manipulation internals stay private — one public query surface, not two', async () => { + const barrel = await import('./index.js'); + for (const name of [ + 'spliceQueryParam', + 'readQueryParam', + 'parseLinkHeader', + 'findNextLink', + ]) { + expect(barrel).not.toHaveProperty(name); + } +}); + +test('nothing under src/pagination/ imports serde (§12: the engine is serde-agnostic)', async () => { + const {readdirSync, readFileSync} = await import('node:fs'); + const paginationDir = new URL('./pagination/', import.meta.url); + const names = readdirSync(paginationDir).filter( + f => f.endsWith('.ts') && !f.endsWith('.test.ts'), + ); + const sourceOf = (name: string): string => + readFileSync(new URL(name, paginationDir), 'utf8'); + for (const name of names) { + const code = sourceOf(name).replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, ''); + expect(code).not.toMatch(/from\s+['"].*(serde|codec-json)/); + } +}); + +test('nothing under src/pagination/ uses URLSearchParams (PAGE-21)', async () => { + const {readdirSync, readFileSync} = await import('node:fs'); + const paginationDir = new URL('./pagination/', import.meta.url); + const names = readdirSync(paginationDir).filter( + f => f.endsWith('.ts') && !f.endsWith('.test.ts'), + ); + const sourceOf = (name: string): string => + readFileSync(new URL(name, paginationDir), 'utf8'); + for (const name of names) { + const code = sourceOf(name).replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, ''); + expect(code).not.toContain('URLSearchParams'); + } +}); diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 2acbdfb..3ade81f 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -217,3 +217,23 @@ export { typedSseStream, } from './sse/typed.js'; export type {MapperOutcome, SseMapper} from './sse/typed.js'; + +// Pagination (Phase 6c). The query splice and link tokenizer stay internal: publishing them would put a second +// URL-manipulation surface next to Phase 1's QueryParams, which is the confusion the one-encoder rule avoids. +export {Page, pageInfo} from './pagination/page.js'; +export type {PageInfo} from './pagination/page.js'; +export type {PaginationStrategy} from './pagination/strategy.js'; +export {Paginator} from './pagination/paginator.js'; +export type {PaginatorInit} from './pagination/paginator.js'; +export { + cursorStrategy, + linkHeaderStrategy, + pageNumberStrategy, +} from './pagination/strategies.js'; +export {paginateWithFetchers} from './pagination/fetchers.js'; +export type { + FetcherPage, + FetcherPaginationInit, + PagingOptions, +} from './pagination/fetchers.js'; +export {PaginationError} from './pagination/errors.js'; diff --git a/packages/core/src/pagination/cancellation.test.ts b/packages/core/src/pagination/cancellation.test.ts new file mode 100644 index 0000000..d2e86d8 --- /dev/null +++ b/packages/core/src/pagination/cancellation.test.ts @@ -0,0 +1,140 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/cancellation.test.ts +// Exercises: PAGE-25 (the signal reaches every exchange and halts the walk), PAGE-26 (page-granular +// cancellation; a fetched-but-undelivered page is dropped AND closed), PAGE-31 (no per-page recursion), +// PAGE-33 (a response that arrives after the abort is closed and discarded). +import {expect, test} from 'bun:test'; +import {FakeTransport, countingResponse} from '../testing/fake-transport.js'; +import {pageInfo} from './page.js'; +import {Paginator} from './paginator.js'; +import type {PaginationStrategy} from './strategy.js'; +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; + +const initialRequest = (): Request => + ({ + method: 'GET', + url: new URL('https://api.test/items'), + headers: {get: () => undefined}, + }) as unknown as Request; + +const transportOf = ( + pages: number, + onClose?: (index: number) => void, +): FakeTransport => + new FakeTransport( + Array.from({length: pages}, (_, i) => + countingResponse({ + body: `page-${String(i)}`, + onCancel: () => onClose?.(i), + }), + ), + ); + +const endless = (): PaginationStrategy => ({ + parse: (response: Response, template: Request) => + Promise.resolve( + pageInfo(['x'], { + method: template.method, + url: new URL(`${template.url.pathname}?page=next`, template.url), + } as Request), + ), +}); + +test('the signal is threaded into every page exchange (PAGE-25)', async () => { + const controller = new AbortController(); + const transport = transportOf(5); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: endless(), + maxPages: 3, + signal: controller.signal, + }); + for await (const page of paginator.pages()) { + void page; + } + expect(transport.sentSignals).toHaveLength(3); + expect(transport.sentSignals.every(s => s === controller.signal)).toBe(true); +}); + +test('aborting mid-walk stops the walk at the next page boundary (PAGE-25, PAGE-26)', async () => { + const controller = new AbortController(); + const transport = transportOf(10); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: endless(), + signal: controller.signal, + }); + + let delivered = 0; + for await (const page of paginator.pages()) { + void page; + delivered += 1; + if (delivered === 2) controller.abort(); + } + + // Pre-dispatch abort check ensures Page 3 is never dispatched. + expect(delivered).toBe(2); + expect(transport.sendCount).toBe(2); +}); + +test('a page fetched while abort is in flight is closed and discarded, never yielded (PAGE-26, PAGE-33)', async () => { + const controller = new AbortController(); + const closed: number[] = []; + let sendCount = 0; + const transport = { + send: () => { + sendCount += 1; + if (sendCount === 2) { + controller.abort(); + } + return Promise.resolve( + countingResponse({ + body: `page-${String(sendCount)}`, + onCancel: () => closed.push(sendCount), + }), + ); + }, + close: () => Promise.resolve(), + } as unknown as FakeTransport; + + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: endless(), + signal: controller.signal, + }); + + const delivered = []; + for await (const page of paginator.pages()) { + delivered.push(page); + } + + expect(delivered).toHaveLength(1); + expect(sendCount).toBe(2); + // Page 1 closed at exit, Page 2 closed by post-fetch abort check (PAGE-33). + expect(closed.sort()).toEqual([1, 2]); +}); + +test('thousands of immediately-resolved pages complete without stack growth (PAGE-31)', async () => { + const PAGES = 5000; + const transport = transportOf(PAGES); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: endless(), + maxPages: PAGES, + }); + + let count = 0; + for await (const page of paginator.pages()) { + void page; + count += 1; + } + + // A `for await` loop is iterative by construction — the engine structurally cannot recurse per page, which + // is PAGE-31's own sanctioned escape from building a trampoline. + expect(count).toBe(PAGES); +}); diff --git a/packages/core/src/pagination/errors.test.ts b/packages/core/src/pagination/errors.test.ts new file mode 100644 index 0000000..c03affa --- /dev/null +++ b/packages/core/src/pagination/errors.test.ts @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/errors.test.ts +// Exercises: PAGE-9 (cap validated at construction), PAGE-14 (re-iteration fails loudly). +import {expect, test} from 'bun:test'; +import {DexpaceError} from '../http/errors.js'; +import {PaginationError} from './errors.js'; + +test('sits directly under DexpaceError (two-level tree)', () => { + expect(new PaginationError('x')).toBeInstanceOf(DexpaceError); +}); + +test('name identifies the leaf in a stack trace', () => { + expect(new PaginationError('x').name).toBe('PaginationError'); +}); + +test('chains a cause when given one', () => { + const backing = new Error('root'); + expect(new PaginationError('x', {cause: backing}).cause).toBe(backing); +}); diff --git a/packages/core/src/pagination/errors.ts b/packages/core/src/pagination/errors.ts new file mode 100644 index 0000000..b02f1ac --- /dev/null +++ b/packages/core/src/pagination/errors.ts @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/errors.ts +import {DexpaceError} from '../http/errors.js'; + +/** + * A misuse or precondition failure of the pagination engine: a non-positive page cap at construction + * (PAGE-9), or a second iterator on the single-use page-level view (PAGE-14). + * + * Not used for transport, parse, or close failures — those propagate as whatever the underlying layer raised, + * because PAGE-28 requires the *original* cause to surface rather than a pagination-flavored wrapper. + * + * @public + */ +export class PaginationError extends DexpaceError { + // bun's coverage tool never marks a bodiless subclass's implicit constructor as covered + // (undercounts function coverage); an explicit forwarding constructor is instrumented + // correctly and keeps the file above the 80% function-coverage floor without changing behavior. + // eslint-disable-next-line @typescript-eslint/no-useless-constructor -- see comment above + constructor(message: string, options?: ErrorOptions) { + super(message, options); + } +} diff --git a/packages/core/src/pagination/fetchers.test.ts b/packages/core/src/pagination/fetchers.test.ts new file mode 100644 index 0000000..28c5797 --- /dev/null +++ b/packages/core/src/pagination/fetchers.test.ts @@ -0,0 +1,333 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/fetchers.test.ts +// Exercises: PAGE-34 (first fetcher runs once; next keys off nextLink with token fallback; blank link or +// undefined page terminates; a fetcher builds a page it does not close), PAGE-35 (one shared mutable options +// instance threaded through every call). +import {expect, test} from 'bun:test'; +import {Page} from './page.js'; +import {PaginationError} from './errors.js'; +import {paginateWithFetchers, type PagingOptions} from './fetchers.js'; +import type {Response} from '../http/response.js'; + +function fakePage(items: readonly T[], onClose: () => void): Page { + let closed = false; + const response = { + status: {code: 200}, + headers: {get: () => undefined}, + request: {}, + close(): Promise { + if (!closed) { + closed = true; + onClose(); + } + return Promise.resolve(); + }, + } as unknown as Response; + return new Page(response, items); +} + +test('the first fetcher runs exactly once and the next keys off nextLink (PAGE-34)', async () => { + let firstCalls = 0; + const nextLinks: string[] = []; + const iterable = paginateWithFetchers({ + first: () => { + firstCalls += 1; + return Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: '/p2', + }); + }, + next: link => { + nextLinks.push(link); + return Promise.resolve({page: fakePage(['b'], () => undefined)}); + }, + }); + + const seen = []; + for await (const page of iterable) seen.push(page.items[0]); + + expect(firstCalls).toBe(1); + expect(nextLinks).toEqual(['/p2']); + expect(seen).toEqual(['a', 'b']); +}); + +test('the continuation token is used only when no next link is present — link wins (PAGE-34)', async () => { + const keys: string[] = []; + let nextCalls = 0; + const iterable = paginateWithFetchers({ + // Page 1 offers BOTH a link and a token; the link must win. + first: () => + Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: '/p2', + continuationToken: 'tok-2', + }), + next: key => { + keys.push(key); + nextCalls += 1; + return nextCalls === 1 + ? Promise.resolve({ + page: fakePage(['b'], () => undefined), + // Page 2 offers ONLY a token; now the token must be used. + continuationToken: 'tok-3', + }) + : Promise.resolve(undefined); + }, + }); + + const seen = []; + for await (const page of iterable) seen.push(page.items[0]); + + expect(seen).toEqual(['a', 'b']); + expect(keys).toEqual(['/p2', 'tok-3']); +}); + +test('a blank, whitespace-only, or undefined nextLink ends the stream (PAGE-34)', async () => { + let calls = 0; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: ' ', + }), + next: () => { + calls += 1; + return Promise.resolve({page: fakePage(['b'], () => undefined)}); + }, + }); + + const seen = []; + for await (const page of iterable) seen.push(page.items[0]); + + expect(seen).toEqual(['a']); + expect(calls).toBe(0); +}); + +test('an undefined first-page result yields an empty stream (PAGE-34)', async () => { + const iterable = paginateWithFetchers({ + first: () => Promise.resolve(undefined), + next: () => Promise.resolve(undefined), + }); + + const seen = []; + for await (const page of iterable) seen.push(page); + + expect(seen).toEqual([]); +}); + +test('an undefined page from the next fetcher ends the stream (PAGE-34)', async () => { + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: '/p2', + }), + next: () => Promise.resolve(undefined), + }); + const seen = []; + for await (const page of iterable) seen.push(page.items[0]); + expect(seen).toEqual(['a']); +}); + +test('options bag is passed to first and next as the identical mutable instance (PAGE-35)', async () => { + const received: (PagingOptions | undefined)[] = []; + const iterable = paginateWithFetchers({ + first: options => { + received.push(options); + options.custom = 'stashed'; + return Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: '/p2', + }); + }, + next: (_link, options) => { + received.push(options); + return Promise.resolve({page: fakePage(['b'], () => undefined)}); + }, + }); + + for await (const page of iterable) { + void page; + } + + expect(received[0]).toBe(received[1]); + expect(received[1]?.custom).toBe('stashed'); +}); + +test('options.nextLink and options.continuationToken are populated before next() call (PAGE-34, PAGE-35)', async () => { + const optionsSeen: PagingOptions[] = []; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => undefined), + nextLink: '/p2', + continuationToken: 'tok-1', + }), + next: (_key, options) => { + optionsSeen.push({...options}); + return Promise.resolve(undefined); + }, + }); + + for await (const page of iterable) { + void page; + } + + expect(optionsSeen).toHaveLength(1); + expect(optionsSeen[0]?.nextLink).toBe('/p2'); + expect(optionsSeen[0]?.continuationToken).toBe('tok-1'); +}); + +test('pages are closed as the consumer advances and at exhaustion (PAGE-3, PAGE-12)', async () => { + const closed: string[] = []; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => closed.push('a')), + nextLink: '/p2', + }), + next: () => + Promise.resolve({page: fakePage(['b'], () => closed.push('b'))}), + }); + + for await (const page of iterable) { + void page; + } + + expect(closed).toEqual(['a', 'b']); +}); + +test('the cap bounds a fetcher pair that never terminates, fetching nothing extra (PAGE-9)', async () => { + const closed: string[] = []; + let calls = 0; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => closed.push('a')), + nextLink: '/loop', + }), + next: () => { + calls += 1; + const label = `x${String(calls)}`; + return Promise.resolve({ + page: fakePage([label], () => closed.push(label)), + nextLink: '/loop', + }); + }, + maxPages: 3, + }); + + let delivered = 0; + for await (const page of iterable) { + void page; + delivered += 1; + } + + expect(delivered).toBe(3); + // Three pages delivered means the fetcher ran twice, not three times: the third call would produce a fourth + // page the cap forbids delivering, and a page fetched but never delivered is a page nobody closes. + expect(calls).toBe(2); + // Every page that was fetched was also closed — no leak on the capped path. + expect(closed.sort()).toEqual(['a', 'x1', 'x2']); +}); + +test.each([0, -1, 1.5, NaN])( + 'non-positive integer maxPages throws PaginationError (PAGE-9)', + maxPages => { + expect(() => + paginateWithFetchers({ + first: () => Promise.resolve(undefined), + next: () => Promise.resolve(undefined), + maxPages, + }), + ).toThrow(PaginationError); + }, +); + +test('the fetcher view is single-use at the iterator level, and does not re-run first() (PAGE-14, PAGE-34)', async () => { + let firstCalls = 0; + const iterable = paginateWithFetchers({ + first: () => { + firstCalls += 1; + return Promise.resolve({page: fakePage(['a'], () => undefined)}); + }, + next: () => { + throw new Error('must not be called'); + }, + }); + + for await (const page of iterable) { + void page; + } + + let caughtView: unknown; + try { + for await (const page of iterable) { + void page; + } + } catch (e: unknown) { + caughtView = e; + } + expect(caughtView).toBeInstanceOf(PaginationError); + // PAGE-34 says the first-page fetcher runs exactly once. Without the guard a second loop would run it again. + expect(firstCalls).toBe(1); +}); + +test('a throwing next fetcher propagates its failure and closes previous page (PAGE-15, PAGE-28)', async () => { + const fetcherFailure = new Error('page 2 fetch blew up'); + let page1Closed = false; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => { + page1Closed = true; + }), + nextLink: '/p2', + }), + next: () => Promise.reject(fetcherFailure), + }); + + let caught: unknown; + try { + for await (const page of iterable) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(fetcherFailure); + expect(page1Closed).toBe(true); +}); + +test('a close failure while advancing stops the walk before next fetch (PAGE-12, PAGE-15, PAGE-27)', async () => { + const closePreviousFailure = new Error('previous page close failed'); + let nextCalls = 0; + const iterable = paginateWithFetchers({ + first: () => + Promise.resolve({ + page: fakePage(['a'], () => { + throw closePreviousFailure; + }), + nextLink: '/p2', + }), + next: () => { + nextCalls += 1; + return Promise.resolve({ + page: fakePage(['b'], () => undefined), + }); + }, + }); + + let caught: unknown; + try { + for await (const page of iterable) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(closePreviousFailure); + expect(nextCalls).toBe(0); +}); diff --git a/packages/core/src/pagination/fetchers.ts b/packages/core/src/pagination/fetchers.ts new file mode 100644 index 0000000..f73b3eb --- /dev/null +++ b/packages/core/src/pagination/fetchers.ts @@ -0,0 +1,154 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/fetchers.ts +import {invariant} from '../invariant.js'; +import {PaginationError} from './errors.js'; +import type {Page} from './page.js'; + +/** + * A mutable bag threaded through **every** fetcher call in one walk (PAGE-35). + * + * The same instance is passed each time, so a custom retriever can stash cursor or auth state between pages. + * Cross-call mutation visibility is the *point*, not a hazard to defend against — it is documented here rather + * than designed away. Single-consumer; needs no synchronization. + * + * @public + */ +export interface PagingOptions { + /** The RFC 8288 link target for the next page (PAGE-34). */ + nextLink?: string | undefined; + /** The continuation/cursor token fallback for the next page (PAGE-34). */ + continuationToken?: string | undefined; + /** Custom per-walk state stashed by callers across page requests (PAGE-35). */ + [key: string]: unknown; +} + +/** + * What a fetcher returns: a page it built and does not close, plus how to reach the one after it. + * + * @public + */ +export interface FetcherPage { + /** The constructed page, which owns its underlying response and will be closed by the engine (PAGE-34). */ + readonly page: Page; + /** The RFC 8288 next link, taking priority over continuationToken (PAGE-34). */ + readonly nextLink?: string | undefined; + /** The continuation token fallback used when nextLink is absent (PAGE-34). */ + readonly continuationToken?: string | undefined; +} + +/** + * Initialization options for {@link paginateWithFetchers}. + * + * @public + */ +export interface FetcherPaginationInit { + /** Called exactly once, at the start of the walk. Return `undefined` for an empty stream. */ + first: (options: PagingOptions) => Promise | undefined>; + /** + * Called with the previous page's next link, or — only when no link was present — its continuation token. + * Return `undefined` to end the stream. + */ + next: ( + key: string, + options: PagingOptions, + ) => Promise | undefined>; + /** Maximum pages delivered. Unbounded when omitted. */ + maxPages?: number | undefined; +} + +/** + * Drive pagination from caller-supplied per-page fetchers instead of a strategy (PAGE-34). + * + * **Ownership**: each fetcher builds a {@link (Page:class)} that owns its response and must **not** close it — + * ownership transfers to the page, and this engine closes it as the consumer advances and at exhaustion. A + * fetcher that throws *before* building the page still owns whatever response it opened; this engine never saw + * it and has no handle with which to close it. + * + * **Next link wins** over the continuation token. A blank or whitespace-only link with no fallback token ends + * the stream, as does an `undefined` return from either fetcher — an `undefined` first page yields an empty + * stream rather than an error. + * + * **Single-use** (PAGE-14). This is a page-level view, so its iterator may be obtained at most once; a second + * `for await` over the same returned value throws rather than silently restarting. Without the guard a second + * loop would re-run `first()`, breaking PAGE-34's "exactly once" and double-consuming the walk. Call + * `paginateWithFetchers()` again for a fresh walk — the same restart path `Paginator.pages()` offers. + * + * @public + */ +export function paginateWithFetchers( + init: FetcherPaginationInit, +): AsyncIterable> { + if ( + init.maxPages !== undefined && + (!Number.isInteger(init.maxPages) || init.maxPages <= 0) + ) { + throw new PaginationError( + `maxPages must be a positive integer; received ${String(init.maxPages)}`, + ); + } + invariant( + typeof init.first === 'function', + 'paginateWithFetchers requires a first-page fetcher', + ); + invariant( + typeof init.next === 'function', + 'paginateWithFetchers requires a next-page fetcher', + ); + + let iteratorTaken = false; + + return { + async *[Symbol.asyncIterator](): AsyncGenerator> { + if (iteratorTaken) { + throw new PaginationError( + 'the fetcher pagination view is single-use; its iterator may be obtained at most once', + ); + } + iteratorTaken = true; + yield* driveFetchers(init); + }, + }; +} + +async function* driveFetchers( + init: FetcherPaginationInit, +): AsyncGenerator> { + const options: PagingOptions = {}; + let held: Page | undefined; + let delivered = 0; + + try { + let current: FetcherPage | undefined = await init.first(options); + + while (current !== undefined) { + const page: Page = current.page; + held = page; + delivered += 1; + yield page; + + // PAGE-9: stop *before* fetching the page that would exceed the cap. + if (init.maxPages !== undefined && delivered >= init.maxPages) return; + + const key: string | undefined = nextKey(current); + if (key === undefined) return; + + // PAGE-12: release previous page before calling the next fetcher to eliminate connection overlap. + held = undefined; + await page.close(); + + options.nextLink = current.nextLink; + options.continuationToken = current.continuationToken; + current = await init.next(key, options); + } + } finally { + if (held !== undefined) await held.close(); + } +} + +/** PAGE-34: the next link wins; the continuation token is a fallback only when no usable link is present. */ +function nextKey(page: FetcherPage): string | undefined { + const link = page.nextLink?.trim(); + if (link !== undefined && link.length > 0) return link; + const token = page.continuationToken?.trim(); + return token !== undefined && token.length > 0 ? token : undefined; +} diff --git a/packages/core/src/pagination/lifecycle.test.ts b/packages/core/src/pagination/lifecycle.test.ts new file mode 100644 index 0000000..5ea37ab --- /dev/null +++ b/packages/core/src/pagination/lifecycle.test.ts @@ -0,0 +1,453 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/lifecycle.test.ts +// Exercises: PAGE-11 (close BEFORE yielding items — the assertion appendix B does not make), PAGE-12 +// (close-on-abandon), PAGE-13 (parse failure closes inline, close error suppressed), PAGE-14 (single-use page +// view), PAGE-15 (close errors surface), PAGE-27 (exactly once on every path), PAGE-32 (consumer throw keeps +// consumer error primary, discarding return-phase close error). +import {expect, test} from 'bun:test'; +import {FakeTransport, countingResponse} from '../testing/fake-transport.js'; +import {IoError} from '../io/errors.js'; +import {PaginationError} from './errors.js'; +import {pageInfo, type PageInfo} from './page.js'; +import {Paginator} from './paginator.js'; +import type {PaginationStrategy} from './strategy.js'; +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; +import type {SuppressedErrorLike} from '../suppress.js'; + +const requestAt = (href: string): Request => + ({ + url: new URL(href), + newBuilder() { + let target = new URL(href); + return { + url(next: URL) { + target = next; + return this; + }, + build: () => requestAt(target.href), + }; + }, + }) as unknown as Request; + +const initialRequest = (): Request => + requestAt('https://api.test/items?page=1'); + +function twoPageStrategy(): PaginationStrategy { + return { + parse(_response: Response, template: Request): Promise> { + const page = Number(template.url.searchParams.get('page') ?? '1'); + const items = [ + `p${String(page)}a`, + `p${String(page)}b`, + `p${String(page)}c`, + ]; + if (page >= 2) return Promise.resolve(pageInfo(items)); + const next = template + .newBuilder() + .url(new URL(`https://api.test/items?page=${String(page + 1)}`)) + .build(); + return Promise.resolve(pageInfo(items, next)); + }, + }; +} + +function transportOf( + pages: number, + onClose?: (index: number) => void, +): FakeTransport { + return new FakeTransport( + Array.from({length: pages}, (_unused, index) => + countingResponse({ + status: 200, + headers: {'X-Page': String(index + 1)}, + body: '{}', + onCancel: () => onClose?.(index), + }), + ), + ); +} + +test('the item view closes a page BEFORE yielding any of its items (PAGE-11)', async () => { + const events: string[] = []; + const transport = transportOf(2, index => + events.push(`close:${String(index)}`), + ); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + for await (const item of paginator.items()) { + events.push(`item:${item}`); + } + + // The close for page 0 must precede every one of its items. Under the design doc's illustrative snippet + // (close in a `finally`, after `yield*`) this assertion fails while PAGE-11's own checklist test still passes. + expect(events.indexOf('close:0')).toBeLessThan(events.indexOf('item:p1a')); + expect(events.indexOf('close:1')).toBeLessThan(events.indexOf('item:p2a')); +}); + +test('taking one item and stopping closes that page and fetches no second page (PAGE-11)', async () => { + const closed: number[] = []; + const transport = transportOf(2, index => closed.push(index)); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + for await (const item of paginator.items()) { + void item; + break; + } + + expect(closed).toEqual([0]); + expect(transport.sendCount).toBe(1); +}); + +test('breaking out of the page view closes the held page (PAGE-12)', async () => { + const closed: number[] = []; + const transport = transportOf(2, index => closed.push(index)); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + for await (const page of paginator.pages()) { + void page; + break; + } + + expect(closed).toEqual([0]); +}); + +test('advancing the page view closes the previous page (PAGE-12)', async () => { + const closed: number[] = []; + const transport = transportOf(2, index => closed.push(index)); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + const seen = []; + for await (const page of paginator.pages()) seen.push(page); + + expect(seen).toHaveLength(2); + expect(closed).toEqual([0, 1]); +}); + +test('a second pages() call returns a fresh, independent view — the restart PAGE-14 names', async () => { + // PAGE-14's own recovery clause: "a caller restarts pagination by requesting a fresh view from the engine." + // Guarding pages() itself would block that path AND make the engine stateful, which PAGE-8 forbids. + const transport = transportOf(4); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + const first = []; + for await (const page of paginator.pages()) first.push(page.items[0]); + const second = []; + for await (const page of paginator.pages()) second.push(page.items[0]); + + expect(second).toEqual(first); + expect(transport.sendCount).toBe(4); +}); + +test('the page view is single-use at the ITERATOR level too (PAGE-14)', async () => { + // The guard that matters. `for await` calls Symbol.asyncIterator afresh every time, so a view guarded only at + // the pages() level would let a second loop over the *same* view silently restart the whole walk — the exact + // "silently restart" PAGE-14 forbids, and invisible to the test above. + const transport = transportOf(2); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + const view = paginator.pages(); + + for await (const page of view) { + void page; + } + const sendsAfterFirstPass = transport.sendCount; + + let caught: unknown; + try { + for await (const page of view) { + void page; + } + } catch (e: unknown) { + caught = e; + } + expect(caught).toBeInstanceOf(PaginationError); + expect(transport.sendCount).toBe(sendsAfterFirstPass); +}); + +test('a transport failure surfaces the original cause, unwrapped (PAGE-28)', async () => { + const transportFailure = new IoError('connection reset'); + const transport = { + send: () => Promise.reject(transportFailure), + } as unknown as FakeTransport; + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + // No pagination-flavored wrapper: PAGE-28 wants the cause the caller can actually act on. + expect(caught).toBe(transportFailure); + expect(caught).not.toBeInstanceOf(PaginationError); +}); + +test('advancing closes the held page before next send, and surfaces close error (PAGE-12, PAGE-15)', async () => { + const closeFailure = new IoError('close failed'); + let sends = 0; + const transport = { + send: () => { + sends += 1; + return Promise.resolve( + countingResponse({ + status: 200, + headers: {'X-Page': '1'}, + body: '{}', + onCancel: () => { + throw closeFailure; + }, + }), + ); + }, + } as unknown as FakeTransport; + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(closeFailure); + expect(sends).toBe(1); +}); + +test('a parse failure closes the response inline and propagates the parse error (PAGE-13)', async () => { + const boom = new Error('malformed page'); + const closed: number[] = []; + const transport = transportOf(1, index => closed.push(index)); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: { + parse(): Promise { + return Promise.reject(boom); + }, + }, + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(boom); + expect(closed).toEqual([0]); +}); + +test('a close failure during a parse failure is suppressed, not masking (PAGE-13)', async () => { + const parseFailure = new Error('malformed page'); + const closeFailure = new IoError('close failed'); + const transport = new FakeTransport([ + countingResponse({ + status: 200, + headers: {}, + body: '{}', + onCancel: () => { + throw closeFailure; + }, + }), + ]); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: { + parse(): Promise { + return Promise.reject(parseFailure); + }, + }, + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect((caught as SuppressedErrorLike).name).toBe('SuppressedError'); + expect((caught as SuppressedErrorLike).error).toBe(parseFailure); + expect((caught as SuppressedErrorLike).suppressed).toBe(closeFailure); +}); + +test('a close error while releasing a held page surfaces rather than being swallowed (PAGE-15)', async () => { + const closeFailure = new IoError('close failed'); + const transport = new FakeTransport([ + countingResponse({ + status: 200, + headers: {'X-Page': '1'}, + body: '{}', + onCancel: () => { + throw closeFailure; + }, + }), + ]); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: { + parse: () => Promise.resolve(pageInfo(['only'])), + }, + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(closeFailure); +}); + +test('a close failure while advancing stops walk before dispatching next request (PAGE-12, PAGE-15, PAGE-27)', async () => { + const closePreviousFailure = new IoError('previous page close failed'); + const secondResponseClosed: number[] = []; + const transport = new FakeTransport([ + countingResponse({ + status: 200, + headers: {'X-Page': '1'}, + body: '{}', + onCancel: () => { + throw closePreviousFailure; + }, + }), + countingResponse({ + status: 200, + headers: {'X-Page': '2'}, + body: '{}', + onCancel: () => { + secondResponseClosed.push(2); + }, + }), + ]); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + let caught: unknown; + try { + for await (const page of paginator.pages()) { + void page; + } + } catch (e: unknown) { + caught = e; + } + + expect(caught).toBe(closePreviousFailure); + expect(transport.sendCount).toBe(1); + expect(secondResponseClosed).toEqual([]); +}); + +test.each([ + [ + 'full drain of the page view', + 2, + async (paginator: Paginator) => { + for await (const page of paginator.pages()) { + void page; + } + }, + ], + [ + 'full drain of the item view', + 2, + async (paginator: Paginator) => { + for await (const item of paginator.items()) { + void item; + } + }, + ], + [ + 'early break from the page view', + 1, + async (paginator: Paginator) => { + for await (const page of paginator.pages()) { + void page; + break; + } + }, + ], + [ + 'consumer throws mid-iteration', + 1, + async (paginator: Paginator) => { + try { + for await (const page of paginator.pages()) { + void page; + throw new Error('consumer blew up'); + } + } catch { + /* expected */ + } + }, + ], +])( + 'every response closes exactly once: %s (PAGE-27)', + async (_name, expectedFetches, drive) => { + const closeCounts = new Map(); + const transport = transportOf(2, index => { + closeCounts.set(index, (closeCounts.get(index) ?? 0) + 1); + }); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: twoPageStrategy(), + }); + + await drive(paginator); + + expect(closeCounts.size).toBe(expectedFetches); + for (let i = 0; i < expectedFetches; i++) { + expect(closeCounts.get(i)).toBe(1); + } + }, +); diff --git a/packages/core/src/pagination/link-header.test.ts b/packages/core/src/pagination/link-header.test.ts new file mode 100644 index 0000000..8a169bd --- /dev/null +++ b/packages/core/src/pagination/link-header.test.ts @@ -0,0 +1,78 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/link-header.test.ts +// Exercises: PAGE-18 (RFC 5988/8288 link-value parsing — commas inside <> or quotes do not split, quoted-pair +// escapes, quoted/unquoted rel, multi-token rel, case-insensitive `next`), PAGE-20 (multiple header instances). +import {expect, test} from 'bun:test'; +import {findNextLink, parseLinkHeader} from './link-header.js'; + +test('a simple rel=next is found', () => { + expect(findNextLink(['; rel="next"'])).toBe('/p?page=2'); +}); + +test('an unquoted rel works (PAGE-18)', () => { + expect(findNextLink(['; rel=next'])).toBe('/p?page=2'); +}); + +test('rel matching is case-insensitive (PAGE-18)', () => { + expect(findNextLink(['; rel="NEXT"'])).toBe('/p?page=2'); +}); + +test('a multi-token rel containing next matches (PAGE-18)', () => { + expect(findNextLink(['; rel="prev next last"'])).toBe('/p?page=2'); +}); + +test('a tab-separated multi-token rel matches (PAGE-18)', () => { + expect(findNextLink(['; rel="prev\tnext"'])).toBe('/p?page=2'); +}); + +test('the FIRST link-value whose rel contains next wins (PAGE-18)', () => { + expect(findNextLink(['; rel="next", ; rel="next"'])).toBe('/a'); +}); + +test('rel=prev and rel=last decoys are skipped (PAGE-18)', () => { + expect( + findNextLink(['; rel="prev", ; rel="last", ; rel="next"']), + ).toBe('/c'); +}); + +test('a comma inside the angle-bracketed URL does not split link-values (PAGE-18)', () => { + expect(findNextLink(['; rel="next"'])).toBe('/p?ids=1,2,3'); +}); + +test('a comma inside a quoted parameter value does not split link-values (PAGE-18)', () => { + const parsed = parseLinkHeader( + '; title="one, two"; rel="next", ; rel="prev"', + ); + expect(parsed).toHaveLength(2); + expect(parsed[0]?.target).toBe('/a'); +}); + +test('a quoted-pair escape is honored (PAGE-18)', () => { + const parsed = parseLinkHeader('; title="say \\"hi\\", ok"; rel="next"'); + expect(parsed).toHaveLength(1); + expect(parsed[0]?.rel).toContain('next'); +}); + +test('no Link header means end of stream (PAGE-18)', () => { + expect(findNextLink([])).toBeUndefined(); +}); + +test('a Link header with no rel=next means end of stream (PAGE-18)', () => { + expect(findNextLink(['; rel="prev"'])).toBeUndefined(); +}); + +test('multiple separate Link header instances are normalized by concatenation (PAGE-20)', () => { + expect(findNextLink(['; rel="last"', '; rel="next"'])).toBe('/b'); +}); + +test('an empty header set maps to no next link (PAGE-20)', () => { + expect(findNextLink([''])).toBeUndefined(); +}); + +test('surrounding whitespace is tolerated', () => { + expect( + findNextLink([ + ' < /p?page=2 > ; rel = "next" '.replace(/ (?=[/>])|(?<=<) /g, ''), + ]), + ).toBe('/p?page=2'); +}); diff --git a/packages/core/src/pagination/link-header.ts b/packages/core/src/pagination/link-header.ts new file mode 100644 index 0000000..52950f4 --- /dev/null +++ b/packages/core/src/pagination/link-header.ts @@ -0,0 +1,117 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/link-header.ts + +export interface LinkValue { + /** The raw target inside the angle brackets, unresolved. */ + readonly target: string; + /** The `rel` tokens, lowercased and split on whitespace. Empty when the link-value carried no `rel`. */ + readonly rel: readonly string[]; +} + +/** + * Parse an RFC 5988/8288 `Link` header into its link-values (PAGE-18). + * + * A regular expression is the wrong tool here and a hand-rolled scanner is the right one, because the + * separator rules are context-sensitive in two directions at once: a comma splits link-values **only** outside + * both angle brackets and quoted strings, and a semicolon splits parameters under the same condition. A quoted + * string additionally supports quoted-pair escapes (`\"`), so quote tracking cannot be a simple toggle. + * + * @internal + */ +export function parseLinkHeader(value: string): readonly LinkValue[] { + const out: LinkValue[] = []; + for (const raw of splitTopLevel(value, ',')) { + const parsed = parseOne(raw); + if (parsed !== undefined) out.push(parsed); + } + return out; +} + +/** + * The first target whose `rel` contains the token `next`, case-insensitively (PAGE-18). + * + * Multiple `Link` header instances are normalized by concatenation before parsing (PAGE-20), which is exactly + * what the RFC's own list semantics allow. An empty header set maps to no next link. + * + * @internal + */ +export function findNextLink( + headerValues: readonly string[], +): string | undefined { + const combined = headerValues.filter(v => v.trim().length > 0).join(', '); + if (combined.length === 0) return undefined; + for (const link of parseLinkHeader(combined)) { + if (link.rel.includes('next')) return link.target; + } + return undefined; +} + +function parseOne(raw: string): LinkValue | undefined { + const trimmed = raw.trim(); + const open = trimmed.indexOf('<'); + const close = trimmed.indexOf('>', open + 1); + if (open === -1 || close === -1) return undefined; + + const target = trimmed.slice(open + 1, close).trim(); + const rel: string[] = []; + + for (const parameter of splitTopLevel(trimmed.slice(close + 1), ';')) { + const eq = parameter.indexOf('='); + if (eq === -1) continue; + if (parameter.slice(0, eq).trim().toLowerCase() !== 'rel') continue; + // `rel` may be quoted or unquoted, and a quoted value may list several whitespace-separated types. + rel.push( + ...unquote(parameter.slice(eq + 1).trim()) + .toLowerCase() + .split(/[\s]+/) + .filter(t => t.length > 0), + ); + } + + return {target, rel: Object.freeze(rel)}; +} + +/** Split on `separator` only at depth zero — outside `<...>` and outside a quoted string. */ +function splitTopLevel(input: string, separator: string): string[] { + const parts: string[] = []; + let current = ''; + let inAngle = false; + let inQuotes = false; + let escaped = false; + + for (const char of input) { + if (escaped) { + current += char; + escaped = false; + continue; + } + if (inQuotes && char === '\\') { + current += char; + escaped = true; + continue; + } + if (char === '"') { + inQuotes = !inQuotes; + current += char; + continue; + } + if (!inQuotes && char === '<') inAngle = true; + else if (!inQuotes && char === '>') inAngle = false; + + if (char === separator && !inAngle && !inQuotes) { + parts.push(current); + current = ''; + continue; + } + current += char; + } + parts.push(current); + return parts.filter(part => part.trim().length > 0); +} + +/** Strip surrounding double quotes and unescape quoted pairs. */ +function unquote(value: string): string { + if (!value.startsWith('"') || !value.endsWith('"') || value.length < 2) + return value; + return value.slice(1, -1).replace(/\\(.)/g, '$1'); +} diff --git a/packages/core/src/pagination/page.test.ts b/packages/core/src/pagination/page.test.ts new file mode 100644 index 0000000..3a3b230 --- /dev/null +++ b/packages/core/src/pagination/page.test.ts @@ -0,0 +1,102 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/page.test.ts +// Exercises: PAGE-2 (items and metadata survive close; items never null), PAGE-3 (one owned response, closed +// exactly once), PAGE-4 (PageInfo shape, undefined next-request is the end signal). +import {expect, test} from 'bun:test'; +import {Page, pageInfo} from './page.js'; + +function fakeResponse(): { + response: Parameters[0]; + closes: () => number; +} { + let closeCount = 0; + let closing: Promise | undefined; + const response = { + status: {code: 200}, + headers: { + get: (n: string) => (n.toLowerCase() === 'x-total' ? '42' : undefined), + }, + request: {method: 'GET'}, + async close(): Promise { + closing ??= Promise.resolve().then(() => { + closeCount += 1; + }); + return closing; + }, + } as unknown as Parameters[0]; + return {response, closes: () => closeCount}; +} + +const makePage = ( + response: ConstructorParameters>[0], + items: readonly T[], +): Page => new Page(response, items); + +test('items and derived metadata remain readable after close (PAGE-2)', async () => { + const {response} = fakeResponse(); + const page = makePage(response, [1, 2, 3]); + await page.close(); + expect(page.items).toEqual([1, 2, 3]); + expect(page.status.code).toBe(200); + expect(page.headers.get('X-Total')).toBe('42'); + expect(page.request).toBeDefined(); +}); + +test('items are never null and are frozen (PAGE-2)', () => { + const {response} = fakeResponse(); + const page = makePage(response, []); + expect(page.items).toEqual([]); + expect(Object.isFrozen(page.items)).toBe(true); +}); + +test('the items list is defensively copied from the caller (PAGE-2)', () => { + const {response} = fakeResponse(); + const supplied = [1, 2]; + const page = makePage(response, supplied); + supplied.push(3); + expect(page.items).toEqual([1, 2]); +}); + +test('close releases the owned response exactly once, and is idempotent (PAGE-3)', async () => { + const {response, closes} = fakeResponse(); + const page = makePage(response, [1]); + await page.close(); + await page.close(); + await page.close(); + expect(closes()).toBe(1); +}); + +test('pageInfo with no next request signals end of stream (PAGE-4)', () => { + expect(pageInfo([1, 2]).nextRequest).toBeUndefined(); +}); + +test('pageInfo carries items plus a next request, both frozen (PAGE-4)', () => { + const next = {method: 'GET'} as never; + const info = pageInfo([1], next); + expect(info.items).toEqual([1]); + expect(info.nextRequest).toBe(next); + expect(Object.isFrozen(info)).toBe(true); +}); + +test('an empty items list with a next request is a valid non-terminal page (PAGE-4)', () => { + const next = {method: 'GET'} as never; + const info = pageInfo([], next); + expect(info.items).toEqual([]); + expect(info.nextRequest).toBe(next); +}); + +test('await using releases the page via Symbol.asyncDispose (PAGE-3, PAGE-12)', async () => { + const {response, closes} = fakeResponse(); + const page = makePage(response, [1]); + + { + await using scoped = page; + expect(scoped.items).toEqual([1]); + expect(closes()).toBe(0); + } + expect(closes()).toBe(1); + + // Dispose delegates to close, so it inherits Response.close()'s idempotence rather than adding a second guard. + await page.close(); + expect(closes()).toBe(1); +}); diff --git a/packages/core/src/pagination/page.ts b/packages/core/src/pagination/page.ts new file mode 100644 index 0000000..578beb5 --- /dev/null +++ b/packages/core/src/pagination/page.ts @@ -0,0 +1,103 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/page.ts +import type {Headers} from '../http/headers.js'; +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; +import type {Status} from '../http/status.js'; +import {invariant} from '../invariant.js'; + +/** + * A pagination strategy's parse output: the items on this page plus the request that fetches the next one + * (PAGE-4). + * + * `nextRequest === undefined` is the **single, exclusive** end-of-stream signal the engine recognizes. A + * strategy must never signal termination by throwing or through a side channel, and an empty `items` list + * paired with a defined `nextRequest` is a perfectly valid non-terminal page. + * + * @public + */ +export interface PageInfo { + /** The materialized items on this page (PAGE-2). */ + readonly items: readonly T[]; + /** The request that fetches the next page, or `undefined` to signal end of stream (PAGE-4). */ + readonly nextRequest: Request | undefined; +} + +/** + * Construct a frozen {@link PageInfo}. Omit `nextRequest` to signal end of stream. + * + * @public + */ +export function pageInfo( + items: readonly T[], + nextRequest?: Request, +): PageInfo { + return Object.freeze({items: Object.freeze([...items]), nextRequest}); +} + +/** + * One page of results, owning exactly one underlying response (PAGE-2, PAGE-3). + * + * State is split by lifetime, which is the whole point of the type: the materialized item list and the derived + * status, headers, and originating request are captured at construction and **remain readable after close** — + * only the raw body and its connection become invalid. Reading `page.status` after `await page.close()` is + * supported, not a bug. + * + * Whoever pulls a page owns closing it. A component that hands a caller a live page — a first-page fetcher, for + * instance — must **not** close the response itself; ownership transfers to the page. + * + * A class rather than a frozen object because it owns a resource with a lifecycle and an idempotent close, + * which is `styleguide/typescript/06` §6.3's test for a class. + * + * @public + */ +export class Page implements AsyncDisposable { + /** Materialized, frozen items that remain readable after close (PAGE-2). */ + readonly items: readonly T[]; + /** The HTTP response status code and reason phrase (PAGE-1). */ + readonly status: Status; + /** The HTTP response headers (PAGE-1). */ + readonly headers: Headers; + /** The executed request that produced this page (PAGE-1). */ + readonly request: Request; + // `#private` rather than the styleguide's default `private` (styleguide 6.6): `Page` is a *published* type + // holding a live connection, and `private` is compile-time-only — a consumer could reach the response through + // bracket access and close or re-read it behind the engine's back, breaking PAGE-3's single-owner rule and + // PAGE-27's close-exactly-once. Runtime unreachability is the requirement here, not just encapsulation. + readonly #response: Response; + + constructor(response: Response, items: readonly T[]) { + invariant( + (response as unknown) !== undefined, + 'a Page must own a response (PAGE-3)', + ); + invariant( + (items as unknown) !== undefined, + 'a Page’s items must never be null (PAGE-2)', + ); + + this.#response = response; + // Captured now, so they outlive the response (PAGE-2). Copied so a caller's later mutation cannot reach in. + this.items = Object.freeze([...items]); + this.status = response.status; + this.headers = response.headers; + this.request = response.request; + } + + /** + * Release the underlying response's body and connection (PAGE-3). + * + * Idempotent, by delegation: Phase 3b's `Response.close()` is already close-once, so this adds no second + * guard that could disagree with it. + */ + async close(): Promise { + await this.#response.close(); + } + + /** + * Scoped teardown for `await using`, delegating to {@link Page.close} (PAGE-12). + */ + async [Symbol.asyncDispose](): Promise { + await this.close(); + } +} diff --git a/packages/core/src/pagination/paginator.test.ts b/packages/core/src/pagination/paginator.test.ts new file mode 100644 index 0000000..7a29831 --- /dev/null +++ b/packages/core/src/pagination/paginator.test.ts @@ -0,0 +1,226 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/paginator.test.ts +// Exercises: PAGE-1 (both views over one walk, server order across boundaries), PAGE-6 (page-lazy, zero +// exchanges before the first probe), PAGE-7 (forward-only, idempotent end probes), PAGE-8 (independent +// iterations), PAGE-9/PAGE-10 (cap), PAGE-36 (options on every page). +import {expect, test} from 'bun:test'; +import {RequestOptions} from '../http/request-options.js'; +import {FakeTransport, countingResponse} from '../testing/fake-transport.js'; +import {pageInfo, type PageInfo} from './page.js'; +import {Paginator} from './paginator.js'; +import {PaginationError} from './errors.js'; +import type {PaginationStrategy} from './strategy.js'; +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; + +/** Three pages of two items each, then end. Reads a page number off a header the FakeTransport stamps. */ +function threePageStrategy(): PaginationStrategy { + return { + parse(_response: Response, template: Request): Promise> { + const page = Number(template.url.searchParams.get('page') ?? '1'); + const items = [`p${String(page)}i1`, `p${String(page)}i2`]; + if (page >= 3) return Promise.resolve(pageInfo(items)); + const next = template + .newBuilder() + .url(new URL(`https://api.test/items?page=${String(page + 1)}`)) + .build(); + return Promise.resolve(pageInfo(items, next)); + }, + }; +} + +/** A server that never advances: every page reports another page after it. */ +function neverEndingStrategy(): PaginationStrategy { + return { + parse(_response: Response, template: Request): Promise> { + return Promise.resolve(pageInfo(['x'], template)); + }, + }; +} + +function transportOf(pages: number): FakeTransport { + return new FakeTransport( + Array.from({length: pages}, (_unused, index) => + countingResponse({ + status: 200, + headers: {'X-Page': String(index + 1)}, + body: '{}', + }), + ), + ); +} + +/** + * A `Request` stand-in carrying the two members the engine and the strategies actually touch: `url`, and a + * `newBuilder()` chain for `PAGE-23`'s swap-only-the-URL rewrite. + * + * `newBuilder()` is not optional here — `threePageStrategy` below calls it on every non-terminal page, so a bare + * `{url}` cast would fail on the first parse with `template.newBuilder is not a function`, in every test in this + * file that walks more than one page. + */ +const requestAt = (href: string): Request => + ({ + url: new URL(href), + newBuilder() { + let target = new URL(href); + return { + url(next: URL) { + target = next; + return this; + }, + build: () => requestAt(target.href), + }; + }, + }) as unknown as Request; + +const initialRequest = (): Request => + requestAt('https://api.test/items?page=1'); + +test('the item view flattens all pages in server order (PAGE-1)', async () => { + const paginator = new Paginator({ + transport: transportOf(3), + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + const seen: string[] = []; + for await (const item of paginator.items()) seen.push(item); + expect(seen).toEqual(['p1i1', 'p1i2', 'p2i1', 'p2i2', 'p3i1', 'p3i2']); +}); + +test('the page view yields exactly three pages with their own status and headers (PAGE-1)', async () => { + const paginator = new Paginator({ + transport: transportOf(3), + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + const pages = []; + for await (const page of paginator.pages()) pages.push(page); + expect(pages).toHaveLength(3); + expect(pages.map(p => p.headers.get('X-Page'))).toEqual(['1', '2', '3']); + expect(pages[0]?.status.code).toBe(200); +}); + +test('constructing the paginator and obtaining the iterator trigger zero exchanges (PAGE-6)', async () => { + const transport = transportOf(3); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + const iterable = paginator.items(); + const iterator = iterable[Symbol.asyncIterator](); + expect(transport.sendCount).toBe(0); + + await iterator.next(); + expect(transport.sendCount).toBe(1); +}); + +test('exactly one exchange occurs per page consumed (PAGE-6)', async () => { + const transport = transportOf(3); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + for await (const page of paginator.pages()) { + void page; + } + expect(transport.sendCount).toBe(3); +}); + +test('no exchange happens past the terminal page, and end probes are idempotent (PAGE-7)', async () => { + const transport = transportOf(3); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + const iterator = paginator.items()[Symbol.asyncIterator](); + while (!(await iterator.next()).done) { + /* drain */ + } + expect((await iterator.next()).done).toBe(true); + expect((await iterator.next()).done).toBe(true); + expect(transport.sendCount).toBe(3); +}); + +test('two independent iterations each drive a full fetch sequence with equal results (PAGE-8)', async () => { + const transport = transportOf(6); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: threePageStrategy(), + }); + const first: string[] = []; + for await (const item of paginator.items()) first.push(item); + const second: string[] = []; + for await (const item of paginator.items()) second.push(item); + expect(second).toEqual(first); + expect(transport.sendCount).toBe(6); +}); + +test('the cap stops a non-advancing server at exactly N exchanges (PAGE-9)', async () => { + const transport = transportOf(10); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: neverEndingStrategy(), + maxPages: 4, + }); + for await (const page of paginator.pages()) { + void page; + } + expect(transport.sendCount).toBe(4); +}); + +test.each([0, -1, 1.5, Number.NaN])( + 'a cap of %p is rejected at construction, not lazily (PAGE-9)', + maxPages => { + expect( + () => + new Paginator({ + transport: transportOf(1), + initialRequest: initialRequest(), + strategy: threePageStrategy(), + maxPages: maxPages, + }), + ).toThrow(PaginationError); + }, +); + +test('the default cap is effectively unbounded (PAGE-10)', async () => { + const transport = transportOf(500); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: neverEndingStrategy(), + }); + let count = 0; + for await (const page of paginator.pages()) { + void page; + count += 1; + if (count === 400) break; + } + expect(count).toBe(400); +}); + +test('per-call options reach every page exchange, not just the first (PAGE-36)', async () => { + const transport = transportOf(3); + // Deliberately NOT `RequestOptions.EMPTY`. The failure PAGE-36 guards is an engine that honours the caller's + // options on page 1 and falls back to the default on pages 2..N — and against `EMPTY` that bug is invisible, + // because the substituted default IS `EMPTY`. A distinctive instance makes the identity assertion bite. + // (Use whichever HTTP-3 `newBuilder()` setter Phase 1 actually shipped; the only thing that matters here is + // that `options !== RequestOptions.EMPTY`.) + const options = RequestOptions.EMPTY.newBuilder().timeoutMs(1_234).build(); + const paginator = new Paginator({ + transport, + initialRequest: initialRequest(), + strategy: threePageStrategy(), + options, + }); + for await (const page of paginator.pages()) { + void page; + } + expect(transport.sentOptions).toHaveLength(3); + expect(transport.sentOptions.every(o => o === options)).toBe(true); +}); diff --git a/packages/core/src/pagination/paginator.ts b/packages/core/src/pagination/paginator.ts new file mode 100644 index 0000000..6d0396b --- /dev/null +++ b/packages/core/src/pagination/paginator.ts @@ -0,0 +1,257 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/paginator.ts +import type {Request} from '../http/request.js'; +import type {RequestOptions} from '../http/request-options.js'; +import type {Response} from '../http/response.js'; +import type {Transport} from '../seams/transport.js'; +import {invariant} from '../invariant.js'; +import {PaginationError} from './errors.js'; +import {Page, type PageInfo} from './page.js'; +import type {PaginationStrategy} from './strategy.js'; +import {suppress} from '../suppress.js'; + +/** + * Initialization options for {@link Paginator}. + * + * @public + */ +export interface PaginatorInit { + /** + * Any `Transport` — a raw one, a `FakeTransport`, or 4c's `Runtime` (which implements `Transport`, so a + * full resilience pipeline drops in unchanged). The engine is transport-agnostic by §12's own mandate. + */ + readonly transport: Transport; + /** The request template that fetches the initial page (page 1) (PAGE-1). */ + readonly initialRequest: Request; + /** The pagination strategy that parses each response into items and the next request (PAGE-5). */ + readonly strategy: PaginationStrategy; + /** Maximum exchanges. Counts pages, not items. Unbounded when omitted (PAGE-10). */ + readonly maxPages?: number | undefined; + /** Applied to **every** page exchange, not just the first (PAGE-36). */ + readonly options?: RequestOptions | undefined; + /** Optional abort signal applied to every page exchange (PAGE-25). */ + readonly signal?: AbortSignal | undefined; +} + +/** + * Turns a paginated endpoint into a lazy stream of items or of whole pages (PAGE-1). + * + * Holds only frozen configuration and is safe to share; each call to {@link Paginator.items} or {@link Paginator.pages} builds a + * fresh walk with its own counter and cursor, so two iterations drive two full fetch sequences (PAGE-8). That + * is a property of generators, not bookkeeping performed here. + * + * **Laziness is free** (PAGE-6): a generator body does not run until its first `.next()`, so constructing this + * object, calling `items()`, and taking its iterator all trigger zero exchanges. + * + * **Cancellation race** (PAGE-33), inherent and worth knowing: if `signal` aborts *before* the transport + * delivers a response, that response never reaches this engine and releasing it is the transport's + * responsibility — cancelling a walk cannot reach into a response it was never handed. Conversely, a page + * request already dispatched may still complete after the abort; when it does, this engine closes and discards + * that response rather than yielding it. + * + * @public + */ +export class Paginator { + // `#private` rather than `private` (styleguide 6.6 defaults to `private`): this is a published class, so the + // config bag must be unreachable via bracket access from consumer code, not merely compile-time-hidden. + // It is the class's ONLY field — PAGE-8 requires the engine to hold immutable configuration and nothing else. + readonly #init: PaginatorInit; + + constructor(init: PaginatorInit) { + // PAGE-9: fail fast at construction, not lazily on the first fetch, so a misconfiguration surfaces at the + // call site that caused it. + if ( + init.maxPages !== undefined && + (!Number.isInteger(init.maxPages) || init.maxPages <= 0) + ) { + throw new PaginationError( + `maxPages must be a positive integer; received ${String(init.maxPages)}`, + ); + } + this.#init = Object.freeze({...init}); + + invariant( + (this.#init.transport as unknown) !== undefined, + 'Paginator requires a transport', + ); + invariant( + (this.#init.initialRequest as unknown) !== undefined, + 'Paginator requires an initialRequest', + ); + invariant( + (this.#init.strategy as unknown) !== undefined, + 'Paginator requires a strategy', + ); + } + + /** + * Every item across every page, flattened in server order (PAGE-1). + * + * **Each page is closed before any of its items are yielded** (PAGE-11), after the items are copied. The + * items survive close (PAGE-2), so this costs nothing — and it means abandoning iteration mid-page can never + * strand a response, regardless of how long the consumer takes. + * + * Note this is deliberately *not* the ordering `sdk-design-nodejs/07` §7.1's illustrative snippet shows. That + * snippet closes in a `finally` after yielding, which holds the response open for the whole item walk; it + * passes PAGE-11's stated conformance test anyway, which is exactly why the ordering is called out here. + * + * Re-iterable, unlike {@link Paginator.pages}: PAGE-14 scopes single-use to the page-level view, and PAGE-8 requires + * independent iterations to work. + */ + items(): AsyncIterable { + const walk = this.#walk.bind(this); + return { + async *[Symbol.asyncIterator](): AsyncGenerator { + for await (const page of walk()) { + const items = page.items; + await page.close(); + yield* items; + } + }, + }; + } + + /** + * Whole pages, each exposing per-page status, headers, and originating request (PAGE-1). + * + * Auto-closing (PAGE-12): the previous page is closed as the consumer advances, and the currently held page + * is closed at exhaustion or on abandonment via the generator's `finally` — which the runtime drives + * automatically when a `for await` loop exits early through `break`, `return`, or a throw. + * + * **Consume this inside a scoped construct** (PAGE-12, MUST). A `for await` loop is one — it drives + * `.return()` on every exit path, including `break` and `throw`, so the held page is always released. Driving + * the iterator by hand is the case to be careful with: if you call `[Symbol.asyncIterator]()` yourself and + * then abandon it without calling `.return()`, the generator never resumes, its `finally` never runs, and the + * page it is holding stays open until the process exits. Either stay in a `for await`, or bind the pages you + * pull with `await using` (see {@link (Page:class)}), or call `.return()` on the iterator yourself. + * + * Single-use (PAGE-14) — **per view, not per paginator**. A second `[Symbol.asyncIterator]()` on *this* + * returned view fails loudly rather than silently restarting the walk. Calling `pages()` again is the + * sanctioned recovery path PAGE-14 itself names ("a caller restarts pagination by requesting a fresh view + * from the engine"), so it returns a new, independent view. Guarding `pages()` too would make the engine + * stateful, which PAGE-8 forbids ("the engine itself MUST hold only immutable configuration and be safe to + * share") and would break two concurrent callers sharing one `Paginator`. + */ + pages(): AsyncIterable> { + const walk = this.#walk.bind(this); + let iteratorTaken = false; + return { + [Symbol.asyncIterator]: (): AsyncIterator> => { + // PAGE-14 governs obtaining the *iterator*, not calling pages(), and guarding only the method would + // leave the exact hole the requirement names: `for await` calls Symbol.asyncIterator afresh each time, + // so iterating one returned view twice would silently restart the entire walk. 6b's SseStream guards at + // this same level, for the same reason. + if (iteratorTaken) { + throw new PaginationError( + 'the page-level view is single-use; its iterator may be obtained at most once', + ); + } + iteratorTaken = true; + return walk()[Symbol.asyncIterator](); + }, + }; + } + + /** The one drive routine both views share. */ + async *#walk(): AsyncGenerator> { + const {transport, strategy, initialRequest, maxPages, options, signal} = + this.#init; + let request: Request | undefined = initialRequest; + let fetched = 0; + let held: Page | undefined; + + try { + while (request !== undefined) { + // PAGE-25/PAGE-26: check abort before dispatch so no extra request is sent past the abort boundary. + if (isAborted(signal)) return; + // PAGE-9: cap stops the walk even when the strategy still reports a next request. + if (maxPages !== undefined && fetched >= maxPages) return; + + // PAGE-12: release the previous page before dispatching the next request, so the two-page window + // does not hold connections open across subsequent network exchanges. + if (held !== undefined) { + const previous = held; + held = undefined; + await previous.close(); + } + + const response = await transport.send(request, options, signal); + fetched += 1; + + // PAGE-26/PAGE-33: an abort that landed while this exchange was in flight means the page must be + // dropped AND closed rather than delivered. + if (isAborted(signal)) { + await closeQuietly(response); + return; + } + + const info: PageInfo = await parseOrClose( + strategy, + response, + request, + ); + + // PAGE-4: parse must always return a well-formed result and must never signal termination through a + // side channel. A strategy that returns nothing is a programmer error, so it crashes at the fault + // rather than silently ending the walk as if the server had run out of pages. + invariant( + (info as unknown) !== undefined, + 'PaginationStrategy.parse must return a PageInfo, never undefined', + ); + invariant( + (info.items as unknown) !== undefined, + 'PageInfo.items must never be null or absent (PAGE-2)', + ); + + held = new Page(response, info.items); + request = info.nextRequest; + yield held; + } + } finally { + // Covers exhaustion, an early `break`, and a consumer throw — a `for await` loop drives `.return()` on the + // generator (AsyncIteratorClose), which executes this `finally` block (PAGE-12, PAGE-27, PAGE-32). If + // `held.close()` throws during an active `.return()` unwind, the ECMAScript specification discards the close + // error and propagates the consumer's original error, satisfying PAGE-32's requirement. + if (held !== undefined) await held.close(); + } + } +} + +/** + * PAGE-13: if `parse` rejects, the page was never constructed, so nothing else will close this response — do it + * inline on the exceptional path. A close failure must not mask the parse failure: parse error primary, close + * error suppressed. + */ +async function parseOrClose( + strategy: PaginationStrategy, + response: Response, + template: Request, +): Promise> { + try { + return await strategy.parse(response, template); + } catch (parseError: unknown) { + try { + await response.close(); + } catch (closeError: unknown) { + throw suppress( + parseError, + closeError, + 'pagination parse failed and releasing the response also failed', + ); + } + throw parseError; + } +} + +/** PAGE-26: on an already-settled cancellation path, a close error is swallowed — nothing is left to report to. */ +async function closeQuietly(response: Response): Promise { + try { + await response.close(); + } catch { + // Deliberately swallowed: the walk has already ended and there is no in-flight result to attach this to. + } +} + +function isAborted(signal?: AbortSignal): boolean { + return signal?.aborted === true; +} diff --git a/packages/core/src/pagination/query-splice.property.test.ts b/packages/core/src/pagination/query-splice.property.test.ts new file mode 100644 index 0000000..f6c6761 --- /dev/null +++ b/packages/core/src/pagination/query-splice.property.test.ts @@ -0,0 +1,53 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/query-splice.property.test.ts +import {test} from 'bun:test'; +import fc from 'fast-check'; +import {readQueryParam, spliceQueryParam} from './query-splice.js'; + +/** + * Segment names and values drawn from characters a real server actually sends, including hostile ones. + * + * The alphabet deliberately excludes `"`, `#`, `<`, `>`, and `'`: those sit in the WHATWG query percent-encode + * set, so assigning to `URL.search` rewrites them and byte-for-byte preservation genuinely does not hold. That + * boundary is pinned by its own named test above rather than being smuggled into a property that would then + * fail for a reason unrelated to the splice logic this property exists to check. + */ +const rawSegment = fc + .tuple( + fc.stringMatching(/^[a-z]{1,6}$/), + fc.stringMatching(/^[a-zA-Z0-9:%._~-]{0,10}$/), + ) + .map(([name, value]) => `${name}=${value}`); + +test('every untargeted segment survives the splice byte-for-byte (PAGE-21)', () => { + fc.assert( + fc.property( + fc.array(rawSegment, {maxLength: 6}), + fc.string({minLength: 1}), + (segments, newValue) => { + const untargeted = segments.filter(s => !s.startsWith('page=')); + const url = new URL( + `https://h/p?${[...untargeted, 'page=1'].join('&')}`, + ); + const out = spliceQueryParam(url, 'page', newValue); + const outSegments = out.search.replace(/^\?/, '').split('&'); + return untargeted.every( + (segment, index) => outSegments[index] === segment, + ); + }, + ), + ); +}); + +test('write-then-read is the identity for any value (PAGE-22)', () => { + fc.assert( + fc.property(fc.string(), value => { + const url = spliceQueryParam( + new URL('https://h/p?a=1&b=2'), + 'cursor', + value, + ); + return readQueryParam(url, 'cursor') === value; + }), + ); +}); diff --git a/packages/core/src/pagination/query-splice.test.ts b/packages/core/src/pagination/query-splice.test.ts new file mode 100644 index 0000000..dc1ca1c --- /dev/null +++ b/packages/core/src/pagination/query-splice.test.ts @@ -0,0 +1,141 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/query-splice.test.ts +// Exercises: PAGE-21 (verbatim splice, untargeted params byte-for-byte), PAGE-22 (RFC 3986 component encoding, +// literal + is data), PAGE-23 (replace-first / append / remove, order preserved), PAGE-24 (non-query components +// preserved exactly). +import {expect, test} from 'bun:test'; +import {readQueryParam, spliceQueryParam} from './query-splice.js'; + +const at = (href: string): URL => new URL(href); +const query = (url: URL): string => url.search.replace(/^\?/, ''); + +test('untargeted parameters survive byte-for-byte, order preserved (PAGE-21)', () => { + const out = spliceQueryParam( + at('https://h/p?flag&filter=a:b&page=1'), + 'page', + '2', + ); + expect(query(out)).toBe('flag&filter=a:b&page=2'); +}); + +test('a value-less flag stays value-less', () => { + const out = spliceQueryParam(at('https://h/p?flag&page=1'), 'page', '2'); + expect(query(out)).toContain('flag&'); + expect(query(out)).not.toContain('flag='); +}); + +test('reserved characters in untargeted values are not rewritten (PAGE-21)', () => { + const out = spliceQueryParam(at('https://h/p?a=x:y/z&page=1'), 'page', '2'); + expect(query(out)).toBe('a=x:y/z&page=2'); +}); + +test('a newly-set value uses RFC 3986 component encoding (PAGE-22)', () => { + expect(query(spliceQueryParam(at('https://h/p'), 'q', 'a b'))).toBe( + 'q=a%20b', + ); + expect(query(spliceQueryParam(at('https://h/p'), 'token', 'a+b/c='))).toBe( + 'token=a%2Bb%2Fc%3D', + ); +}); + +test('reading decodes with the same semantics — a literal + reads back as + (PAGE-22)', () => { + expect(readQueryParam(at('https://h/p?q=a+b'), 'q')).toBe('a+b'); + expect(readQueryParam(at('https://h/p?q=a%20b'), 'q')).toBe('a b'); +}); + +test('a value-less flag reads as the empty string, an absent name as undefined (PAGE-22)', () => { + expect(readQueryParam(at('https://h/p?flag'), 'flag')).toBe(''); + expect(readQueryParam(at('https://h/p?flag'), 'other')).toBeUndefined(); +}); + +test('reading takes the first match when a name repeats (PAGE-22)', () => { + expect(readQueryParam(at('https://h/p?page=1&page=9'), 'page')).toBe('1'); +}); + +test('setting replaces the first occurrence in place and drops later duplicates (PAGE-23)', () => { + expect( + query( + spliceQueryParam(at('https://h/p?page=1&sort=asc&page=9'), 'page', '2'), + ), + ).toBe('page=2&sort=asc'); +}); + +test('setting an absent parameter appends it (PAGE-23)', () => { + expect(query(spliceQueryParam(at('https://h/p?sort=asc'), 'page', '2'))).toBe( + 'sort=asc&page=2', + ); +}); + +test('setting undefined removes the parameter entirely (PAGE-23)', () => { + expect( + query( + spliceQueryParam(at('https://h/p?page=1&sort=asc'), 'page', undefined), + ), + ).toBe('sort=asc'); +}); + +test('removing the only parameter leaves an empty query', () => { + expect( + query(spliceQueryParam(at('https://h/p?page=1'), 'page', undefined)), + ).toBe(''); +}); + +test('setting on a URL with no query at all creates one', () => { + expect(query(spliceQueryParam(at('https://h/p'), 'page', '2'))).toBe( + 'page=2', + ); +}); + +test('every non-query component is preserved exactly (PAGE-24)', () => { + const source = at( + 'https://user:pw@host.example:8443/deep/path?page=1&keep=yes#frag', + ); + const out = spliceQueryParam(source, 'page', '2'); + expect(out.protocol).toBe(source.protocol); + expect(out.username).toBe(source.username); + expect(out.password).toBe(source.password); + expect(out.hostname).toBe(source.hostname); + expect(out.port).toBe(source.port); + expect(out.pathname).toBe(source.pathname); + expect(out.hash).toBe(source.hash); + expect(query(out)).toBe('page=2&keep=yes'); +}); + +test('the input URL is not mutated', () => { + const source = at('https://h/p?page=1'); + spliceQueryParam(source, 'page', '2'); + expect(query(source)).toBe('page=1'); +}); + +test('URLSearchParams-style canonicalization does NOT happen (PAGE-21)', () => { + // URLSearchParams would rewrite `a b` to `a+b` and re-encode `:`; the splice leaves both alone. + const out = spliceQueryParam( + at('https://h/p?msg=a%20b&path=x:y&page=1'), + 'page', + '2', + ); + expect(query(out)).toBe('msg=a%20b&path=x:y&page=2'); +}); + +test('the WHATWG query encode set is the one boundary of byte-for-byte preservation (PAGE-21)', () => { + // Assigning to `URL.search` percent-encodes C0 controls, space, " # < > and (on special schemes) ' — so an + // untargeted segment carrying one of those raw is rewritten. Every such character is one RFC 3986 already + // requires to be encoded in a query, so the only inputs affected were already non-conformant. Pinned here so + // the boundary is known rather than discovered, and recorded in the Deviation Ledger. + const out = spliceQueryParam(at('https://h/p?tag=&page=1'), 'page', '2'); + expect(query(out)).toBe('tag=%3Craw%3E&page=2'); + + // Everything RFC 3986 permits raw in a query survives untouched — which is the case that actually matters. + const safe = spliceQueryParam( + at('https://h/p?f=a:b/c!d$e(f)*g,h;i@j&page=1'), + 'page', + '2', + ); + expect(query(safe)).toBe('f=a:b/c!d$e(f)*g,h;i@j&page=2'); +}); + +test('stray empty segments are skipped, matching HTTP-31 query parsing', () => { + expect( + query(spliceQueryParam(at('https://h/p?a=1&&b=2&page=1'), 'page', '2')), + ).toBe('a=1&b=2&page=2'); +}); diff --git a/packages/core/src/pagination/query-splice.ts b/packages/core/src/pagination/query-splice.ts new file mode 100644 index 0000000..ba38d77 --- /dev/null +++ b/packages/core/src/pagination/query-splice.ts @@ -0,0 +1,93 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/query-splice.ts +import { + decodeQueryComponent, + encodeQueryComponent, +} from '../http/query-params.js'; + +/** + * Rewrite one query parameter, splicing the raw query string rather than re-rendering it (PAGE-21–PAGE-24). + * + * **Why not `URLSearchParams`.** It re-serializes the *entire* query through its own canonical encoding on + * every mutation: untouched parameters get reordered and re-encoded (against PAGE-21's byte-for-byte rule), and + * a space becomes `+` rather than the `%20` this port standardizes on (HTTP-29). + * + * **Why not `QueryParams`.** Same problem in a different costume — `encode()` re-renders the whole query from + * the parsed model. `QueryParams` is the right tool for *building* a query and the wrong one for *splicing* one. + * Only the component *encoder* is shared, which is the part PAGE-22 and HTTP-29 genuinely agree on. + * + * Passing `undefined` removes the parameter. Setting replaces the first occurrence in place and drops later + * duplicates — the single-value convention paging parameters follow. Everything else is copied byte-for-byte. + * + * @internal + */ +export function spliceQueryParam( + url: URL, + name: string, + value: string | undefined, +): URL { + const encodedName = encodeQueryComponent(name); + const segments = splitQuery(url.search); + + const out: string[] = []; + let replaced = false; + + for (const segment of segments) { + if (nameOf(segment) !== encodedName) { + out.push(segment); // byte-for-byte, untouched + continue; + } + if (replaced) continue; // PAGE-23: later duplicates are dropped + replaced = true; + if (value !== undefined) + out.push(`${encodedName}=${encodeQueryComponent(value)}`); + } + + if (!replaced && value !== undefined) { + out.push(`${encodedName}=${encodeQueryComponent(value)}`); + } + + // Rebuilding through `URL` preserves scheme, userinfo, host, port, path, and fragment exactly (PAGE-24); + // only `search` is assigned. + const next = new URL(url.href); + next.search = out.length === 0 ? '' : `?${out.join('&')}`; + return next; +} + +/** + * Read one query parameter with the same RFC 3986 semantics the splice writes (PAGE-22). + * + * A literal `+` reads back as `+`, `%20` as a space, a value-less flag as the empty string, and an absent name + * as `undefined`. First match wins. + * + * @internal + */ +export function readQueryParam(url: URL, name: string): string | undefined { + const encodedName = encodeQueryComponent(name); + for (const segment of splitQuery(url.search)) { + if (nameOf(segment) !== encodedName) continue; + const eq = segment.indexOf('='); + return eq === -1 ? '' : decodeQueryComponent(segment.slice(eq + 1)); + } + return undefined; +} + +/** + * Split a raw query into `&`-separated segments, dropping the leading `?` and any stray empty segments. + * + * Dropping empty segments (`?a=1&&b=2` → two segments) is not a byte-for-byte violation to apologize for — it + * is the same leniency `HTTP-31` already mandates for query *parsing*, "stray `&` is skipped." Doing something + * different here would put two disagreeing readings of the same query string in one codebase. + */ +function splitQuery(search: string): string[] { + const raw = search.startsWith('?') ? search.slice(1) : search; + return raw.length === 0 + ? [] + : raw.split('&').filter(segment => segment.length > 0); +} + +/** The raw (still-encoded) name of a segment. A value-less flag is all name. */ +function nameOf(segment: string): string { + const eq = segment.indexOf('='); + return eq === -1 ? segment : segment.slice(0, eq); +} diff --git a/packages/core/src/pagination/strategies.test.ts b/packages/core/src/pagination/strategies.test.ts new file mode 100644 index 0000000..264602c --- /dev/null +++ b/packages/core/src/pagination/strategies.test.ts @@ -0,0 +1,267 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/strategies.test.ts +// Exercises: PAGE-16 (cursor: single body read, null OR empty ends, configurable parameter), PAGE-17 +// (page-number: empty items ends, start-page fallback on absent/empty/garbage, configurable name and start), +// PAGE-18/19/20 (link header: rel=next, RFC 3986 reference resolution, query-only reference preserves the path, +// unresolvable target ends the stream without throwing). +import {expect, test} from 'bun:test'; +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; +import { + cursorStrategy, + linkHeaderStrategy, + pageNumberStrategy, +} from './strategies.js'; + +const template = (href: string): Request => + ({ + url: new URL(href), + newBuilder() { + let target = new URL(href); + return { + url(next: URL) { + target = next; + return this; + }, + build: () => ({url: target}) as unknown as Request, + }; + }, + }) as unknown as Request; + +const response = (init: { + url?: string; + headers?: Record; +}): Response => + ({ + request: {url: new URL(init.url ?? 'https://api.test/repo/issues?page=1')}, + headers: { + get: (name: string) => init.headers?.[name.toLowerCase()]?.[0], + getAll: (name: string) => init.headers?.[name.toLowerCase()] ?? [], + }, + }) as unknown as Response; + +// ---- cursor (PAGE-16) ---- + +test('a cursor sets the configured query parameter on the next request (PAGE-16)', async () => { + let reads = 0; + const strategy = cursorStrategy({ + extract: () => { + reads += 1; + return Promise.resolve({items: ['a'], cursor: 'c'}); + }, + }); + const info = await strategy.parse( + response({}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.search).toBe('?cursor=c'); + expect(reads).toBe(1); +}); + +test('the cursor parameter name is configurable (PAGE-16)', async () => { + const strategy = cursorStrategy({ + extract: () => Promise.resolve({items: ['a'], cursor: 'c'}), + parameterName: 'after', + }); + const info = await strategy.parse( + response({}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.search).toBe('?after=c'); +}); + +test.each([null, '', undefined])( + 'a %p cursor ends the stream (PAGE-16)', + async cursor => { + const strategy = cursorStrategy({ + extract: () => + Promise.resolve({items: ['a'], cursor: cursor as string | null}), + }); + const info = await strategy.parse( + response({}), + template('https://api.test/items'), + ); + expect(info.nextRequest).toBeUndefined(); + expect(info.items).toEqual(['a']); + }, +); + +// ---- page number (PAGE-17) ---- + +test('the first page with no parameter advances to start+1 (PAGE-17)', async () => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({url: 'https://api.test/items'}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.search).toBe('?page=2'); +}); + +test('an empty items list ends the stream, defensively (PAGE-17)', async () => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve([]), + }); + const info = await strategy.parse( + response({url: 'https://api.test/items?page=4'}), + template('https://api.test/items?page=4'), + ); + expect(info.nextRequest).toBeUndefined(); +}); + +test('the current page comes from the EXECUTED request, not the template (PAGE-17)', async () => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({url: 'https://api.test/items?page=7'}), + template('https://api.test/items?page=1'), + ); + expect(info.nextRequest?.url.search).toBe('?page=8'); +}); + +test.each(['', 'garbage', '1.5', '-3'])( + 'a %p page value falls back to the start page (PAGE-17)', + async value => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({url: `https://api.test/items?page=${value}`}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.search).toBe('?page=2'); + }, +); + +test('the parameter name and start page are configurable, supporting 0-based servers (PAGE-17)', async () => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve(['a']), + parameterName: 'offset', + startPage: 0, + }); + const info = await strategy.parse( + response({url: 'https://api.test/items'}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.search).toBe('?offset=1'); +}); + +// ---- link header (PAGE-18/19/20) ---- + +test('an absolute rel=next target is used as-is (PAGE-19)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({headers: {link: ['; rel="next"']}}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.href).toBe('https://other.test/x?page=2'); +}); + +test('a query-only reference preserves the base path and replaces only the query (PAGE-19)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({ + url: 'https://api.test/repo/issues?page=1', + headers: {link: ['; rel="next"']}, + }), + template('https://api.test/repo/issues?page=1'), + ); + // RFC 2396 would drop the last path segment here; RFC 3986 (and WHATWG URL) does not. + expect(info.nextRequest?.url.pathname).toBe('/repo/issues'); + expect(info.nextRequest?.url.search).toBe('?page=2'); +}); + +test('a relative path reference resolves against the response URL (PAGE-19)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({ + url: 'https://api.test/repo/issues?page=1', + headers: {link: ['<../pulls>; rel="next"']}, + }), + template('https://api.test/repo/issues'), + ); + expect(info.nextRequest?.url.pathname).toBe('/pulls'); +}); + +test('an unresolvable target ends the stream rather than throwing (PAGE-19)', async () => { + // Picking this fixture takes care. With a base supplied, WHATWG `URL` resolves almost *anything* as a + // relative reference rather than failing — `ht!tp://%%%` has no valid scheme, so it parses happily as a path + // and yields a defined next request, which would make this test assert nothing. A genuinely unparseable + // target needs a valid scheme and a broken authority, so the absolute-URL path is taken and fails: `http://[` + // opens an IPv6 literal that never closes. + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({headers: {link: ['; rel="next"']}}), + template('https://api.test/items'), + ); + expect(info.nextRequest).toBeUndefined(); + expect(info.items).toEqual(['a']); +}); + +test('the fixture above really is unparseable — the guard is not vacuous (PAGE-19)', () => { + expect(() => new URL('http://[', 'https://api.test/items')).toThrow(); + // And the near-miss that does NOT throw, pinned so nobody "simplifies" the fixture back to it later. + expect(() => new URL('ht!tp://%%%', 'https://api.test/items')).not.toThrow(); +}); + +test('no Link header ends the stream (PAGE-18)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({}), + template('https://api.test/items'), + ); + expect(info.nextRequest).toBeUndefined(); +}); + +test('the header name is configurable (PAGE-18)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + headerName: 'X-Links', + }); + const info = await strategy.parse( + response({headers: {'x-links': ['; rel="next"']}}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.pathname).toBe('/next'); +}); + +test('two separate Link header instances are both considered (PAGE-20)', async () => { + const strategy = linkHeaderStrategy({ + extract: () => Promise.resolve(['a']), + }); + const info = await strategy.parse( + response({headers: {link: ['; rel="last"', '; rel="next"']}}), + template('https://api.test/items'), + ); + expect(info.nextRequest?.url.pathname).toBe('/b'); +}); + +test('one strategy instance is safe across two concurrent walks (PAGE-5)', async () => { + const strategy = pageNumberStrategy({ + extract: () => Promise.resolve(['a']), + }); + const [first, second] = await Promise.all([ + strategy.parse( + response({url: 'https://api.test/items?page=1'}), + template('https://api.test/items'), + ), + strategy.parse( + response({url: 'https://api.test/items?page=9'}), + template('https://api.test/items'), + ), + ]); + expect(first.nextRequest?.url.search).toBe('?page=2'); + expect(second.nextRequest?.url.search).toBe('?page=10'); +}); diff --git a/packages/core/src/pagination/strategies.ts b/packages/core/src/pagination/strategies.ts new file mode 100644 index 0000000..165ce12 --- /dev/null +++ b/packages/core/src/pagination/strategies.ts @@ -0,0 +1,124 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/strategies.ts +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; +import {findNextLink} from './link-header.js'; +import {pageInfo, type PageInfo} from './page.js'; +import {readQueryParam, spliceQueryParam} from './query-splice.js'; +import type {PaginationStrategy} from './strategy.js'; + +/** Build the next request by swapping only the URL, preserving method, headers, and body (PAGE-23). */ +function withUrl(template: Request, url: URL): Request { + return template.newBuilder().url(url).build(); +} + +/** + * Cursor/continuation-token pagination (PAGE-16). + * + * `extract` reads items and the next cursor from **one** read of the response body. It is caller-supplied + * rather than codec-driven because §12 requires the engine to be serde-agnostic: naming a `Serde` here would + * couple pagination to a wire format it has no business knowing about. A caller using `@dexpace/codec-json` + * simply closes over it inside `extract`. + * + * A `null` **or empty** cursor ends the stream — both, because a server returning `""` for "no more pages" is + * common enough that treating it as a real cursor produces an infinite walk. + * + * @public + */ +export function cursorStrategy(init: { + extract: ( + response: Response, + ) => Promise<{items: readonly T[]; cursor?: string | null | undefined}>; + parameterName?: string | undefined; +}): PaginationStrategy { + const parameterName = init.parameterName ?? 'cursor'; + return Object.freeze({ + async parse(response: Response, template: Request): Promise> { + const {items, cursor} = await init.extract(response); + if (cursor === null || cursor === undefined || cursor.length === 0) + return pageInfo(items); + return pageInfo( + items, + withUrl( + template, + spliceQueryParam(template.url, parameterName, cursor), + ), + ); + }, + }); +} + +/** + * Page-number pagination (PAGE-17). + * + * An empty items list ends the stream **before** any arithmetic runs — defensive against servers that keep + * returning an empty page past the end instead of signalling termination, which would otherwise walk forever. + * + * The current page comes from the *executed* request's query, not the template's, because the template never + * changes across the walk. An absent, empty, or non-numeric value falls back to `startPage`; `startPage: 0` + * supports 0-based servers. + * + * @public + */ +export function pageNumberStrategy(init: { + extract: (response: Response) => Promise; + parameterName?: string | undefined; + startPage?: number | undefined; +}): PaginationStrategy { + const parameterName = init.parameterName ?? 'page'; + const startPage = init.startPage ?? 1; + return Object.freeze({ + async parse(response: Response, template: Request): Promise> { + const items = await init.extract(response); + if (items.length === 0) return pageInfo(items); + + const raw = readQueryParam(response.request.url, parameterName); + const parsed = + raw === undefined || raw.length === 0 ? Number.NaN : Number(raw); + const current = + Number.isInteger(parsed) && parsed >= 0 ? parsed : startPage; + + const nextUrl = spliceQueryParam( + template.url, + parameterName, + String(current + 1), + ); + return pageInfo(items, withUrl(template, nextUrl)); + }, + }); +} + +/** + * `Link`-header pagination (PAGE-18, PAGE-19, PAGE-20). + * + * The target resolves as an RFC 3986 reference against the originating response's URL. WHATWG `URL` gets the + * query-only (`?page=2`) case right natively — it preserves the base path and replaces only the query, where + * RFC 2396's older rule would drop the last path segment. + * + * A target that cannot resolve into a valid URL is **end-of-stream, not an error** (PAGE-19). That is why the + * `URL` constructor's throw is caught and converted here — one of the few places in this codebase where + * swallowing an exception is the specified behavior rather than a smell. + * + * @public + */ +export function linkHeaderStrategy(init: { + extract: (response: Response) => Promise; + headerName?: string | undefined; +}): PaginationStrategy { + const headerName = init.headerName ?? 'Link'; + return Object.freeze({ + async parse(response: Response, template: Request): Promise> { + const items = await init.extract(response); + const target = findNextLink(response.headers.getAll(headerName)); + if (target === undefined) return pageInfo(items); + + let resolved: URL; + try { + resolved = new URL(target, response.request.url); + } catch { + return pageInfo(items); // PAGE-19: unresolvable means end of stream, never an error. + } + return pageInfo(items, withUrl(template, resolved)); + }, + }); +} diff --git a/packages/core/src/pagination/strategy.test.ts b/packages/core/src/pagination/strategy.test.ts new file mode 100644 index 0000000..01834a1 --- /dev/null +++ b/packages/core/src/pagination/strategy.test.ts @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/strategy.test.ts +// Exercises: PAGE-5 (strategy contract), PAGE-29 (async parse boundary), PAGE-30 (synchronous item array). +// Pure type declarations, so the assertions are expect-type only (styleguide 11.6) and fire under `bun run typecheck`. +import {test} from 'bun:test'; +import {expectTypeOf} from 'expect-type'; +import type {PageInfo} from './page.js'; +import type {PaginationStrategy} from './strategy.js'; + +test('parse returns a promise — a synchronous body read does not exist in this runtime (PAGE-5)', () => { + expectTypeOf['parse']>().returns.toEqualTypeOf< + Promise> + >(); +}); + +test('parse receives the response and the original request template (PAGE-5)', () => { + expectTypeOf['parse']>().parameters.toBeArray(); +}); + +test('a strategy is generic in its item type, not in a codec (PAGE-5, §12 serde-agnostic)', () => { + expectTypeOf>().not.toBeAny(); +}); diff --git a/packages/core/src/pagination/strategy.ts b/packages/core/src/pagination/strategy.ts new file mode 100644 index 0000000..abbf5bb --- /dev/null +++ b/packages/core/src/pagination/strategy.ts @@ -0,0 +1,47 @@ +// SPDX-License-Identifier: MIT +// packages/core/src/pagination/strategy.ts +import type {Request} from '../http/request.js'; +import type {Response} from '../http/response.js'; +import type {PageInfo} from './page.js'; + +/** + * A stateless parser turning one response into that page's items plus the next page's request (PAGE-5). + * + * **On `template`.** The glossary calls this "the original request template," but the engine passes the request + * that produced *this* response — i.e. it advances with the walk. That is deliberate and is what the built-in + * strategies need: `cursorStrategy` splices the new cursor onto the request actually just executed, so a walk + * accumulates one cursor parameter rather than re-deriving page N's URL from page 1's every time. Read the + * parameter as "the request to derive the next one from," and use `response.request` when you specifically want + * the executed request's own URL (`pageNumberStrategy` does). + * + * **Contract obligations on implementors** — none of these can be enforced by the type system, so they are + * stated here and covered by the engine's own tests: + * + * - **Read the body at most once.** The body is single-use. The engine hands you the response exactly once and + * never reads the body itself, so it is entirely yours — but only once. + * - **Do not retain the response or its body past the call.** The engine closes the response as soon as `parse` + * resolves, so a retained body is already dead; holding one produces an intermittent failure rather than a + * clean one. + * - **Do not close or mutate the response.** Lifecycle ownership belongs to the engine. + * - **Be immutable and safe to share.** One strategy instance may drive several concurrent walks. Keep no + * per-call state on `this`. + * - **Never signal termination by throwing.** Return `pageInfo(items)` with no next request. A throw means a + * genuine parse failure, and the engine treats it as one (PAGE-13). + * + * **Why `parse` is asynchronous.** `PAGE-5` says a strategy must read what it needs "synchronously inside + * parse." This runtime has no synchronous body read — the bytes may not have arrived — so the literal reading + * is unimplementable. Every enforceable part of the requirement's intent survives the promise, as listed above. + * Do not "fix" this back to a synchronous signature; it cannot work. + * + * @public + */ +export interface PaginationStrategy { + /** + * Parses one HTTP response into this page's items and the request for the next page (PAGE-5). + * + * @param response - the executed response to extract items from. + * @param template - the request to derive the next page's request from. + * @returns a {@link PageInfo} containing items and the optional next request. + */ + parse(response: Response, template: Request): Promise>; +} diff --git a/packages/core/src/testing/fake-transport.ts b/packages/core/src/testing/fake-transport.ts index 4d984fc..567483a 100644 --- a/packages/core/src/testing/fake-transport.ts +++ b/packages/core/src/testing/fake-transport.ts @@ -1,5 +1,6 @@ // SPDX-License-Identifier: MIT // packages/core/src/testing/fake-transport.ts +import {Headers} from '../http/headers.js'; import {Protocol} from '../http/protocol.js'; import {Request} from '../http/request.js'; import type {RequestOptions} from '../http/request-options.js'; @@ -57,6 +58,16 @@ export class FakeTransport implements Transport { return this.#calls.length; } + /** Options passed to each send, in order (PAGE-36). */ + get sentOptions(): readonly (RequestOptions | undefined)[] { + return this.#calls.map(c => c.options); + } + + /** Abort signals passed to each send, in order (PAGE-25). */ + get sentSignals(): readonly (AbortSignal | undefined)[] { + return this.#calls.map(c => c.signal); + } + /** * Records the send and serves the scripted entry at this position. * @@ -87,6 +98,14 @@ export class FakeTransport implements Transport { } } +export interface CountingResponseInit { + readonly status?: number; + readonly headers?: Record; + readonly body?: string; + readonly request?: Request; + readonly onCancel?: () => void; +} + /** * Builds a `Response` whose close can be OBSERVED. * @@ -107,35 +126,81 @@ export class FakeTransport implements Transport { * `ReadableStream` that enqueues and never closes leaves `toHttpError()`'s drain awaiting a chunk * that never arrives, and every engine test that discards a 503 hangs until the runner's timeout. * - * @param status - the status code the response carries. - * @param request - the originating request; defaults to a bare GET. - * @returns the response and a counter reporting how many times its body was released. - * * @internal */ export function countingResponse( status: number, - request: Request = Request.newBuilder().url('https://example.com').build(), -): {response: Response; cancelCount: () => number} { - let releases = 0; + request?: Request, +): {response: Response; cancelCount: () => number}; +export function countingResponse(init: CountingResponseInit): Response; +export function countingResponse( + statusOrInit: number | CountingResponseInit, + requestParam?: Request, +): Response | {response: Response; cancelCount: () => number} { + if (typeof statusOrInit === 'number') { + let releases = 0; + const body = new ReadableStream({ + start(controller) { + controller.enqueue(Uint8Array.from([1])); + }, + pull(controller) { + // Reached only once the single chunk has been read (default highWaterMark 1), i.e. a full drain. + releases += 1; + controller.close(); + }, + cancel() { + releases += 1; + }, + }); + const response = Response.newBuilder() + .request( + requestParam ?? Request.newBuilder().url('https://example.com').build(), + ) + .protocol(Protocol.HTTP_1_1) + .status(Status.of(statusOrInit)) + .body(body) + .build(); + return {response, cancelCount: () => releases}; + } + + const { + status = 200, + headers: headersRecord, + body: bodyString = '{}', + request = Request.newBuilder().url('https://example.com').build(), + onCancel, + } = statusOrInit; + + const headerBuilder = Headers.newBuilder(); + if (headersRecord) { + for (const [key, value] of Object.entries(headersRecord)) { + headerBuilder.set(key, value); + } + } + + const encoded = new TextEncoder().encode(bodyString); + let served = false; const body = new ReadableStream({ start(controller) { - controller.enqueue(Uint8Array.from([1])); + controller.enqueue(encoded); }, pull(controller) { - // Reached only once the single chunk has been read (default highWaterMark 1), i.e. a full drain. - releases += 1; - controller.close(); + if (!served) { + served = true; + } else { + controller.close(); + } }, cancel() { - releases += 1; + onCancel?.(); }, }); - const response = Response.newBuilder() + + return Response.newBuilder() .request(request) .protocol(Protocol.HTTP_1_1) .status(Status.of(status)) + .headers(headerBuilder.build()) .body(body) .build(); - return {response, cancelCount: () => releases}; } diff --git a/test/node-conformance/pagination.test.mjs b/test/node-conformance/pagination.test.mjs new file mode 100644 index 0000000..7e892a9 --- /dev/null +++ b/test/node-conformance/pagination.test.mjs @@ -0,0 +1,119 @@ +// SPDX-License-Identifier: MIT +// test/node-conformance/pagination.test.mjs +// +// Phase 6c's runtime-divergent surface, run against the BUILT artifact on real Node. +// +// Three things in this phase are runtime-divergent across Bun and Node: +// 1. Explicit Resource Management: `Page` implements `[Symbol.asyncDispose]` delegating to `close()`. +// 2. `AbortSignal` integration: threading signal into every request exchange and halting pagination walks at boundaries. +// 3. `Response.close()` cancelling active `ReadableStream` bodies upon advance, early break, or completion. +import assert from 'node:assert/strict'; +import {describe, it} from 'node:test'; +import {Page, pageInfo, Paginator, Request} from '@dexpace/core'; +import { + FakeTransport, + countingResponse, +} from '../../packages/core/dist/testing/fake-transport.js'; + +describe('Page explicit resource management on Node (PAGE-3, PAGE-12)', () => { + it('disposes the page via Symbol.asyncDispose, releasing the response body', async () => { + const {response, cancelCount} = countingResponse(200); + const page = new Page(response, ['item-1', 'item-2']); + + assert.equal(typeof page[Symbol.asyncDispose], 'function'); + assert.deepEqual(page.items, ['item-1', 'item-2']); + + await page[Symbol.asyncDispose](); + assert.equal(cancelCount(), 1); + // Metadata survives close (PAGE-2) + assert.deepEqual(page.items, ['item-1', 'item-2']); + assert.equal(page.status.code, 200); + }); +}); + +describe('Paginator iteration and cancellation on Node (PAGE-1, PAGE-25, PAGE-26)', () => { + it('walks pages and items, closing responses before yielding items (PAGE-11)', async () => { + const closed = []; + const r1 = countingResponse({body: '{}', onCancel: () => closed.push(0)}); + const r2 = countingResponse({body: '{}', onCancel: () => closed.push(1)}); + + const transport = new FakeTransport([r1, r2]); + + let parseCount = 0; + const strategy = { + parse: async () => { + parseCount += 1; + const nextReq = + parseCount === 1 + ? Request.newBuilder() + .method('GET') + .url('https://api.test/items?page=2') + .build() + : undefined; + return pageInfo([`item-${parseCount}`], nextReq); + }, + }; + + const initialRequest = Request.newBuilder() + .method('GET') + .url('https://api.test/items?page=1') + .build(); + + const paginator = new Paginator({ + transport, + strategy, + initialRequest, + }); + + const items = []; + for await (const item of paginator.items()) { + items.push(item); + } + + assert.deepEqual(items, ['item-1', 'item-2']); + assert.deepEqual(closed, [0, 1]); + assert.equal(transport.sendCount, 2); + }); + + it('stops walk at page boundary on abort, threading AbortSignal (PAGE-25, PAGE-26)', async () => { + const controller = new AbortController(); + const responses = Array.from( + {length: 10}, + () => countingResponse(200).response, + ); + const transport = new FakeTransport(responses); + + const strategy = { + parse: async (_res, template) => { + return pageInfo(['x'], template); + }, + }; + + const initialRequest = Request.newBuilder() + .method('GET') + .url('https://api.test/items') + .build(); + + const paginator = new Paginator({ + transport, + strategy, + initialRequest, + signal: controller.signal, + }); + + let delivered = 0; + for await (const page of paginator.pages()) { + void page; + delivered += 1; + if (delivered === 2) controller.abort(); + } + + assert.equal(delivered, 2); + assert.equal(transport.sendCount, 2); + assert.equal(transport.sentSignals.length, 2); + assert.equal( + transport.sentSignals.every(s => s === controller.signal), + true, + ); + }); +}); diff --git a/tsconfig.base.json b/tsconfig.base.json index e715f95..679be34 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -7,6 +7,7 @@ "moduleResolution": "nodenext", "lib": [ "ES2023", + "ESNext.Disposable", "DOM", "DOM.AsyncIterable" ],