@confect/react 10.0.0-next.21 → 10.0.0-next.22

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @confect/react
 
+## 10.0.0-next.22
+
+### Minor Changes
+
+- 6cc5834: Add experimental stream querying with reactive pagination, configurable middleware policies, and broader tracing.
+
+  ### Stream queries and pagination
+
+  Create composable Effect streams with `reader.table(...).stream(index, range?, order?)` and `QueryStream` from `@confect/server`. Merge, filter, map, join, deduplicate, narrow, and reverse queries without losing cursor pagination. Order keys and directions are checked by the type system. Joins support left-join placeholders through `onEmpty`, and effectful filters and maps support ordered concurrency. Reversing a distinct stream preserves its chosen representatives.
+
+  `QueryStream.paginate` resumes from indexed cursor bounds and supports pinned page ranges, automatic split recommendations, and `maximumRowsRead`/`maximumBytesRead` budgets that count underlying query-stream reads, including filtered documents. Byte counts are estimates. If a budget prevents safe progress or splitting, pagination fails with `ReadBudgetExceededError`; increase the budget or reduce the query's read requirements.
+
+  Use React's new `useStreamPaginatedQuery` for these queries:
+
+  ```ts
+  import { useStreamPaginatedQuery } from "@confect/react";
+
+  const { results, status, loadMore } = useStreamPaginatedQuery(
+    refs.public.notes.feed,
+    {},
+    {
+      initialNumItems: 10,
+      maximumRowsRead: 1000,
+      maximumBytesRead: 512 * 1024,
+    },
+  );
+  ```
+
+  The hook pins loaded pages to fixed ranges, splits oversized or budget-limited pages, and restarts pagination on invalid cursors. Foldkit's `PaginatedQuery` also supports stream queries and preserves page ranges when navigating back and forward, avoiding skipped or repeated documents as data changes.
+
+  Stream cursors expose their order-key values. Do not paginate publicly over sensitive indexed fields unless they are pinned with `eq`. All `QueryStream` APIs are experimental.
+
+  ### Middleware options
+
+  Declare a lazy `options` schema on `MiddlewareSpec.MiddlewareSpec`, then pass typed values with `.middleware(Policy, options)` on functions or groups. Options are validated without coercion during codegen and server registration; keep schemas and values client-safe because generated refs carry them.
+
+  The same policy can be attached repeatedly with non-equivalent options. Every attachment runs, with group policies before function policies. Equivalent options and duplicate policies without options are rejected. Register implementations against the same spec used for attachments.
+
+  ### Breaking changes
+
+  Middleware callbacks passed to `MiddlewareImpl.make` or `MiddlewareImpl.makeByFunctionType` receive invocation metadata under `invocation`. To migrate, nest destructuring of `name`, `functionType`, `functionVisibility`, and decoded `args`:
+
+  **Before:**
+
+  ```ts
+  (effect, { name, args }) => effect;
+  ```
+
+  **After:**
+
+  ```ts
+  (effect, { invocation: { name, args } }) => effect;
+  ```
+
+  Middleware with an options schema also receives `options` alongside `invocation`; middleware without one keeps its single-argument attachment API and receives only `{ invocation }`.
+
+  ### Fixes and tracing
+  - Preserve `ConvexError.data` when a handler throws a `ConvexError` inside an Effect instead of returning it as a typed failure.
+  - Add named tracing spans for JavaScript client calls, server function execution, database writes and pagination, `QueryStream.unique`/`QueryStream.paginate`, and `confect codegen`/`confect dev` code-generation passes.
+
+### Patch Changes
+
+- 9f4e2c0: Require `effect@^4.0.0-rc.113` across `@confect/*` and raise `@confect/server`'s optional `@effect/platform-node` peer to the same range. Upgrade Effect alongside Confect; existing Confect call sites are unchanged.
+
+  Effect's own APIs include breaking renames: use `Config.String` instead of `Config.string`, and `LanguageModel.LanguageModel` instead of `LanguageModel.Service` when annotating the result of `AiGatewayLanguageModel.make`. See the [Effect RC 113 release notes](https://github.com/Effect-TS/effect/releases/tag/effect%404.0.0-rc.113) for the complete migration guidance.
+
+- 90c80e9: Require `effect@^4.0.0-rc.115` across `@confect/*` and `@effect/platform-node@^4.0.0-rc.115` when using `@confect/server`'s optional Node integration. Upgrade these dependencies alongside Confect; existing Confect call sites are unchanged.
+- f721d2c: Remove spaces around em dashes and separator slashes in API documentation and `confect codegen` diagnostics.
+
 ## 10.0.0-next.21
 
 ### Major Changes
@@ -9,7 +78,7 @@
   ### Breaking Changes
   - `engines.node` is now `>=24` on every `@confect/*` package, raised from `>=22`.
 
-  Node 22 has entered maintenance, so Confect now targets Node 24, the active LTS line. To migrate, move the Node version your project builds and runs on to 24 or later — on Node 22, installing `@confect/*` now fails your package manager's engine check. No API changes accompany the raise: code already running on Node 24 needs no edits.
+  Node 22 has entered maintenance, so Confect now targets Node 24, the active LTS line. To migrate, move the Node version your project builds and runs on to 24 or later—on Node 22, installing `@confect/*` now fails your package manager's engine check. No API changes accompany the raise: code already running on Node 24 needs no edits.
 
 ## 10.0.0-next.20
 
@@ -34,14 +103,14 @@
   Breaking changes for users:
 
   - **Schemas** follow Effect v4's Schema API: `Schema.Union([a, b])` (array form), `Schema.Literals([...])` for literal unions, `Schema.optionalKey` in place of `optionalWith({ exact: true })`, and checks like `Schema.String.check(Schema.isMaxLength(...))` in place of piped filters.
-  - **Option-returning functions** must use a codec with a serializable encoded form, such as `Schema.OptionFromNullOr(...)` — v4's `Schema.Option` encodes to an `Option` instance, which is not a Convex value.
-  - **Table schemas** may now be transformations (`Schema.decodeTo` chains, `Schema.encodeKeys`), branded structs, suspended schemas, or unions of these — Convex's system fields are carried through the whole encoding chain. Schemas that do not resolve to an object shape at every step (such as `Schema.Class`) are rejected with a descriptive error when the table is defined.
+  - **Option-returning functions** must use a codec with a serializable encoded form, such as `Schema.OptionFromNullOr(...)`—v4's `Schema.Option` encodes to an `Option` instance, which is not a Convex value.
+  - **Table schemas** may now be transformations (`Schema.decodeTo` chains, `Schema.encodeKeys`), branded structs, suspended schemas, or unions of these—Convex's system fields are carried through the whole encoding chain. Schemas that do not resolve to an object shape at every step (such as `Schema.Class`) are rejected with a descriptive error when the table is defined.
   - **Clients**: decode failures surface as `SchemaError` rather than `ParseError` in `@confect/js` and `@confect/react`, and `@confect/react`'s `useMutation`/`useAction` handles with an `error` schema now resolve to `Result` (v4's replacement for `Either`).
-  - **HTTP** is now mounted through the renamed `HttpRouter` module (formerly `HttpApi`). `HttpRouter.make(routes)` takes a single route-registering `Layer` composed from Effect's own `effect/unstable/http` and `effect/unstable/httpapi` modules — `HttpApiBuilder.layer(api)` (with group handler layers supplied via `Layer.provide`; a missing group is a compile-time error), `HttpApiScalar.layer` for docs, `HttpRouter.add` for plain routes, and `HttpRouter.middleware(fn, { global: true })` for middleware, merged with `Layer.mergeAll`. The per-path-prefix record and its `api`/`apiLive`/`middleware`/`scalar` options are gone; Confect registers one catch-all Convex HTTP action at `/`, and plain Convex routes added to the returned router still take precedence. Handlers, middleware, and route-layer construction all run with Confect's Convex-aware `ConfigProvider` in context.
+  - **HTTP** is now mounted through the renamed `HttpRouter` module (formerly `HttpApi`). `HttpRouter.make(routes)` takes a single route-registering `Layer` composed from Effect's own `effect/unstable/http` and `effect/unstable/httpapi` modules—`HttpApiBuilder.layer(api)` (with group handler layers supplied via `Layer.provide`; a missing group is a compile-time error), `HttpApiScalar.layer` for docs, `HttpRouter.add` for plain routes, and `HttpRouter.middleware(fn, { global: true })` for middleware, merged with `Layer.mergeAll`. The per-path-prefix record and its `api`/`apiLive`/`middleware`/`scalar` options are gone; Confect registers one catch-all Convex HTTP action at `/`, and plain Convex routes added to the returned router still take precedence. Handlers, middleware, and route-layer construction all run with Confect's Convex-aware `ConfigProvider` in context.
   - **Node actions** use `effect/unstable/process` (`ChildProcessSpawner`) and `@effect/platform-node`'s `NodeServices` in place of `@effect/platform` `Command`/`NodeContext`.
   - **Configuration**: Confect's Convex-aware `ConfigProvider` treats empty-string environment variables as missing values (matching Effect v4's built-in providers), so `Config.withDefault` and `Config.option` recover from them.
   - **CLI**: a malformed `convex.json` now fails codegen with a descriptive error instead of being silently ignored.
