@confect/core 10.0.0-next.2 → 10.0.0-next.20

package/CHANGELOG.md

@@ -1,5 +1,464 @@
 # @confect/core
 
+## 10.0.0-next.20
+
+## 10.0.0-next.19
+
+### Minor Changes
+
+- c1087eb: Add `@confect/foldkit` — client-side bindings for [Foldkit](https://foldkit.dev) apps. The package maps Confect's client surface onto Foldkit's integration seams: `Client.layer` provides the scoped WebSocket client and pagination-session allocator through an application's `resources`, `Subscription.reactiveQuery` builds a subscription entry that opens, re-opens, and closes a reactive query as `Option`-wrapped args derived from the Model change, and `Command.query` / `Command.mutation` / `Command.action` build Command definitions whose args are the ref's args and whose Messages are declared with the same `messages` field Foldkit's own `Command.define` takes. Every failure is folded into a Message via the required `onError` handler, so Command and Subscription error channels stay `never` as Foldkit requires.
+
+  ```ts
+  import * as Confect from "@confect/foldkit";
+  import * as Schema from "effect/Schema";
+  import * as Subscription from "foldkit/subscription";
+
+  const SaveNote = Confect.Command.mutation(
+    "SaveNote",
+    refs.public.notes.insert,
+    {
+      messages: [SucceededSaveNote, FailedSaveNote],
+      onSuccess: (noteId) => SucceededSaveNote({ noteId }),
+      onError: (error) => FailedSaveNote({ message: String(error) }),
+    },
+  );
+
+  const subscriptions = Subscription.make<
+    Model,
+    Message,
+    Confect.Client.Client
+  >()(() => ({
+    note: Confect.Subscription.reactiveQuery<Model>()(refs.public.notes.get, {
+      args: (model) => Option.map(model.noteId, (noteId) => ({ noteId })),
+      onSuccess: (note) => SucceededGetNote({ note }),
+      onError: (error) => FailedGetNote({ message: String(error) }),
+    }),
+  }));
+  ```
+
+  The Command factories accept Foldkit's `interrupt` option — `true` keys invocations by the Command name, `{ keyFields, toKey }` by a part derived from the ref's args — and the returned definition gains the `Interrupt` constructor for stopping in-flight invocations. Factory-built definitions instantiate Foldkit's own definition interfaces, so they are accepted wherever Foldkit accepts a Command definition — including Story/Scene `Command.resolve` and `expectExact` matchers. `Command.queryEffect`, `Command.mutationEffect`, and `Command.actionEffect` return execute bodies for hand-written `Command.define` calls (custom args schemas, multi-call Commands), and `Subscription.reactiveQueryStream` is the `dependenciesToStream` escape hatch for hand-written subscription entries.
+
+  `PaginatedQuery` navigates a paginated query one page at a time over Convex's cursor pagination. `PaginatedQuery.make(ref)` returns the Model and settlement schemas. Its states use Foldkit `AsyncData`'s vocabulary and semantics: `Idle`, `Loading`, `Refreshing`, `Success`, `Failure`, and `Stale`. Failed settlements preserve the complete error contract: declared function and middleware errors are wrapped as `FunctionError`, Convex's invalid-cursor pseudo-error is normalized to the new `@confect/core/PaginationError.InvalidCursor`, and `WebSocketClientError` and `SchemaError` are carried directly. `settle` accepts a request-bound `Result`, turns a failed refresh into `Stale`, automatically resets an invalid cursor, and ignores successes or failures from superseded requests. All machine operations (`init`, `reinitialize`, `reset`, `close`, `next`, `prev`, and `first`) remain pure.
+
+  `Subscription.paginatedQuery` keeps exactly one live, reactive page subscription in sync with the machine and emits one `onSettled` Message shape for either outcome. It allocates Convex's pagination `id` internally and returns it with the first settlement, so session allocation is not a separate Command or application Message. Installing that id is keep-alive-equivalent and does not restart the subscription. Query errors are emitted as values without closing the underlying Convex subscription, allowing a later successful result to recover naturally. Each request supports `maximumRowsRead` and `maximumBytesRead` and uses `initialNumItems` for the initial page and split heuristic. Page splits remain transparent, the last complete page stays visible during navigation and after refresh failure, and an empty terminal page automatically retreats to the preceding page.
+
+  ```ts
+  const Notes = Confect.PaginatedQuery.make(refs.public.notes.paginate);
+
+  // Model: notes: Notes.schema
+  // Initial Model value: notes: Notes.idle
+  // Message: settlement: Notes.settlement
+  // update after matching Idle: Notes.init(idle, { channel }, { initialNumItems: 20 })
+
+  const subscriptions = Subscription.make<
+    Model,
+    Message,
+    Confect.Client.Client
+  >()(() => ({
+    notesPage: Confect.Subscription.paginatedQuery<Model>()(Notes, {
+      state: (model) => model.notes,
+      onSettled: (settlement) => SettledGetNotesPage({ settlement }),
+    }),
+  }));
+  ```
+
+- b34e029: Declare Confect function arguments as optional lazy `Schema.Struct` field maps instead of constructed struct schemas. Confect now derives and builds the struct schema itself, defaults omitted args to `{}`, matches Convex's object-only argument model, and preserves exact field types through function specs and refs.
+
+## 10.0.0-next.18
+
+### Minor Changes
+
+- 91aebe4: Move `Table.make` to `@confect/core` so a spec that returns `notes.Doc` from `_generated/tables/notes` no longer ships `@confect/server` to the client.
+
+  ```ts confect/tables/notes.ts
+  import { Table } from "@confect/core";
+  import * as Schema from "effect/Schema";
+
+  export default Table.make(() =>
+    Schema.Struct({
+      text: Schema.String,
+    }),
+  );
+  ```
+
+  `confect codegen` now fails if any module a spec reaches value-imports `@confect/server`, including `confect/tables/` and `_generated/`. Type-only imports remain allowed.
+
+## 10.0.0-next.17
+
+### Minor Changes
+
+- 126548a: Add middleware: reusable logic that runs around a group's function handlers, provides Effect services to them, and fails with typed errors that reach clients.
+
+  Middleware lives in a reserved `confect/middleware/` directory, one `<Name>.spec.ts`/`<Name>.impl.ts` pair per middleware. Confect no longer scans that directory for function groups, so a group can no longer be defined at `confect/middleware/...`.
+
+  Declare a middleware's client-safe interface with `MiddlewareSpec.MiddlewareSpec` — its `provides` service (type-level), its `error` schema, and the function types it may cover (`functionTypes`, one required boolean flag per function type, so every spec states its coverage outright) — and attach it in a group spec with `GroupSpec.middleware`:
+
+  ```ts confect/middleware/RequireUser.spec.ts
+  import { MiddlewareSpec } from "@confect/core";
+
+  export class CurrentUser extends Context.Service<
+    CurrentUser,
+    {
+      readonly user: User;
+    }
+  >()("confect/middleware/RequireUser.spec/CurrentUser") {}
+
+  export class NotSignedIn extends Schema.TaggedError<NotSignedIn>()(
+    "NotSignedIn",
+    {},
+  ) {}
+
+  export default class RequireUser extends MiddlewareSpec.MiddlewareSpec<
+    RequireUser,
+    {
+      provides: CurrentUser;
+    }
+  >()("RequireUser", {
+    error: () => NotSignedIn,
+    functionTypes: { query: true, mutation: true, action: false },
+  }) {}
+  ```
+
+  ```ts confect/notes.spec.ts
+  import RequireUser from "./middleware/RequireUser.spec";
+
+  export default GroupSpec.make()
+    .middleware(RequireUser)
+    .addFunction(FunctionSpec.publicMutation({ ... }));
+  ```
+
+  Handlers of covered functions can then consume the provided service — a handler requiring `CurrentUser` type-checks exactly when a middleware providing it is attached to the group. Implement the middleware server-side with `MiddlewareImpl.make` (one strategy for all declared function types), `MiddlewareImpl.makeByFunctionType` (one per function type — the recommended shape for database-touching middleware that also covers actions), or the `MiddlewareImpl.provides` shorthand, and provide it to the group's impl layer like any function implementation:
+
+  ```ts confect/middleware/RequireUser.impl.ts
+  import { MiddlewareImpl } from "@confect/server";
+
+  export default MiddlewareImpl.provides(
+    databaseSchema,
+    RequireUser,
+    CurrentUser,
+    Effect.gen(function* () {
+      // load the user; `return yield* new NotSignedIn()` short-circuits
+      return { user };
+    }),
+  );
+  ```
+
+  ```ts confect/notes.impl.ts
+  import RequireUser from "./middleware/RequireUser.impl";
+
+  export default GroupImpl.make(databaseSchema, group).pipe(
+    Layer.provide(createNote),
+    Layer.provide(RequireUser), // omitting this is a compile error at `GroupImpl.finalize`
+    GroupImpl.finalize,
+  );
+  ```
+
+  Middleware runs per invocation, after args are decoded and before the handler, in attachment order; a middleware failure short-circuits the rest of the chain. Its errors join the covered functions' error unions end to end: `useQuery`/`useMutation` and the `@confect/js` clients surface them as typed errors with no client-side changes.
+
+  Middleware can also attach to a single function with `.middleware()` on the function spec — it runs inside the group-attached chain, immediately around the handler, and its errors join only that function's error union:
+
+  ```ts
+  FunctionSpec.publicMutation({ name: "deleteAll", ... }).middleware(RequireAdmin);
+  ```
+
+  A middleware can depend on one that runs earlier in the chain by declaring `requires` in its `Config` type parameter — its implementation may then consume the required service (e.g. `RequireAdmin` reading the `CurrentUser` that `RequireUser` provides). Satisfaction is type-checked at `GroupSpec.middleware` for group attachments and at `GroupImpl.make` for whole groups.
+
+  Attaching the same middleware twice (including once at group level and once at function level), attaching one whose `functionTypes` don't cover a covered function's type, attaching any middleware to a plain-Convex function, or attaching to a group containing a matching-type plain-Convex function are all type errors. Middleware does not propagate to subgroups. `confect codegen` fails with an explicit error when a group's spec attaches a middleware its impl never provides.
+
+  Because every `*.spec.ts` is reachable from `_generated/refs.ts`, which clients import, a spec's whole import graph is bundled into the browser — so an implementation co-located with its declaration ships server logic (table names, index names, authorization checks) to users. `confect codegen` now fails when any module a spec reaches value-imports `@confect/server`, outside the `tables/` and `_generated/` directories that legitimately need it. Type-only imports are erased before bundling and remain allowed.
+
+### Patch Changes
+
+- 8e4962e: Raise the required `effect` peer version to `^4.0.0-rc.111` (from `^4.0.0-rc.110`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
+
+  No Confect API changed, and no call-site edits are needed. `rc.111` is a patch release of Effect with nothing removed or renamed, so upgrading is a matter of installing it alongside `@confect/*`.
+
+## 10.0.0-next.16
+
+### Major Changes
+
+- Migrate to Effect v4. All `@confect/*` packages now require `effect@^4.0.0-beta.97`; `@effect/platform` and `@effect/cli` are no longer dependencies (their functionality moved into `effect` core and `effect/unstable/*`).
+
+  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.
+  - **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.
+  - **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.
+
+### Patch Changes
+
+- Raise the required `effect` peer version to `^4.0.0-beta.100` (from `^4.0.0-beta.99`).
+
+  This is a peer-range-only change with no consumer-visible API consequences. The `beta.100` release only touches `Cron` internals (month/weekday alias normalization, day/weekday rollover, and equality/hashing), CLI error message formatting (`InvalidValue` prefixes), and `Schema.toTaggedUnion` discriminants that Confect doesn't use.
+
+- Raise the required `effect` peer version to `^4.0.0-beta.101` (from `^4.0.0-beta.100`).
+
+  This is a peer-range-only change with no consumer-visible API consequences. The `beta.101` release only touches fiber/concurrency internals (interrupt handling in concurrent traversal, stack frame annotations, `awaitAllChildren` linearization, `interruptibleMask` interrupt delivery), a `MutableList.filter` fix for empty buckets, a `Schema.Struct` required-readonly-field type display simplification, and an `HttpRouter.toWebHandler` middleware type-inference tightening that Confect doesn't need to accommodate.
+
+- 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` 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:
+
+  **Before:**
+
+  ```ts
+  export class NoteNotFound extends Schema.TaggedErrorClass<NoteNotFound>()(
+    "NoteNotFound",
+    { noteId: Id("notes") },
+  ) {}
+  ```
+
+  **After:**
+
+  ```ts
+  export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
+    "NoteNotFound",
+    { noteId: Id("notes") },
+  ) {}
+  ```
+
+  `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.
+
+- Raise the required `effect` peer version to `^4.0.0-beta.106` (from `^4.0.0-beta.105`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
+
+  `beta.106` is a patch-only Effect release. Nothing in Confect's own API changes, and your table, argument, and returns schemas still compile to the same Convex validators.
+
+  One Effect change needs a call-site edit if you derive property-test generators from those schemas: `Schema.toArbitrary` now returns a factory that takes the `fast-check` module instead of returning an arbitrary directly, and `Schema.toArbitraryLazy` and the `{ report: true }` option are gone.
+
+  **Before:**
+
+  ```ts
+  const NoteArbitrary = Schema.toArbitrary(Note);
+  ```
+
+  **After:**
+
+  ```ts
+  import * as FastCheck from "fast-check";
+
+  const NoteArbitrary = Schema.toArbitrary(Note)(FastCheck);
+  ```
+
+  HTTP actions written against `HttpRouter` also inherit Effect's stricter multipart handling: a request that exceeds the configured part count, part size, or field size limits now stops being parsed at the limit rather than being read to completion first.
+
+- 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.
+
+  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.
+
+- Raise the required `effect` peer version to `^4.0.0-beta.99` (from `^4.0.0-beta.98`).
+
+  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.
+
+- Raise the required `effect` peer version to `^4.0.0-rc.108` (from `^4.0.0-beta.107`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise. Effect v4 has left beta for release candidates, so `effect@rc` is now the tag to install alongside `@confect/*`.
+
+  No Confect API changed, and no call-site edits are needed for Confect itself. One Effect change can reach your code: the standalone `effect/SchemaError` module is gone, and `SchemaError` is now exported from `Schema`. Confect still fails decoding with the same error, so this only matters if you name the type when handling it.
+
+  Before:
+
+  ```ts
+  import type { SchemaError } from "effect/SchemaError";
+  ```
+
+  After:
+
+  ```ts
+  import type { SchemaError } from "effect/Schema";
+  ```
+
+  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.
+
+- 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.
+
+  No Confect API changed, and no call-site edits are needed. `rc.109` is a patch release of Effect with nothing removed or renamed, so upgrading is a matter of installing it alongside `@confect/*`.
+
+- 8e4962e: Raise the required `effect` peer version to `^4.0.0-rc.110` (from `^4.0.0-rc.109`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
+
+  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.
+- The schemas Confect uses for values Convex itself produces now reject `NaN` and `±Infinity`: `_creationTime`, a scheduled function's `scheduledTime` and `completedTime`, a stored file's `size`, and the fields of `PaginationOptions`. Convex cannot return a non-finite value for any of them, so this rules out states that were never reachable.
+
+  The Convex validators these compile to are unchanged — each is still `v.float64()` — so nothing changes about what your deployment accepts. Only Confect's decoding is narrower. Your own table schemas are untouched: `Schema.Number` still accepts non-finite values wherever you use it, which matters because Convex stores them.
+
+- 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.
+
+- 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.
+
+## 10.0.0-next.15
+
+### Patch Changes
+
+- 8e4962e: 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.
+
+  No Confect API changed, and no call-site edits are needed. `rc.109` is a patch release of Effect with nothing removed or renamed, so upgrading is a matter of installing it alongside `@confect/*`.
+
+## 10.0.0-next.14
+
+### Patch Changes
+
+- 9d51bd3: Raise the required `effect` peer version to `^4.0.0-rc.108` (from `^4.0.0-beta.107`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise. Effect v4 has left beta for release candidates, so `effect@rc` is now the tag to install alongside `@confect/*`.
+
+  No Confect API changed, and no call-site edits are needed for Confect itself. One Effect change can reach your code: the standalone `effect/SchemaError` module is gone, and `SchemaError` is now exported from `Schema`. Confect still fails decoding with the same error, so this only matters if you name the type when handling it.
+
+  Before:
+
+  ```ts
+  import type { SchemaError } from "effect/SchemaError";
+  ```
+
+  After:
+
+  ```ts
+  import type { SchemaError } from "effect/Schema";
+  ```
+
+  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.
+
+- aede323: The schemas Confect uses for values Convex itself produces now reject `NaN` and `±Infinity`: `_creationTime`, a scheduled function's `scheduledTime` and `completedTime`, a stored file's `size`, and the fields of `PaginationOptions`. Convex cannot return a non-finite value for any of them, so this rules out states that were never reachable.
+
+  The Convex validators these compile to are unchanged — each is still `v.float64()` — so nothing changes about what your deployment accepts. Only Confect's decoding is narrower. Your own table schemas are untouched: `Schema.Number` still accepts non-finite values wherever you use it, which matters because Convex stores them.
+
+- 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.
+
+## 10.0.0-next.13
+
+### Patch Changes
+
+- 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.
+
+  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
+
+### Patch Changes
+
+- 661ee9b: Raise the required `effect` peer version to `^4.0.0-beta.106` (from `^4.0.0-beta.105`), and `@confect/server`'s optional `@effect/platform-node` peer version likewise.
+
+  `beta.106` is a patch-only Effect release. Nothing in Confect's own API changes, and your table, argument, and returns schemas still compile to the same Convex validators.
+
+  One Effect change needs a call-site edit if you derive property-test generators from those schemas: `Schema.toArbitrary` now returns a factory that takes the `fast-check` module instead of returning an arbitrary directly, and `Schema.toArbitraryLazy` and the `{ report: true }` option are gone.
+
+  **Before:**
+
+  ```ts
+  const NoteArbitrary = Schema.toArbitrary(Note);
+  ```
+
+  **After:**
+
+  ```ts
+  import * as FastCheck from "fast-check";
+
+  const NoteArbitrary = Schema.toArbitrary(Note)(FastCheck);
+  ```
+
+  HTTP actions written against `HttpRouter` also inherit Effect's stricter multipart handling: a request that exceeds the configured part count, part size, or field size limits now stops being parsed at the limit rather than being read to completion first.
+
+## 10.0.0-next.11
+
+### Patch Changes
+
+- 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` 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:
+
+  **Before:**
+
+  ```ts
+  export class NoteNotFound extends Schema.TaggedErrorClass<NoteNotFound>()(
+    "NoteNotFound",
+    { noteId: Id("notes") },
+  ) {}
+  ```
+
+  **After:**
+
+  ```ts
+  export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
+    "NoteNotFound",
+    { noteId: Id("notes") },
+  ) {}
+  ```
+
+  `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.
+
+  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.
+
+## 10.0.0-next.10
+
+### Patch Changes
+
+- 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.
+
+## 10.0.0-next.8
+
+### Patch Changes
+
+- 913d0e5: Raise the required `effect` peer version to `^4.0.0-beta.101` (from `^4.0.0-beta.100`).
+
+  This is a peer-range-only change with no consumer-visible API consequences. The `beta.101` release only touches fiber/concurrency internals (interrupt handling in concurrent traversal, stack frame annotations, `awaitAllChildren` linearization, `interruptibleMask` interrupt delivery), a `MutableList.filter` fix for empty buckets, a `Schema.Struct` required-readonly-field type display simplification, and an `HttpRouter.toWebHandler` middleware type-inference tightening that Confect doesn't need to accommodate.
+
+## 10.0.0-next.7
+
+## 10.0.0-next.6
+
+## 10.0.0-next.5
+
+## 10.0.0-next.4
+
+## 10.0.0-next.3
+
+### Patch Changes
+
+- 5b63546: Raise the required `effect` peer version to `^4.0.0-beta.100` (from `^4.0.0-beta.99`).
+
+  This is a peer-range-only change with no consumer-visible API consequences. The `beta.100` release only touches `Cron` internals (month/weekday alias normalization, day/weekday rollover, and equality/hashing), CLI error message formatting (`InvalidValue` prefixes), and `Schema.toTaggedUnion` discriminants that Confect doesn't use.
+
 ## 10.0.0-next.2
 
 ### Patch Changes
@@ -35,6 +494,65 @@
   - **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.
 
+## 9.4.1
+
+### Patch Changes
+
+- 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.
+
+## 9.4.0
+
+## 9.3.0
+
+### Minor Changes
+
+- 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`.
+
+  ```ts
+  // confect/notes.spec.ts
+  FunctionSpec.publicPaginatedQuery({
+    name: "listByAuthor",
+    args: () => Schema.Struct({ author: Schema.String }),
+    item: () => notes.Doc,
+  });
+
+  // confect/notes.impl.ts
+  ({ author, paginationOpts }) =>
+    Effect.gen(function* () {
+      const reader = yield* DatabaseReader;
+
+      return yield* reader
+        .table("notes")
+        .index("by_creation_time", "desc")
+        .paginate(paginationOpts, (q) => q.eq(q.field("author"), author));
+    }).pipe(Effect.orDie);
+  ```
+
+  Declaring `paginationOpts` in `args` yourself is a type and runtime error.
+
+  ```tsx
+  import { PaginatedQueryResult, usePaginatedQuery } from "@confect/react";
+
+  const notes = usePaginatedQuery(
+    refs.public.notes.listByAuthor,
+    { author },
+    { initialNumItems: 10 },
+  );
+
+  // `notes.results` holds the pages decoded through `item`.
+  if (PaginatedQueryResult.isCanLoadMore(notes)) {
+    notes.loadMore(10);
+  }
+  ```
+
+  The hook returns a `PaginatedQueryResult<Item, E>`. `LoadingFirstPage`, `LoadingMore`, `CanLoadMore`, and `Exhausted` all carry `results` and `isLoading`; `loadMore` lives only on `CanLoadMore`, the one state it can make progress from. A declared `error` schema surfaces as a `Failure` variant carrying the decoded error instead of throwing during render, and `Failure` carries `results` too, so the pages loaded before it can still be rendered. Without an `error` schema, `Failure` is absent from the type entirely.
+
+  `paginate` in `@confect/server` now accepts Convex's full `PaginationOptions`, so a handler's `paginationOpts` passes straight through. `@confect/react` now requires `convex` >= 1.36.0.
+
+## 9.2.5
+
 ## 9.2.4
 
 ## 9.2.3

package/README.md

@@ -5,7 +5,9 @@ Confect is a framework that deeply integrates Effect with Convex. It's more than
 - Define your Convex database schema using Effect schemas.
 - Write Convex function args and returns validators using Effect's schema library.
 - Use Confect functions to automatically decode and encode your data according to your Effect schema definitions for end-to-end rich types, from client to function to database (and back).
-- Use Effect's HTTP API modules to define your HTTP API(s). Includes interactive OpenAPI documentation powered by [Scalar](https://github.com/scalar/scalar).
+- Add reusable, type-safe middleware to function groups or individual functions to provide Effect services and run logic around handlers.
+- Declare typed errors on functions and middleware using Effect schemas, then handle the decoded errors at every call site.
+- Use Effect's native HTTP API modules to define your HTTP API.
 - Access Convex platform capabilities via Effect services.
 
 Want to learn more? Read the [docs](https://confect.dev)!