-  - Confect queries no longer stub the global `Date.now`. Queries run with a `Clock` whose unsafe accessors return constants, so Effect-internal reads (log timestamps, spans) never evict a query from Convex's cache; explicit time reads — `Clock.currentTimeMillis`/`currentTimeNanos` or a raw `Date.now()` call — opt the query out and evict as they honestly should.
+  - Confect queries no longer stub the global `Date.now`. Queries run with a `Clock` whose unsafe accessors return constants, so Effect-internal reads (log timestamps, spans) never evict a query from Convex's cache; explicit time reads—`Clock.currentTimeMillis`/`currentTimeNanos` or a raw `Date.now()` call—opt the query out and evict as they honestly should.
 
 ### Patch Changes
 
@@ -56,9 +125,9 @@
 - Raise the required `effect` peer version to `^4.0.0-beta.102` (from `^4.0.0-beta.101`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 - Raise the required `effect` peer version to `^4.0.0-beta.105` (from `^4.0.0-beta.102`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 
-  `beta.103` separates wall-clock time from monotonic elapsed time: `Clock.Clock` now also requires `monotonicTimeNanos` and `monotonicTimeNanosUnsafe`, so a custom `Clock` provided to a Confect function has to supply both. Effects that measure elapsed time — `Effect.timed`, duration metrics, `Sink.withDuration` — read the monotonic accessors instead of the wall clock, and continue to report a zero duration inside queries and mutations, where Confect pins the unsafe accessors to constants to keep Convex's query cache from evicting on every logged span.
+  `beta.103` separates wall-clock time from monotonic elapsed time: `Clock.Clock` now also requires `monotonicTimeNanos` and `monotonicTimeNanosUnsafe`, so a custom `Clock` provided to a Confect function has to supply both. Effects that measure elapsed time—`Effect.timed`, duration metrics, `Sink.withDuration`—read the monotonic accessors instead of the wall clock, and continue to report a zero duration inside queries and mutations, where Confect pins the unsafe accessors to constants to keep Convex's query cache from evicting on every logged span.
 
-  `beta.103` also moves synchronous Effect runs off `setImmediate`/`setTimeout` and onto the microtask queue, which Convex's query and mutation isolate permits. Confect no longer suppresses cooperative fiber yielding for the synchronous work it performs while your modules load — registration and schema-to-validator compilation — and relies on that scheduling instead. Neither the "Can't use `setTimeout` in queries and mutations" crash nor any other consumer-visible behavior changes, but this is the area to look at if module loading starts misbehaving.
+  `beta.103` also moves synchronous Effect runs off `setImmediate`/`setTimeout` and onto the microtask queue, which Convex's query and mutation isolate permits. Confect no longer suppresses cooperative fiber yielding for the synchronous work it performs while your modules load—registration and schema-to-validator compilation—and relies on that scheduling instead. Neither the "Can't use `setTimeout` in queries and mutations" crash nor any other consumer-visible behavior changes, but this is the area to look at if module loading starts misbehaving.
 
   `beta.104` renames Effect's schema error constructors to match their `Data` counterparts, which affects any error schema you declare for a Confect function:
 
@@ -80,7 +149,7 @@
   ) {}
   ```
 
-  `Schema.ErrorClass` is likewise now `Schema.Error`; the schema for JavaScript `Error` instances that previously went by `Schema.Error` is now `Schema.ErrorInstance`, and `Schema.ErrorReviver` is now `Schema.ErrorInstanceReviver`. Confect's own error types — `DocumentDecodeError`, `BlobNotFoundError`, and the rest — are unchanged in name, shape, and message.
+  `Schema.ErrorClass` is likewise now `Schema.Error`; the schema for JavaScript `Error` instances that previously went by `Schema.Error` is now `Schema.ErrorInstance`, and `Schema.ErrorReviver` is now `Schema.ErrorInstanceReviver`. Confect's own error types—`DocumentDecodeError`, `BlobNotFoundError`, and the rest—are unchanged in name, shape, and message.
 
   `beta.105` restructures how schema validation failures are reported, but not on the path Confect puts you on: decode and encode failures still surface as `Schema.SchemaError` with a formatted `message`, so error text from `@confect/js`, `@confect/react`, and document decoding is unchanged.
 
@@ -108,13 +177,13 @@
 
 - Raise the required `effect` peer version to `^4.0.0-beta.107` (from `^4.0.0-beta.106`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 
-  `beta.107` is a patch-only Effect release, so no Confect API changes and no call-site edits are needed — upgrade `effect` alongside `@confect/*` and everything you have written keeps compiling. Your table, argument, and returns schemas still produce the same Convex validators.
+  `beta.107` is a patch-only Effect release, so no Confect API changes and no call-site edits are needed—upgrade `effect` alongside `@confect/*` and everything you have written keeps compiling. Your table, argument, and returns schemas still produce the same Convex validators.
 
-  Two Effect fixes are worth knowing about if they touch your code. HTTP actions written with `HttpRouter` now collect uploaded file contents far faster on large multipart bodies, and a file part whose stream is cut short — because a parser limit was exceeded or the request body ended early — now fails instead of hanging. Separately, `Duration` values that are equal now hash equally, so a `Duration` used as a `HashMap` key or a `HashSet` member is found regardless of which constructor built it.
+  Two Effect fixes are worth knowing about if they touch your code. HTTP actions written with `HttpRouter` now collect uploaded file contents far faster on large multipart bodies, and a file part whose stream is cut short—because a parser limit was exceeded or the request body ended early—now fails instead of hanging. Separately, `Duration` values that are equal now hash equally, so a `Duration` used as a `HashMap` key or a `HashSet` member is found regardless of which constructor built it.
 
 - Raise the required `effect` peer version to `^4.0.0-beta.98` (from `^4.0.0-beta.97`).
 
-  `effect`'s `SchemaError` is now exposed as its own public module (`effect/SchemaError`), which changes the import path TypeScript picks when Confect emits `.d.ts` declarations that reference `Schema.SchemaError` (for example in generated `services.d.ts`). Existing `Schema.SchemaError` / `Schema.isSchemaError` usage is unaffected — this is purely a declaration-emit detail that consumers relying on generated types may notice.
+  `effect`'s `SchemaError` is now exposed as its own public module (`effect/SchemaError`), which changes the import path TypeScript picks when Confect emits `.d.ts` declarations that reference `Schema.SchemaError` (for example in generated `services.d.ts`). Existing `Schema.SchemaError`/`Schema.isSchemaError` usage is unaffected—this is purely a declaration-emit detail that consumers relying on generated types may notice.
 
 - Raise the required `effect` peer version to `^4.0.0-beta.99` (from `^4.0.0-beta.98`).
 
@@ -138,7 +207,7 @@
 
   Also worth knowing if you serve an `HttpApi`: a query parameter declared as an array now decodes correctly when a request supplies exactly one value for it.
 
-  One internal change rides along. Queries and mutations that run long enough to trigger a cooperative fiber yield now take that yield from Effect's own scheduler, which `rc.108` made usable inside Convex's isolate for the first time. The underlying microtask primitive is identical, so behavior should not change — but it is the thing to look at if a long-running query or mutation regresses on this release.
+  One internal change rides along. Queries and mutations that run long enough to trigger a cooperative fiber yield now take that yield from Effect's own scheduler, which `rc.108` made usable inside Convex's isolate for the first time. The underlying microtask primitive is identical, so behavior should not change—but it is the thing to look at if a long-running query or mutation regresses on this release.
 
 - Raise the required `effect` peer version to `^4.0.0-rc.109` (from `^4.0.0-rc.108`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 
@@ -149,10 +218,10 @@
   No Confect API changed, and no call-site edits are needed. `rc.110` is a patch release of Effect with nothing removed or renamed, so upgrading is a matter of installing it alongside `@confect/*`.
 
 - 3f0255c: Build and test against `convex` 1.44.0. The published `convex` peer ranges are unchanged, so no consumer action is required.
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.2–9.2.4 — see those versions' changelog entries.
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.5 — see that version's changelog entries.
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.3.0 — see that version's changelog entries.
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.4.0 — see that version's changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.2–9.2.4—see those versions' changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.5—see that version's changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.3.0—see that version's changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.4.0—see that version's changelog entries.
 
   The `@effect/platform` and `@effect/cli` peer and dependency floors that 9.4.0 raises do not apply here: this line runs on Effect v4, where those packages are not dependencies at all.
 
@@ -188,7 +257,7 @@
 
   Also worth knowing if you serve an `HttpApi`: a query parameter declared as an array now decodes correctly when a request supplies exactly one value for it.
 
-  One internal change rides along. Queries and mutations that run long enough to trigger a cooperative fiber yield now take that yield from Effect's own scheduler, which `rc.108` made usable inside Convex's isolate for the first time. The underlying microtask primitive is identical, so behavior should not change — but it is the thing to look at if a long-running query or mutation regresses on this release.
+  One internal change rides along. Queries and mutations that run long enough to trigger a cooperative fiber yield now take that yield from Effect's own scheduler, which `rc.108` made usable inside Convex's isolate for the first time. The underlying microtask primitive is identical, so behavior should not change—but it is the thing to look at if a long-running query or mutation regresses on this release.
 
 - a4054ab: The published type declarations are now emitted by TypeScript 7 rather than TypeScript 6. No API changed, but the declaration text differs in places, so an inferred type printed in your editor or in a type error may read slightly differently than before.
 
@@ -198,9 +267,9 @@
 
 - 5a73763: Raise the required `effect` peer version to `^4.0.0-beta.107` (from `^4.0.0-beta.106`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 
-  `beta.107` is a patch-only Effect release, so no Confect API changes and no call-site edits are needed — upgrade `effect` alongside `@confect/*` and everything you have written keeps compiling. Your table, argument, and returns schemas still produce the same Convex validators.
+  `beta.107` is a patch-only Effect release, so no Confect API changes and no call-site edits are needed—upgrade `effect` alongside `@confect/*` and everything you have written keeps compiling. Your table, argument, and returns schemas still produce the same Convex validators.
 
-  Two Effect fixes are worth knowing about if they touch your code. HTTP actions written with `HttpRouter` now collect uploaded file contents far faster on large multipart bodies, and a file part whose stream is cut short — because a parser limit was exceeded or the request body ended early — now fails instead of hanging. Separately, `Duration` values that are equal now hash equally, so a `Duration` used as a `HashMap` key or a `HashSet` member is found regardless of which constructor built it.
+  Two Effect fixes are worth knowing about if they touch your code. HTTP actions written with `HttpRouter` now collect uploaded file contents far faster on large multipart bodies, and a file part whose stream is cut short—because a parser limit was exceeded or the request body ended early—now fails instead of hanging. Separately, `Duration` values that are equal now hash equally, so a `Duration` used as a `HashMap` key or a `HashSet` member is found regardless of which constructor built it.
 
 ## 10.0.0-next.12
 
@@ -234,9 +303,9 @@
 
 - f782cdd: Raise the required `effect` peer version to `^4.0.0-beta.105` (from `^4.0.0-beta.102`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
 
-  `beta.103` separates wall-clock time from monotonic elapsed time: `Clock.Clock` now also requires `monotonicTimeNanos` and `monotonicTimeNanosUnsafe`, so a custom `Clock` provided to a Confect function has to supply both. Effects that measure elapsed time — `Effect.timed`, duration metrics, `Sink.withDuration` — read the monotonic accessors instead of the wall clock, and continue to report a zero duration inside queries and mutations, where Confect pins the unsafe accessors to constants to keep Convex's query cache from evicting on every logged span.
+  `beta.103` separates wall-clock time from monotonic elapsed time: `Clock.Clock` now also requires `monotonicTimeNanos` and `monotonicTimeNanosUnsafe`, so a custom `Clock` provided to a Confect function has to supply both. Effects that measure elapsed time—`Effect.timed`, duration metrics, `Sink.withDuration`—read the monotonic accessors instead of the wall clock, and continue to report a zero duration inside queries and mutations, where Confect pins the unsafe accessors to constants to keep Convex's query cache from evicting on every logged span.
 
-  `beta.103` also moves synchronous Effect runs off `setImmediate`/`setTimeout` and onto the microtask queue, which Convex's query and mutation isolate permits. Confect no longer suppresses cooperative fiber yielding for the synchronous work it performs while your modules load — registration and schema-to-validator compilation — and relies on that scheduling instead. Neither the "Can't use `setTimeout` in queries and mutations" crash nor any other consumer-visible behavior changes, but this is the area to look at if module loading starts misbehaving.
+  `beta.103` also moves synchronous Effect runs off `setImmediate`/`setTimeout` and onto the microtask queue, which Convex's query and mutation isolate permits. Confect no longer suppresses cooperative fiber yielding for the synchronous work it performs while your modules load—registration and schema-to-validator compilation—and relies on that scheduling instead. Neither the "Can't use `setTimeout` in queries and mutations" crash nor any other consumer-visible behavior changes, but this is the area to look at if module loading starts misbehaving.
 
   `beta.104` renames Effect's schema error constructors to match their `Data` counterparts, which affects any error schema you declare for a Confect function:
 
@@ -258,11 +327,11 @@
   ) {}
   ```
 
-  `Schema.ErrorClass` is likewise now `Schema.Error`; the schema for JavaScript `Error` instances that previously went by `Schema.Error` is now `Schema.ErrorInstance`, and `Schema.ErrorReviver` is now `Schema.ErrorInstanceReviver`. Confect's own error types — `DocumentDecodeError`, `BlobNotFoundError`, and the rest — are unchanged in name, shape, and message.
+  `Schema.ErrorClass` is likewise now `Schema.Error`; the schema for JavaScript `Error` instances that previously went by `Schema.Error` is now `Schema.ErrorInstance`, and `Schema.ErrorReviver` is now `Schema.ErrorInstanceReviver`. Confect's own error types—`DocumentDecodeError`, `BlobNotFoundError`, and the rest—are unchanged in name, shape, and message.
 
   `beta.105` restructures how schema validation failures are reported, but not on the path Confect puts you on: decode and encode failures still surface as `Schema.SchemaError` with a formatted `message`, so error text from `@confect/js`, `@confect/react`, and document decoding is unchanged.
 
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.4.0 — see that version's changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.4.0—see that version's changelog entries.
 
   The `@effect/platform` and `@effect/cli` peer and dependency floors that 9.4.0 raises do not apply here: this line runs on Effect v4, where those packages are not dependencies at all.
 
@@ -270,14 +339,14 @@
 
 ### Patch Changes
 
-- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.3.0 — see that version's changelog entries.
+- Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.3.0—see that version's changelog entries.
 
 ## 10.0.0-next.9
 
 ### Patch Changes
 
 - 0dcc0fb: Raise the required `effect` peer version to `^4.0.0-beta.102` (from `^4.0.0-beta.101`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
-- 25e8d19: Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.5 — see that version's changelog entries.
+- 25e8d19: Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.5—see that version's changelog entries.
 
 ## 10.0.0-next.8
 
@@ -311,7 +380,7 @@
 
   This is a peer-range-only change with no consumer-visible API consequences. The `beta.99` release only touches `Graph`, CLI (`Command`/`CliConfig`/wizard mode), `Tool` cloning, Redis script eval, and multipart parser internals that Confect doesn't use.
 
-- 2aa7541: Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.2–9.2.4 — see those versions' changelog entries.
+- 2aa7541: Sync with `main`: this prerelease line now includes all changes released in `@confect/*` 9.2.2–9.2.4—see those versions' changelog entries.
 
 ## 10.0.0-next.1
 
@@ -319,7 +388,7 @@
 
 - 4d98ea8: Raise the required `effect` peer version to `^4.0.0-beta.98` (from `^4.0.0-beta.97`).
 
-  `effect`'s `SchemaError` is now exposed as its own public module (`effect/SchemaError`), which changes the import path TypeScript picks when Confect emits `.d.ts` declarations that reference `Schema.SchemaError` (for example in generated `services.d.ts`). Existing `Schema.SchemaError` / `Schema.isSchemaError` usage is unaffected — this is purely a declaration-emit detail that consumers relying on generated types may notice.
+  `effect`'s `SchemaError` is now exposed as its own public module (`effect/SchemaError`), which changes the import path TypeScript picks when Confect emits `.d.ts` declarations that reference `Schema.SchemaError` (for example in generated `services.d.ts`). Existing `Schema.SchemaError`/`Schema.isSchemaError` usage is unaffected—this is purely a declaration-emit detail that consumers relying on generated types may notice.
 
 - Updated dependencies [4d98ea8]
   - @confect/core@10.0.0-next.1
@@ -332,14 +401,14 @@
 
   Breaking changes for users:
   - **Schemas** follow Effect v4's Schema API: `Schema.Union([a, b])` (array form), `Schema.Literals([...])` for literal unions, `Schema.optionalKey` in place of `optionalWith({ exact: true })`, `Schema.TaggedErrorClass` in place of `Schema.TaggedError`, and checks like `Schema.String.check(Schema.isMaxLength(...))` in place of piped filters.
-  - **Option-returning functions** must use a codec with a serializable encoded form, such as `Schema.OptionFromNullOr(...)` — v4's `Schema.Option` encodes to an `Option` instance, which is not a Convex value.
-  - **Table schemas** may now be transformations (`Schema.decodeTo` chains, `Schema.encodeKeys`), branded structs, suspended schemas, or unions of these — Convex's system fields are carried through the whole encoding chain. Schemas that do not resolve to an object shape at every step (such as `Schema.Class`) are rejected with a descriptive error when the table is defined.
+  - **Option-returning functions** must use a codec with a serializable encoded form, such as `Schema.OptionFromNullOr(...)`—v4's `Schema.Option` encodes to an `Option` instance, which is not a Convex value.
+  - **Table schemas** may now be transformations (`Schema.decodeTo` chains, `Schema.encodeKeys`), branded structs, suspended schemas, or unions of these—Convex's system fields are carried through the whole encoding chain. Schemas that do not resolve to an object shape at every step (such as `Schema.Class`) are rejected with a descriptive error when the table is defined.
   - **Clients**: decode failures surface as `SchemaError` rather than `ParseError` in `@confect/js` and `@confect/react`, and `@confect/react`'s `useMutation`/`useAction` handles with an `error` schema now resolve to `Result` (v4's replacement for `Either`).
-  - **HTTP** is now mounted through the renamed `HttpRouter` module (formerly `HttpApi`). `HttpRouter.make(routes)` takes a single route-registering `Layer` composed from Effect's own `effect/unstable/http` and `effect/unstable/httpapi` modules — `HttpApiBuilder.layer(api)` (with group handler layers supplied via `Layer.provide`; a missing group is a compile-time error), `HttpApiScalar.layer` for docs, `HttpRouter.add` for plain routes, and `HttpRouter.middleware(fn, { global: true })` for middleware, merged with `Layer.mergeAll`. The per-path-prefix record and its `api`/`apiLive`/`middleware`/`scalar` options are gone; Confect registers one catch-all Convex HTTP action at `/`, and plain Convex routes added to the returned router still take precedence. Handlers, middleware, and route-layer construction all run with Confect's Convex-aware `ConfigProvider` in context.
+  - **HTTP** is now mounted through the renamed `HttpRouter` module (formerly `HttpApi`). `HttpRouter.make(routes)` takes a single route-registering `Layer` composed from Effect's own `effect/unstable/http` and `effect/unstable/httpapi` modules—`HttpApiBuilder.layer(api)` (with group handler layers supplied via `Layer.provide`; a missing group is a compile-time error), `HttpApiScalar.layer` for docs, `HttpRouter.add` for plain routes, and `HttpRouter.middleware(fn, { global: true })` for middleware, merged with `Layer.mergeAll`. The per-path-prefix record and its `api`/`apiLive`/`middleware`/`scalar` options are gone; Confect registers one catch-all Convex HTTP action at `/`, and plain Convex routes added to the returned router still take precedence. Handlers, middleware, and route-layer construction all run with Confect's Convex-aware `ConfigProvider` in context.
   - **Node actions** use `effect/unstable/process` (`ChildProcessSpawner`) and `@effect/platform-node`'s `NodeServices` in place of `@effect/platform` `Command`/`NodeContext`.
   - **Configuration**: Confect's Convex-aware `ConfigProvider` treats empty-string environment variables as missing values (matching Effect v4's built-in providers), so `Config.withDefault` and `Config.option` recover from them.
   - **CLI**: a malformed `convex.json` now fails codegen with a descriptive error instead of being silently ignored.
-  - Confect queries no longer stub the global `Date.now`. Queries run with a `Clock` whose unsafe accessors return constants, so Effect-internal reads (log timestamps, spans) never evict a query from Convex's cache; explicit time reads — `Clock.currentTimeMillis`/`currentTimeNanos` or a raw `Date.now()` call — opt the query out and evict as they honestly should.
+  - Confect queries no longer stub the global `Date.now`. Queries run with a `Clock` whose unsafe accessors return constants, so Effect-internal reads (log timestamps, spans) never evict a query from Convex's cache; explicit time reads—`Clock.currentTimeMillis`/`currentTimeNanos` or a raw `Date.now()` call—opt the query out and evict as they honestly should.
 
 ### Patch Changes
 
@@ -362,7 +431,7 @@
 
 - 16b5ad6: Add first-class paginated queries: declare one with `FunctionSpec.publicPaginatedQuery` (or `internalPaginatedQuery`) and read it with the new `usePaginatedQuery` hook from `@confect/react`.
 
-  Pass an `item` schema — the type of one element in a page — in place of `returns`, plus an optional `args` struct for your own arguments. The handler receives `paginationOpts` alongside them and forwards it to `paginate`.
+  Pass an `item` schema—the type of one element in a page—in place of `returns`, plus an optional `args` struct for your own arguments. The handler receives `paginationOpts` alongside them and forwards it to `paginate`.
 
   ```ts
   // confect/notes.spec.ts
@@ -487,7 +556,7 @@
 
 - 445ea9b: Loosen and align dependency ranges across all packages:
   - The `convex` peer dependency is now `^1.32.0` in every package (previously pinned exactly to `1.39.1`, or `^1.30.0` in `@confect/react`). The range is validated against convex 1.32.0 through 1.40.0.
-  - `@confect/server`'s `@effect/platform-node` peer dependency is now optional — it is only needed when using the `@confect/server/node` entrypoint.
+  - `@confect/server`'s `@effect/platform-node` peer dependency is now optional—it is only needed when using the `@confect/server/node` entrypoint.
   - `@confect/cli` now uses caret ranges for its `@effect/platform` and `@effect/platform-node` dependencies so they can deduplicate with the versions resolved for `@confect/server`, and no longer declares an unused direct dependency on `@effect/platform-node-shared`.
   - `@confect/test` now accepts any `convex-test` release in `>=0.0.50 <0.1.0` instead of exactly 0.0.50.
 
@@ -506,8 +575,8 @@
 
   Your API is now authored as colocated `*.spec.ts`/`*.impl.ts` pairs, one pair per group, and **the file's path within `confect/` is the group's name** (its stem for top-level groups, the dot-joined directory path for nested groups). `GroupSpec.make()` and `GroupSpec.makeNode()` no longer take a name argument.
   - Each `*.spec.ts` `export default`s its `GroupSpec` (named co-exports like error classes are still allowed).
-  - Each `*.impl.ts` default-imports its sibling spec, passes it to `FunctionImpl.make` / `GroupImpl.make`, and ends the layer pipeline with `GroupImpl.finalize`—a compile-time completeness check that only typechecks once every function the spec declares has a `FunctionImpl` provided.
-  - The root `confect/spec.ts`, `confect/impl.ts`, `confect/nodeSpec.ts`, and `confect/nodeImpl.ts` files are gone, along with `Impl.make` and `Impl.finalize`. `confect codegen` deletes any of these (and the stale aggregate `_generated/registeredFunctions.ts` / `_generated/nodeRegisteredFunctions.ts`) on upgrade.
+  - Each `*.impl.ts` default-imports its sibling spec, passes it to `FunctionImpl.make`/`GroupImpl.make`, and ends the layer pipeline with `GroupImpl.finalize`—a compile-time completeness check that only typechecks once every function the spec declares has a `FunctionImpl` provided.
+  - The root `confect/spec.ts`, `confect/impl.ts`, `confect/nodeSpec.ts`, and `confect/nodeImpl.ts` files are gone, along with `Impl.make` and `Impl.finalize`. `confect codegen` deletes any of these (and the stale aggregate `_generated/registeredFunctions.ts`/`_generated/nodeRegisteredFunctions.ts`) on upgrade.
 
   ### Tables are the source of truth, named by their filename
 
@@ -538,7 +607,7 @@
 
   ### Specs and impls: lazy schemas, and impls take the `DatabaseSchema`
 
-  `FunctionSpec.*` constructors now take `args`, `returns`, and the optional `error` as `() => Schema` thunks, so importing a spec builds no schemas until a function is invoked. `FunctionImpl.make` and `GroupImpl.make` take the runtime `DatabaseSchema` (the default export of `_generated/schema`) as their first argument instead of the whole `Api`—which keeps the project-wide spec graph out of a function's cold-start module graph. The `Api` module (`Api.make`, the `Api` type) and the generated `_generated/api.ts` / `_generated/nodeApi.ts` files are removed.
+  `FunctionSpec.*` constructors now take `args`, `returns`, and the optional `error` as `() => Schema` thunks, so importing a spec builds no schemas until a function is invoked. `FunctionImpl.make` and `GroupImpl.make` take the runtime `DatabaseSchema` (the default export of `_generated/schema`) as their first argument instead of the whole `Api`—which keeps the project-wide spec graph out of a function's cold-start module graph. The `Api` module (`Api.make`, the `Api` type) and the generated `_generated/api.ts`/`_generated/nodeApi.ts` files are removed.
 
   **Before:**
 
@@ -586,7 +655,7 @@
 
   A group's runtime is now declared solely by its spec—`GroupSpec.makeNode()` for a Node action group, `GroupSpec.make()` otherwise—mirroring vanilla Convex's per-file `"use node"` directive. The separate `node` namespace is gone: Node specs/impls are ordinary colocated pairs that can live anywhere in `confect/`, and codegen emits the `"use node"` directive based on the spec.
   - A Node group at `confect/email.spec.ts` is now reached at `refs.public.email.send` instead of `refs.public.node.email.send`.
-  - `@confect/core` removes `Spec.makeNode`, `Spec.merge`, and `Spec.isConvexSpec` / `Spec.isNodeSpec`; `Spec.make()` is a single mixed-runtime container and `Refs.make(spec)` takes one argument. `GroupSpec.makeNode()`, `FunctionSpec.publicNodeAction()` / `internalNodeAction()` are unchanged.
+  - `@confect/core` removes `Spec.makeNode`, `Spec.merge`, and `Spec.isConvexSpec`/`Spec.isNodeSpec`; `Spec.make()` is a single mixed-runtime container and `Refs.make(spec)` takes one argument. `GroupSpec.makeNode()`, `FunctionSpec.publicNodeAction()`/`internalNodeAction()` are unchanged.
 
   ### Less work at cold start
 
@@ -603,7 +672,7 @@
   ### Migration
   1. **Tables.** Delete `confect/schema.ts`. Rename each table file to a valid JS identifier (e.g. `confect/tables/notes.ts`); the basename becomes the table name. Drop the name argument from `Table.make`, wrap the field struct in `() =>`, and replace `GenericId.GenericId("x")` with `Id("x")` from `_generated/id`. If you read `table.name` off a bound table, rename it to `table.tableName`.
   2. **Specs.** Split each group into a colocated `*.spec.ts` that `export default`s `GroupSpec.make()` (no name). Wrap every `args`/`returns`/`error` in `() =>`. Import a table's `Doc`/`Fields` from its wrapper, `import notes from "./_generated/tables/notes"`.
-  3. **Impls.** In each `*.impl.ts`, default-import the sibling spec, import `databaseSchema` from `_generated/schema`, pass it to `FunctionImpl.make` / `GroupImpl.make` in place of `api`, end the pipeline with `GroupImpl.finalize`, and `export default` it. Delete the root `confect/spec.ts`, `impl.ts`, `nodeSpec.ts`, and `nodeImpl.ts` (codegen will also remove them).
+  3. **Impls.** In each `*.impl.ts`, default-import the sibling spec, import `databaseSchema` from `_generated/schema`, pass it to `FunctionImpl.make`/`GroupImpl.make` in place of `api`, end the pipeline with `GroupImpl.finalize`, and `export default` it. Delete the root `confect/spec.ts`, `impl.ts`, `nodeSpec.ts`, and `nodeImpl.ts` (codegen will also remove them).
   4. **Node groups.** Move any `confect/node/<path>` files anywhere you like under `confect/`; the `node/` directory no longer has special meaning. Drop the `node` segment from call sites (`refs.public.node.<group>` → `refs.public.<group>`) and replace `Refs.make(spec, nodeSpec)` with `Refs.make(spec)`.
   5. **Tests.** If you use `@confect/test`, import `confectSchema` from `_generated/schema`, import the generated `convexSchema` from `_generated/convexSchema`, and pass `convexSchema` as the new second argument to `TestConfect.layer`.
   6. **Optional.** Adopt submodule Effect imports (`import * as Schema from "effect/Schema"`) in your own `confect/` files for the full cold-start savings.
@@ -647,11 +716,11 @@
 
   ### Why
 
-  A barrel import of a namespace re-export defeats esbuild's tree-shaking: accessing `Schema.X` from `import { Schema } from "effect"` retains the _entire_ `Schema` namespace, because the bundler can't prune property access on the barrel's `export * as Schema`. So every Convex function's cold-start bundle was pulling all of `effect/Schema` and `effect/Stream` — and, transitively through Schema's `Arbitrary`, `fast-check` — whether the function used them or not.
+  A barrel import of a namespace re-export defeats esbuild's tree-shaking: accessing `Schema.X` from `import { Schema } from "effect"` retains the _entire_ `Schema` namespace, because the bundler can't prune property access on the barrel's `export * as Schema`. So every Convex function's cold-start bundle was pulling all of `effect/Schema` and `effect/Stream`—and, transitively through Schema's `Arbitrary`, `fast-check`—whether the function used them or not.
 
   Importing from the submodule path tree-shakes normally. On a minimal function this cut the bundle esbuild produces by ~54% (the `effect/Schema` module alone by ~75%) and its cold-start module-evaluation time by ~35%, with `fast-check` dropped entirely. This is also the import style Effect v4 recommends, so it's forward-compatible. A `no-restricted-imports` ESLint rule now enforces it across the codebase (type-only imports and `@effect/vitest` are exempt).
 
-  No API changes — your existing code keeps working.
+  No API changes—your existing code keeps working.
 
   ### Getting the full win in your own code
 

package/dist/PaginatedQueryResult.d.ts

@@ -5,7 +5,7 @@ type TypeId = typeof TypeId;
  * A `PaginatedQueryResult` represents the result of a Confect paginated query.
  * The non-`Failure` variants mirror the statuses of `usePaginatedQuery` from
  * `convex/react` and all carry `results` and `isLoading`, so the common UI
- * shape — render the list, show a spinner while loading — needs only an
+ * shape—render the list, show a spinner while loading—needs only an
  * {@link isFailure} early-out and plain field access.
  *
  * Every variant carries `results`, including `Failure`: when a later page
@@ -16,8 +16,8 @@ type TypeId = typeof TypeId;
  * `loadMore` appears only on `CanLoadMore`, the one state it can make
  * progress from. The underlying Convex hook exposes it on every status, but
  * calling it while a page is in flight, once the list is exhausted, or after
- * a failure is an intentional no-op there; narrowing to `CanLoadMore` — via
- * {@link isCanLoadMore} or {@link match} — makes that statically apparent
+ * a failure is an intentional no-op there; narrowing to `CanLoadMore`—via
+ * {@link isCanLoadMore} or {@link match}—makes that statically apparent
  * instead of silently dropping the call.
  *
  * When the query declares no `error` schema (`E` is `never`), the `Failure`
@@ -29,7 +29,7 @@ type TypeId = typeof TypeId;
  */
 export type PaginatedQueryResult<Item, E = never> = [E] extends [never] ? LoadingFirstPage<Item, E> | LoadingMore<Item, E> | CanLoadMore<Item, E> | Exhausted<Item, E> : LoadingFirstPage<Item, E> | LoadingMore<Item, E> | CanLoadMore<Item, E> | Exhausted<Item, E> | Failure<Item, E>;
 /**
- * Every variant regardless of `E` — the parameter type for guards and
+ * Every variant regardless of `E`—the parameter type for guards and
  * {@link match}, since `PaginatedQueryResult` itself excludes `Failure` when
  * `E` is `never`.
  */

package/dist/PaginatedQueryResult.js.map

@@ -1 +1 @@
-{"version":3,"file":"PaginatedQueryResult.js","names":[],"sources":["../src/PaginatedQueryResult.ts"],"sourcesContent":["import * as Equal from \"effect/Equal\";\nimport * as Function from \"effect/Function\";\nimport * as Hash from \"effect/Hash\";\nimport * as Match from \"effect/Match\";\nimport * as Pipeable from \"effect/Pipeable\";\nimport * as Predicate from \"effect/Predicate\";\n\nconst TypeId = \"~@confect/react/PaginatedQueryResult\";\ntype TypeId = typeof TypeId;\n\n/**\n * A `PaginatedQueryResult` represents the result of a Confect paginated query.\n * The non-`Failure` variants mirror the statuses of `usePaginatedQuery` from\n * `convex/react` and all carry `results` and `isLoading`, so the common UI\n * shape — render the list, show a spinner while loading — needs only an\n * {@link isFailure} early-out and plain field access.\n *\n * Every variant carries `results`, including `Failure`: when a later page\n * fails, the pages already loaded are still worth rendering alongside the\n * error, so they are not discarded. `Failure` additionally carries the\n * query's decoded typed error.\n *\n * `loadMore` appears only on `CanLoadMore`, the one state it can make\n * progress from. The underlying Convex hook exposes it on every status, but\n * calling it while a page is in flight, once the list is exhausted, or after\n * a failure is an intentional no-op there; narrowing to `CanLoadMore` — via\n * {@link isCanLoadMore} or {@link match} — makes that statically apparent\n * instead of silently dropping the call.\n *\n * When the query declares no `error` schema (`E` is `never`), the `Failure`\n * variant is excluded from the type entirely, so `isLoading` is accessible\n * without any narrowing.\n *\n * @typeParam Item - The type of a decoded page item.\n * @typeParam E - The type of the decoded typed error in the `Failure` variant.\n */\nexport type PaginatedQueryResult<Item, E = never> = [E] extends [never]\n  ?\n      | LoadingFirstPage<Item, E>\n      | LoadingMore<Item, E>\n      | CanLoadMore<Item, E>\n      | Exhausted<Item, E>\n  :\n      | LoadingFirstPage<Item, E>\n      | LoadingMore<Item, E>\n      | CanLoadMore<Item, E>\n      | Exhausted<Item, E>\n      | Failure<Item, E>;\n\n/**\n * Every variant regardless of `E` — the parameter type for guards and\n * {@link match}, since `PaginatedQueryResult` itself excludes `Failure` when\n * `E` is `never`.\n */\nexport type Variants<Item, E = never> =\n  | LoadingFirstPage<Item, E>\n  | LoadingMore<Item, E>\n  | CanLoadMore<Item, E>\n  | Exhausted<Item, E>\n  | Failure<Item, E>;\n\nexport declare namespace PaginatedQueryResult {\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export interface Proto<out Item, out E> extends Pipeable.Pipeable {\n    readonly [TypeId]: TypeId;\n    readonly \"~Item\": Item;\n    readonly \"~E\": E;\n  }\n\n  export type Item<R> = R extends { readonly \"~Item\": infer Item_ }\n    ? Item_\n    : never;\n\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export type Failure<R> = R extends { readonly \"~E\": infer E } ? E : never;\n}\n\nexport interface LoadingFirstPage<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"LoadingFirstPage\";\n  readonly skipped: boolean;\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: true;\n}\n\nexport interface LoadingMore<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"LoadingMore\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: true;\n}\n\nexport interface CanLoadMore<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"CanLoadMore\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: false;\n  readonly loadMore: (numItems: number) => void;\n}\n\nexport interface Exhausted<Item, E = never> extends PaginatedQueryResult.Proto<\n  Item,\n  E\n> {\n  readonly _tag: \"Exhausted\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: false;\n}\n\nexport interface Failure<Item, E = never> extends PaginatedQueryResult.Proto<\n  Item,\n  E\n> {\n  readonly _tag: \"Failure\";\n  readonly error: E;\n  /** The pages loaded before the failure. */\n  readonly results: ReadonlyArray<Item>;\n}\n\nexport const isPaginatedQueryResult = (\n  u: unknown,\n): u is Variants<unknown, unknown> => Predicate.hasProperty(u, TypeId);\n\nconst PaginatedQueryResultProto = {\n  [TypeId]: TypeId,\n  pipe(this: Variants<any, any>, ...args: ReadonlyArray<unknown>) {\n    return Pipeable.pipeArguments(\n      this,\n      args as unknown as Parameters<typeof Pipeable.pipeArguments>[1],\n    );\n  },\n  /**\n   * `CanLoadMore`'s `loadMore` is excluded from equality and hashing, like\n   * function fields generally: two results that render identically are equal\n   * even though their callbacks differ by identity.\n   */\n  [Equal.symbol](this: Variants<any, any>, that: Variants<any, any>): boolean {\n    if (this._tag !== that._tag) {\n      return false;\n    }\n    return Match.value(this).pipe(\n      Match.tag(\n        \"LoadingFirstPage\",\n        (self) => self.skipped === (that as LoadingFirstPage<any, any>).skipped,\n      ),\n      Match.tag(\"LoadingMore\", \"CanLoadMore\", \"Exhausted\", (self) =>\n        Equal.equals(self.results, that.results),\n      ),\n      Match.tag(\n        \"Failure\",\n        (self) =>\n          Equal.equals(self.error, (that as Failure<any, any>).error) &&\n          Equal.equals(self.results, (that as Failure<any, any>).results),\n      ),\n      Match.exhaustive,\n    );\n  },\n  [Hash.symbol](this: Variants<any, any>): number {\n    const tagHash = Hash.string(this._tag);\n    return Match.value(this).pipe(\n      Match.tag(\"LoadingFirstPage\", (self) =>\n        Hash.combine(tagHash)(Hash.hash(self.skipped)),\n      ),\n      Match.tag(\"LoadingMore\", \"CanLoadMore\", \"Exhausted\", (self) =>\n        Hash.combine(tagHash)(Hash.hash(self.results)),\n      ),\n      Match.tag(\"Failure\", (self) =>\n        Hash.combine(tagHash)(\n          Hash.combine(Hash.hash(self.error))(Hash.hash(self.results)),\n        ),\n      ),\n      Match.exhaustive,\n    );\n  },\n};\n\nconst noResults: ReadonlyArray<never> = [];\n\nexport const loadingFirstPage = <Item = never, E = never>(options: {\n  skipped: boolean;\n}): LoadingFirstPage<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"LoadingFirstPage\" as const,\n    skipped: options.skipped,\n    results: noResults,\n    isLoading: true as const,\n  });\n\nexport const loadingMore = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n}): LoadingMore<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"LoadingMore\" as const,\n    results: options.results,\n    isLoading: true as const,\n  });\n\nexport const canLoadMore = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n  loadMore: (numItems: number) => void;\n}): CanLoadMore<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"CanLoadMore\" as const,\n    results: options.results,\n    isLoading: false as const,\n    loadMore: options.loadMore,\n  });\n\nexport const exhausted = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n}): Exhausted<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"Exhausted\" as const,\n    results: options.results,\n    isLoading: false as const,\n  });\n\nexport const failure = <E, Item = never>(options: {\n  error: E;\n  results: ReadonlyArray<Item>;\n}): Failure<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"Failure\" as const,\n    error: options.error,\n    results: options.results,\n  });\n\nexport const isLoadingFirstPage = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingFirstPage<Item, E> => result._tag === \"LoadingFirstPage\";\n\nexport const isLoadingMore = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingMore<Item, E> => result._tag === \"LoadingMore\";\n\nexport const isCanLoadMore = <Item, E>(\n  result: Variants<Item, E>,\n): result is CanLoadMore<Item, E> => result._tag === \"CanLoadMore\";\n\nexport const isExhausted = <Item, E>(\n  result: Variants<Item, E>,\n): result is Exhausted<Item, E> => result._tag === \"Exhausted\";\n\nexport const isFailure = <Item, E>(\n  result: Variants<Item, E>,\n): result is Failure<Item, E> => result._tag === \"Failure\";\n\nexport const isLoading = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingFirstPage<Item, E> | LoadingMore<Item, E> =>\n  result._tag === \"LoadingFirstPage\" || result._tag === \"LoadingMore\";\n\ntype MatchOptions<Item, E, V, W, X, Y, Z> = {\n  readonly onLoadingFirstPage: (skipped: boolean) => V;\n  readonly onLoadingMore: (results: ReadonlyArray<Item>) => W;\n  readonly onCanLoadMore: (\n    results: ReadonlyArray<Item>,\n    loadMore: (numItems: number) => void,\n  ) => X;\n  readonly onExhausted: (results: ReadonlyArray<Item>) => Y;\n} & ([E] extends [never]\n  ? {}\n  : {\n      readonly onFailure: (error: E, results: ReadonlyArray<Item>) => Z;\n    });\n\ntype MatchReturns<E, V, W, X, Y, Z> = [E] extends [never]\n  ? V | W | X | Y\n  : V | W | X | Y | Z;\n\n/**\n * Matches a {@link PaginatedQueryResult} to the appropriate handler based on\n * its tag. If the provided result cannot fail (i.e. `E` is `never`),\n * `onFailure` is not required.\n */\nexport const match: {\n  <Item, E, V, W, X, Y, Z = never>(\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): (self: Variants<Item, E>) => MatchReturns<E, V, W, X, Y, Z>;\n  <Item, E, V, W, X, Y, Z = never>(\n    self: Variants<Item, E>,\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): MatchReturns<E, V, W, X, Y, Z>;\n} = Function.dual(\n  2,\n  <Item, E, V, W, X, Y, Z = never>(\n    self: Variants<Item, E>,\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): MatchReturns<E, V, W, X, Y, Z> =>\n    Match.value(self).pipe(\n      Match.tag(\"LoadingFirstPage\", (loadingFirstPage_) =>\n        options.onLoadingFirstPage(loadingFirstPage_.skipped),\n      ),\n      Match.tag(\"LoadingMore\", (loadingMore_) =>\n        options.onLoadingMore(loadingMore_.results),\n      ),\n      Match.tag(\"CanLoadMore\", (canLoadMore_) =>\n        options.onCanLoadMore(canLoadMore_.results, canLoadMore_.loadMore),\n      ),\n      Match.tag(\"Exhausted\", (exhausted_) =>\n        options.onExhausted(exhausted_.results),\n      ),\n      Match.tag(\"Failure\", (failure_) => {\n        if (Predicate.hasProperty(options, \"onFailure\")) {\n          return options.onFailure(failure_.error, failure_.results);\n        }\n        throw new Error(\n          \"`onFailure` is required when error schema is provided\",\n        );\n      }),\n      Match.exhaustive,\n    ) as MatchReturns<E, V, W, X, Y, Z>,\n);\n"],"mappings":"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"}
+{"version":3,"file":"PaginatedQueryResult.js","names":[],"sources":["../src/PaginatedQueryResult.ts"],"sourcesContent":["import * as Equal from \"effect/Equal\";\nimport * as Function from \"effect/Function\";\nimport * as Hash from \"effect/Hash\";\nimport * as Match from \"effect/Match\";\nimport * as Pipeable from \"effect/Pipeable\";\nimport * as Predicate from \"effect/Predicate\";\n\nconst TypeId = \"~@confect/react/PaginatedQueryResult\";\ntype TypeId = typeof TypeId;\n\n/**\n * A `PaginatedQueryResult` represents the result of a Confect paginated query.\n * The non-`Failure` variants mirror the statuses of `usePaginatedQuery` from\n * `convex/react` and all carry `results` and `isLoading`, so the common UI\n * shape—render the list, show a spinner while loading—needs only an\n * {@link isFailure} early-out and plain field access.\n *\n * Every variant carries `results`, including `Failure`: when a later page\n * fails, the pages already loaded are still worth rendering alongside the\n * error, so they are not discarded. `Failure` additionally carries the\n * query's decoded typed error.\n *\n * `loadMore` appears only on `CanLoadMore`, the one state it can make\n * progress from. The underlying Convex hook exposes it on every status, but\n * calling it while a page is in flight, once the list is exhausted, or after\n * a failure is an intentional no-op there; narrowing to `CanLoadMore`—via\n * {@link isCanLoadMore} or {@link match}—makes that statically apparent\n * instead of silently dropping the call.\n *\n * When the query declares no `error` schema (`E` is `never`), the `Failure`\n * variant is excluded from the type entirely, so `isLoading` is accessible\n * without any narrowing.\n *\n * @typeParam Item - The type of a decoded page item.\n * @typeParam E - The type of the decoded typed error in the `Failure` variant.\n */\nexport type PaginatedQueryResult<Item, E = never> = [E] extends [never]\n  ?\n      | LoadingFirstPage<Item, E>\n      | LoadingMore<Item, E>\n      | CanLoadMore<Item, E>\n      | Exhausted<Item, E>\n  :\n      | LoadingFirstPage<Item, E>\n      | LoadingMore<Item, E>\n      | CanLoadMore<Item, E>\n      | Exhausted<Item, E>\n      | Failure<Item, E>;\n\n/**\n * Every variant regardless of `E`—the parameter type for guards and\n * {@link match}, since `PaginatedQueryResult` itself excludes `Failure` when\n * `E` is `never`.\n */\nexport type Variants<Item, E = never> =\n  | LoadingFirstPage<Item, E>\n  | LoadingMore<Item, E>\n  | CanLoadMore<Item, E>\n  | Exhausted<Item, E>\n  | Failure<Item, E>;\n\nexport declare namespace PaginatedQueryResult {\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export interface Proto<out Item, out E> extends Pipeable.Pipeable {\n    readonly [TypeId]: TypeId;\n    readonly \"~Item\": Item;\n    readonly \"~E\": E;\n  }\n\n  export type Item<R> = R extends { readonly \"~Item\": infer Item_ }\n    ? Item_\n    : never;\n\n  // eslint-disable-next-line @typescript-eslint/no-shadow\n  export type Failure<R> = R extends { readonly \"~E\": infer E } ? E : never;\n}\n\nexport interface LoadingFirstPage<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"LoadingFirstPage\";\n  readonly skipped: boolean;\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: true;\n}\n\nexport interface LoadingMore<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"LoadingMore\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: true;\n}\n\nexport interface CanLoadMore<\n  Item,\n  E = never,\n> extends PaginatedQueryResult.Proto<Item, E> {\n  readonly _tag: \"CanLoadMore\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: false;\n  readonly loadMore: (numItems: number) => void;\n}\n\nexport interface Exhausted<Item, E = never> extends PaginatedQueryResult.Proto<\n  Item,\n  E\n> {\n  readonly _tag: \"Exhausted\";\n  readonly results: ReadonlyArray<Item>;\n  readonly isLoading: false;\n}\n\nexport interface Failure<Item, E = never> extends PaginatedQueryResult.Proto<\n  Item,\n  E\n> {\n  readonly _tag: \"Failure\";\n  readonly error: E;\n  /** The pages loaded before the failure. */\n  readonly results: ReadonlyArray<Item>;\n}\n\nexport const isPaginatedQueryResult = (\n  u: unknown,\n): u is Variants<unknown, unknown> => Predicate.hasProperty(u, TypeId);\n\nconst PaginatedQueryResultProto = {\n  [TypeId]: TypeId,\n  pipe(this: Variants<any, any>, ...args: ReadonlyArray<unknown>) {\n    return Pipeable.pipeArguments(\n      this,\n      args as unknown as Parameters<typeof Pipeable.pipeArguments>[1],\n    );\n  },\n  /**\n   * `CanLoadMore`'s `loadMore` is excluded from equality and hashing, like\n   * function fields generally: two results that render identically are equal\n   * even though their callbacks differ by identity.\n   */\n  [Equal.symbol](this: Variants<any, any>, that: Variants<any, any>): boolean {\n    if (this._tag !== that._tag) {\n      return false;\n    }\n    return Match.value(this).pipe(\n      Match.tag(\n        \"LoadingFirstPage\",\n        (self) => self.skipped === (that as LoadingFirstPage<any, any>).skipped,\n      ),\n      Match.tag(\"LoadingMore\", \"CanLoadMore\", \"Exhausted\", (self) =>\n        Equal.equals(self.results, that.results),\n      ),\n      Match.tag(\n        \"Failure\",\n        (self) =>\n          Equal.equals(self.error, (that as Failure<any, any>).error) &&\n          Equal.equals(self.results, (that as Failure<any, any>).results),\n      ),\n      Match.exhaustive,\n    );\n  },\n  [Hash.symbol](this: Variants<any, any>): number {\n    const tagHash = Hash.string(this._tag);\n    return Match.value(this).pipe(\n      Match.tag(\"LoadingFirstPage\", (self) =>\n        Hash.combine(tagHash)(Hash.hash(self.skipped)),\n      ),\n      Match.tag(\"LoadingMore\", \"CanLoadMore\", \"Exhausted\", (self) =>\n        Hash.combine(tagHash)(Hash.hash(self.results)),\n      ),\n      Match.tag(\"Failure\", (self) =>\n        Hash.combine(tagHash)(\n          Hash.combine(Hash.hash(self.error))(Hash.hash(self.results)),\n        ),\n      ),\n      Match.exhaustive,\n    );\n  },\n};\n\nconst noResults: ReadonlyArray<never> = [];\n\nexport const loadingFirstPage = <Item = never, E = never>(options: {\n  skipped: boolean;\n}): LoadingFirstPage<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"LoadingFirstPage\" as const,\n    skipped: options.skipped,\n    results: noResults,\n    isLoading: true as const,\n  });\n\nexport const loadingMore = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n}): LoadingMore<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"LoadingMore\" as const,\n    results: options.results,\n    isLoading: true as const,\n  });\n\nexport const canLoadMore = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n  loadMore: (numItems: number) => void;\n}): CanLoadMore<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"CanLoadMore\" as const,\n    results: options.results,\n    isLoading: false as const,\n    loadMore: options.loadMore,\n  });\n\nexport const exhausted = <Item, E = never>(options: {\n  results: ReadonlyArray<Item>;\n}): Exhausted<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"Exhausted\" as const,\n    results: options.results,\n    isLoading: false as const,\n  });\n\nexport const failure = <E, Item = never>(options: {\n  error: E;\n  results: ReadonlyArray<Item>;\n}): Failure<Item, E> =>\n  Object.assign(Object.create(PaginatedQueryResultProto), {\n    _tag: \"Failure\" as const,\n    error: options.error,\n    results: options.results,\n  });\n\nexport const isLoadingFirstPage = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingFirstPage<Item, E> => result._tag === \"LoadingFirstPage\";\n\nexport const isLoadingMore = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingMore<Item, E> => result._tag === \"LoadingMore\";\n\nexport const isCanLoadMore = <Item, E>(\n  result: Variants<Item, E>,\n): result is CanLoadMore<Item, E> => result._tag === \"CanLoadMore\";\n\nexport const isExhausted = <Item, E>(\n  result: Variants<Item, E>,\n): result is Exhausted<Item, E> => result._tag === \"Exhausted\";\n\nexport const isFailure = <Item, E>(\n  result: Variants<Item, E>,\n): result is Failure<Item, E> => result._tag === \"Failure\";\n\nexport const isLoading = <Item, E>(\n  result: Variants<Item, E>,\n): result is LoadingFirstPage<Item, E> | LoadingMore<Item, E> =>\n  result._tag === \"LoadingFirstPage\" || result._tag === \"LoadingMore\";\n\ntype MatchOptions<Item, E, V, W, X, Y, Z> = {\n  readonly onLoadingFirstPage: (skipped: boolean) => V;\n  readonly onLoadingMore: (results: ReadonlyArray<Item>) => W;\n  readonly onCanLoadMore: (\n    results: ReadonlyArray<Item>,\n    loadMore: (numItems: number) => void,\n  ) => X;\n  readonly onExhausted: (results: ReadonlyArray<Item>) => Y;\n} & ([E] extends [never]\n  ? {}\n  : {\n      readonly onFailure: (error: E, results: ReadonlyArray<Item>) => Z;\n    });\n\ntype MatchReturns<E, V, W, X, Y, Z> = [E] extends [never]\n  ? V | W | X | Y\n  : V | W | X | Y | Z;\n\n/**\n * Matches a {@link PaginatedQueryResult} to the appropriate handler based on\n * its tag. If the provided result cannot fail (i.e. `E` is `never`),\n * `onFailure` is not required.\n */\nexport const match: {\n  <Item, E, V, W, X, Y, Z = never>(\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): (self: Variants<Item, E>) => MatchReturns<E, V, W, X, Y, Z>;\n  <Item, E, V, W, X, Y, Z = never>(\n    self: Variants<Item, E>,\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): MatchReturns<E, V, W, X, Y, Z>;\n} = Function.dual(\n  2,\n  <Item, E, V, W, X, Y, Z = never>(\n    self: Variants<Item, E>,\n    options: MatchOptions<Item, E, V, W, X, Y, Z>,\n  ): MatchReturns<E, V, W, X, Y, Z> =>\n    Match.value(self).pipe(\n      Match.tag(\"LoadingFirstPage\", (loadingFirstPage_) =>\n        options.onLoadingFirstPage(loadingFirstPage_.skipped),\n      ),\n      Match.tag(\"LoadingMore\", (loadingMore_) =>\n        options.onLoadingMore(loadingMore_.results),\n      ),\n      Match.tag(\"CanLoadMore\", (canLoadMore_) =>\n        options.onCanLoadMore(canLoadMore_.results, canLoadMore_.loadMore),\n      ),\n      Match.tag(\"Exhausted\", (exhausted_) =>\n        options.onExhausted(exhausted_.results),\n      ),\n      Match.tag(\"Failure\", (failure_) => {\n        if (Predicate.hasProperty(options, \"onFailure\")) {\n          return options.onFailure(failure_.error, failure_.results);\n        }\n        throw new Error(\n          \"`onFailure` is required when error schema is provided\",\n        );\n      }),\n      Match.exhaustive,\n    ) as MatchReturns<E, V, W, X, Y, Z>,\n);\n"],"mappings":"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"}

package/dist/StreamPagination.d.ts

@@ -0,0 +1,127 @@
+/**
+ * EXPERIMENTAL—the pure state machine behind {@link useStreamPaginatedQuery}
+ * (see `notes/stream-based-querying.md` in the repo root).
+ *
+ * Reactive pagination without the query journal: every loaded page—including the first—is pinned to a fixed index range by echoing its
+ * `continueCursor` back as the next subscription's `endCursor` (the last
+ * page pins to the end-of-stream sentinel once exhausted), so adjacent
+ * pages stay exactly contiguous and pages never shed items as data changes—the "range-defined pages" the Fully Reactive Pagination article calls
+ * for, and the mechanism of `convex-helpers/react`'s `usePaginatedQuery`.
+ *
+ * Pinning a freshly loaded page, loading more, and splitting an overgrown
+ * page are the same transition shape: the affected page keeps rendering
+ * while its replacement subscriptions ("ongoing split") load, and is
+ * swapped out once all of them have results.
+ *
+ * This module is framework-free (it imports only `effect/*` and a type
+ * from `convex/server`); it lives here for now because the React hook is
+ * its only consumer—a second client (e.g. `@confect/foldkit`) should
+ * prompt a move down to `@confect/js`.
+ */
+import type { PaginationResult } from "convex/server";
+import * as Option from "effect/Option";
+import * as Record from "effect/Record";
+/** The `paginationOpts` one subscribed page queries with. */
+export interface PageRequest {
+    readonly numItems: number;
+    readonly cursor: string | null;
+    /** Present once the page is pinned to a fixed range. */
+    readonly endCursor?: string;
+    /**
+     * Per-page read budgets, forwarded to the server so a scan-heavy page
+     * fails over to `SplitRequired` instead of exceeding query limits.
+     */
+    readonly maximumRowsRead?: number;
+    readonly maximumBytesRead?: number;
+}
+/** The per-page read budgets every growing page is requested with. */
+export interface ReadBudget {
+    readonly maximumRowsRead?: number | undefined;
+    readonly maximumBytesRead?: number | undefined;
+}
+export interface State {
+    readonly nextPageKey: number;
+    /** Page keys in display order. */
+    readonly pageKeys: ReadonlyArray<string>;
+    /** The request each subscribed page queries with, by page key. */
+    readonly pages: Record.ReadonlyRecord<string, PageRequest>;
+    /**
+     * Pages being replaced by one (a pin) or two (a split) narrower
+     * subscriptions: the original stays subscribed (and rendered) until every
+     * replacement has a result.
+     */
+    readonly ongoingSplits: Record.ReadonlyRecord<string, ReadonlyArray<string>>;
+}
+/** The skipped state: nothing subscribed. */
+export declare const empty: State;
+/** One growing (unpinned) page from the start of the stream. */
+export declare const initial: (initialNumItems: number, budget?: ReadBudget) => State;
+/**
+ * Pin a freshly loaded growing page at its `continueCursor` (or, once
+ * exhausted, at the end-of-stream sentinel), so it stops being a sliding
+ * window: a pinned page grows and shrinks with the data in its range but
+ * never sheds items past its edges. Modeled as a one-replacement split so
+ * the original keeps rendering until the pinned twin has a result.
+ */
+export declare const pin: (key: string, endCursor: string) => ((state: State) => State);
+/**
+ * Pin the growing last page at `continueCursor` and start a new growing
+ * page from there. Modeled as a split of the last page into its pinned
+ * replacement and the new page, so the swap waits for both.
+ */
+export declare const loadMore: (continueCursor: string, numItems: number, budget?: ReadBudget) => ((state: State) => State);
+/**
+ * Split the page at `key` in two at `splitCursor`. The first replacement
+ * pins at the split point; the second keeps the page's own `endCursor`—for a pinned page its original end (so a truncated `SplitRequired` page
+ * loses none of its range), and for a growing page no end at all (it keeps
+ * growing).
+ */
+export declare const split: (key: string, splitCursor: string) => ((state: State) => State);
+/** Swap a completed split's replacements in for the original page. */
+export declare const completeSplit: (key: string) => ((state: State) => State);
+/** Whether the last (rendered) page is currently being split or pinned. */
+export declare const isLastPageSplitting: (state: State) => boolean;
+/** Build one subscription request per subscribed page. */
+export declare const pageRequests: <A>(state: State, f: (page: PageRequest) => A) => Record.ReadonlyRecord<string, A>;
+/** The per-page results a render observes, keyed like {@link pageRequests}. */
+export type Results = Record.ReadonlyRecord<string, PageResult | Error | undefined>;
+/**
+ * The wire shape of one loaded page—`PaginationResult` from
+ * `convex/server`, so the protocol has a single source of truth.
+ */
+export type PageResult = PaginationResult<unknown>;
+/**
+ * What one render pass derives from the subscribed pages' results: the
+ * items to show, the trailing complete result (absent while the tail is
+ * loading or force-splitting), state transitions to apply, and whether a
+ * failure or an invalid cursor was hit.
+ */
+export type Interpretation = {
+    readonly _tag: "ResetRequired";
+} | {
+    readonly _tag: "Failed";
+    readonly error: unknown;
+    /** Encoded items loaded before the failing page. */
+    readonly items: ReadonlyArray<unknown>;
+} | {
+    readonly _tag: "Interpreted";
+    /** Encoded items across the loaded pages, in order. */
+    readonly items: ReadonlyArray<unknown>;
+    /** The last page's result, when every page has loaded completely. */
+    readonly lastResult: Option.Option<PageResult>;
+    /** Split/swap transitions this render discovered. */
+    readonly transitions: ReadonlyArray<(state: State) => State>;
+};
+/**
+ * Walk the pages in display order, concatenating their items and
+ * collecting the transitions to apply (completed split swaps, recommended
+ * splits, eager splits of pages that outgrew `initialNumItems`).
+ *
+ * `isInvalidCursorError` marks errors that call for a full pagination
+ * reset rather than a failure (the cursor no longer matches the query).
+ */
+export declare const interpret: (state: State, results: Record.ReadonlyRecord<string, PageResult | Error | undefined>, options: {
+    readonly initialNumItems: number;
+    readonly isInvalidCursorError: (error: Error) => boolean;
+}) => Interpretation;
+//# sourceMappingURL=StreamPagination.d.ts.map

package/dist/StreamPagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamPagination.d.ts","sourceRoot":"","sources":["../src/StreamPagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAkBD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;CAC9E;AAED,6CAA6C;AAC7C,eAAO,MAAM,KAAK,EAAE,KAKnB,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,OAAO,oBACD,MAAM,WACf,UAAU,KACjB,KAKD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,QACR,MAAM,aAAa,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAmBtD,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,QAAQ,mBAED,MAAM,YACZ,MAAM,WACR,UAAU,KACjB,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CA8CxB,CAAC;AAEN;;;;;GAKG;AACH,eAAO,MAAM,KAAK,QACV,MAAM,eAAe,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAqBxD,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,aAAa,QAClB,MAAM,KAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAYnC,CAAC;AAEP,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,UAAW,KAAK,KAAG,OAGhD,CAAC;AAEJ,0DAA0D;AAC1D,eAAO,MAAM,YAAY,GAAI,CAAC,SACrB,KAAK,KACT,CAAC,IAAI,EAAE,WAAW,KAAK,CAAC,KAC1B,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAA+B,CAAC;AAElE,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CACzC,MAAM,EACN,UAAU,GAAG,KAAK,GAAG,SAAS,CAC/B,CAAC;AAMF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACxC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC;CAC9D,CAAC;AAQN;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,UACb,KAAK,WACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAAC,WAC7D;IACP,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC1D,KACA,cAmEF,CAAC"}