@confect/foldkit 10.0.0-next.22 → 10.0.0-next.23

package/dist/Subscription.js.map

@@ -1 +1 @@
-{"version":3,"file":"Subscription.js","names":["Client.WebSocketClientError","PaginatedQuery.FunctionError","PaginatedQuery.getSubscriptionRequest","Client.Client","PaginatedQuery.allocateRequest"],"sources":["../src/Subscription.ts"],"sourcesContent":["import * as PaginationError from \"@confect/core/PaginationError\";\nimport type * as Ref from \"@confect/core/Ref\";\nimport * as Effect from \"effect/Effect\";\nimport type * as Equivalence from \"effect/Equivalence\";\nimport * as Match from \"effect/Match\";\nimport * as Option from \"effect/Option\";\nimport * as Result from \"effect/Result\";\nimport * as Schema from \"effect/Schema\";\nimport * as Stream from \"effect/Stream\";\nimport type * as FoldkitSubscription from \"foldkit/subscription\";\nimport * as PaginatedQuery from \"./PaginatedQuery\";\nimport * as Client from \"./Client\";\n\n/**\n * Everything a reactive query subscription against `Query` can fail with: the\n * ref's typed error (if it declares an `error` schema), a transport-level\n * `WebSocketClientError`, or a `SchemaError` from encoding args or decoding\n * returns.\n */\nexport type Error<Query extends Ref.AnyConfectPublicQuery> =\n  | Ref.Error<Query>\n  | Client.WebSocketClientError\n  | Schema.SchemaError;\n\nconst paginatedError = <Query extends Ref.AnyConfectPublicPaginatedQuery>(\n  error: Error<Query>,\n): PaginatedQuery.Error<Query> =>\n  Match.value(error).pipe(\n    Match.when(Schema.isSchemaError, (schemaError) => schemaError),\n    Match.when(Match.instanceOf(Client.WebSocketClientError), (clientError) =>\n      PaginationError.fromConvexQueryError(clientError.cause).pipe(\n        Option.getOrElse(() => clientError),\n      ),\n    ),\n    Match.when(Match.any, (functionError) =>\n      PaginationError.fromConvexErrorData(functionError).pipe(\n        Option.getOrElse(() =>\n          PaginatedQuery.FunctionError({ error: functionError }),\n        ),\n      ),\n    ),\n    Match.exhaustive,\n  ) as PaginatedQuery.Error<Query>;\n\n/**\n * The dependency record of a `reactiveQuery` entry. `None` means the\n * subscription is closed; a change from one `Some` to another tears the\n * server subscription down and reopens it with the new args.\n */\nexport interface Dependencies<Query extends Ref.AnyConfectPublicQuery> {\n  readonly args: Option.Option<Ref.Args<Query>>;\n}\n\n/**\n * Maps a reactive query's emissions into the app's Messages. Every failure—the ref's typed error, a transport error, or a codec error—arrives via\n * `onError`, so the resulting stream's error channel is `never`, as Foldkit\n * requires.\n */\nexport interface Handlers<\n  Query extends Ref.AnyConfectPublicQuery,\n  SuccessMessage,\n  ErrorMessage,\n> {\n  readonly onSuccess: (returns: Ref.Returns<Query>) => SuccessMessage;\n  readonly onError: (error: Error<Query>) => ErrorMessage;\n}\n\n/**\n * The `args` extractor is required whenever the query declares args; queries\n * without args may omit it, in which case the subscription is always open.\n */\ntype ArgsConfig<Query extends Ref.AnyConfectPublicQuery, Model> = {\n  readonly args?: (model: Model) => Option.Option<Ref.Args<Query>>;\n} & (keyof Ref.Args<Query> extends never\n  ? unknown\n  : {\n      readonly args: (model: Model) => Option.Option<Ref.Args<Query>>;\n    });\n\n/**\n * A `dependenciesToStream` body for a hand-written subscription entry: runs\n * the ref as a reactive query against the `Client` resource and maps\n * every emission and every failure into a Message. Query failures are values,\n * so the subscription remains live and can later emit a successful result.\n *\n * Prefer `reactiveQuery`, which builds the whole entry; reach for this when\n * you need control over the entry's dependencies (custom gating, extra\n * dependencies).\n */\nexport const reactiveQueryStream =\n  <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(\n    ref: Query,\n    handlers: Handlers<Query, SuccessMessage, ErrorMessage>,\n  ) =>\n  (\n    ...args: Ref.OptionalArgs<Query>\n  ): Stream.Stream<SuccessMessage | ErrorMessage, never, Client.Client> =>\n    Client.Client.pipe(\n      Effect.map((client) => client.reactiveQueryResult(ref, ...args)),\n      Stream.unwrap,\n      Stream.map(\n        Result.match({\n          onSuccess: handlers.onSuccess,\n          onFailure: handlers.onError,\n        }),\n      ),\n    );\n\n/**\n * A complete Foldkit subscription entry for a Confect reactive query. The\n * leading thunk fixes the `Model` type (TypeScript cannot partially infer\n * type arguments), so the `args` extractor's parameter is already typed.\n * Pass the result as an entry value to `Subscription.make`:\n *\n * ```ts\n * import * as Confect from \"@confect/foldkit\"\n * import * as Subscription from \"foldkit/subscription\"\n *\n * const subscriptions = Subscription.make<\n *   Model,\n *   Message,\n *   Confect.Client.Client\n * >()(() => ({\n *   note: Confect.Subscription.reactiveQuery<Model>()(refs.public.notes.get, {\n *     args: (model) => Option.map(model.noteId, (noteId) => ({ noteId })),\n *     onSuccess: (note) => SucceededGetNote({ note }),\n *     onError: (error) => FailedGetNote({ message: String(error) }),\n *   }),\n * }))\n * ```\n *\n * The entry's dependencies are the query args wrapped in `Option`: `None`\n * closes the subscription, a change from one `Some` to another unsubscribes\n * and resubscribes with the new args, and structurally equal args leave the\n * subscription running (equivalence is derived from the ref's args schema).\n * Queries without args may omit `args`, leaving the subscription always open.\n */\nexport const reactiveQuery =\n  <Model>() =>\n  <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(\n    ref: Query,\n    config: Handlers<Query, SuccessMessage, ErrorMessage> &\n      ArgsConfig<Query, Model>,\n  ): FoldkitSubscription.EntryWithoutKeepAlive<\n    Model,\n    SuccessMessage | ErrorMessage,\n    Dependencies<Query>,\n    Client.Client\n  > => {\n    const modelToArgs = config.args;\n\n    return {\n      dependenciesSchema: Schema.Struct({\n        args: Schema.Option(ref.args),\n      }),\n      modelToDependencies: (model) => ({\n        args:\n          modelToArgs === undefined\n            ? Option.some({} as Ref.Args<Query>)\n            : modelToArgs(model),\n      }),\n      dependenciesToStream: ({ args }) =>\n        Option.match(args, {\n          onNone: () => Stream.empty,\n          onSome: (someArgs) => reactiveQueryStream(ref, config)(someArgs),\n        }),\n    };\n  };\n\n/**\n * A complete Foldkit subscription entry that keeps exactly one live reactive\n * page subscription in sync with a `PaginatedQuery` machine in the Model.\n * The machine state is the single source of truth: navigation and\n * split-pinning change the derived args, while `Idle` closes the subscription.\n * Pagination ids are allocated here and installed by the first settlement.\n *\n * The leading thunk fixes the `Model` type (TypeScript cannot partially\n * infer type arguments), so the `state` extractor's parameter is already\n * typed:\n *\n * ```ts\n * import * as Confect from \"@confect/foldkit\"\n * import * as Subscription from \"foldkit/subscription\"\n *\n * const subscriptions = Subscription.make<\n *   Model,\n *   Message,\n *   Confect.Client.Client\n * >()(() => ({\n *   notesPage: Confect.Subscription.paginatedQuery<Model>()(Notes, {\n *     state: (model) => model.notes,\n *     onSettled: (settlement) => SettledGetNotesPage({ settlement }),\n *   }),\n * }))\n * ```\n *\n * Pass the settlement to `PaginatedQuery.settle` in `update`. The request\n * identity is included in both success and failure Messages, so superseded\n * outcomes cannot settle a newer page or pagination session. Query failures\n * do not close the Convex subscription; a later result can recover naturally.\n */\ntype DependenciesSchema<Dependencies_> = Schema.Schema<Dependencies_> & {\n  readonly fields: Schema.Struct.Fields;\n};\n\ntype EntryWithKeepAlive<Model, Message, Dependencies_, Services> = {\n  readonly dependenciesSchema: DependenciesSchema<Dependencies_>;\n  readonly modelToDependencies: (model: Model) => Dependencies_;\n  readonly keepAliveEquivalence: Equivalence.Equivalence<Dependencies_>;\n  readonly dependenciesToStream: (\n    dependencies: Dependencies_,\n    readDependencies: () => Dependencies_,\n  ) => Stream.Stream<Message, never, Services>;\n};\n\nexport const paginatedQuery =\n  <Model>() =>\n  <\n    PaginatedQueryRef extends Ref.AnyConfectPublicPaginatedQuery,\n    SettledMessage,\n  >(\n    machine: PaginatedQuery.PaginatedQuery<PaginatedQueryRef>,\n    config: {\n      readonly state: (\n        model: Model,\n      ) => PaginatedQuery.State<\n        PaginatedQuery.Item<PaginatedQueryRef>,\n        PaginatedQuery.UserArgs<PaginatedQueryRef>,\n        PaginatedQuery.Error<PaginatedQueryRef>\n      >;\n      readonly onSettled: (\n        settlement: PaginatedQuery.Settlement<\n          PaginatedQuery.Item<PaginatedQueryRef>,\n          PaginatedQuery.UserArgs<PaginatedQueryRef>,\n          PaginatedQuery.Error<PaginatedQueryRef>\n        >,\n      ) => SettledMessage;\n    },\n  ): EntryWithKeepAlive<\n    Model,\n    SettledMessage,\n    {\n      readonly request: Option.Option<\n        PaginatedQuery.SubscriptionRequest<\n          PaginatedQuery.UserArgs<PaginatedQueryRef>\n        >\n      >;\n    },\n    Client.Client\n  > => {\n    const ref = machine.ref;\n    const composedArgsSchema = ref.args;\n    const requestEquivalence = Schema.toEquivalence(\n      machine.subscriptionRequestSchema,\n    );\n    const optionalRequestEquivalence = Option.makeEquivalence<\n      PaginatedQuery.SubscriptionRequest<\n        PaginatedQuery.UserArgs<PaginatedQueryRef>\n      >\n    >((left, right) =>\n      requestEquivalence(\n        { ...left, paginationId: Option.none() },\n        { ...right, paginationId: Option.none() },\n      ),\n    );\n\n    return {\n      dependenciesSchema: Schema.Struct({\n        request: Schema.Option(machine.subscriptionRequestSchema),\n      }),\n      modelToDependencies: (model) => ({\n        request: Match.value(config.state(model)).pipe(\n          Match.tag(\"Idle\", () => Option.none()),\n          Match.tag(\"Active\", (state) =>\n            Option.some(PaginatedQuery.getSubscriptionRequest(state)),\n          ),\n          Match.exhaustive,\n        ),\n      }),\n      keepAliveEquivalence: (left, right) =>\n        optionalRequestEquivalence(left.request, right.request),\n      dependenciesToStream: ({\n        request,\n      }): Stream.Stream<SettledMessage, never, Client.Client> =>\n        Option.match(request, {\n          onNone: () => Stream.empty,\n          onSome: (subscriptionRequest) =>\n            Stream.unwrap(\n              Effect.gen(function* () {\n                const client = yield* Client.Client;\n                const paginationId = yield* client.resolvePaginationId(\n                  subscriptionRequest.paginationId,\n                );\n                const allocatedRequest = PaginatedQuery.allocateRequest(\n                  subscriptionRequest,\n                  paginationId,\n                );\n                const { descriptor, options } = allocatedRequest;\n                const composedArgs = composedArgsSchema.make({\n                  ...allocatedRequest.args,\n                  paginationOpts: {\n                    numItems: options.initialNumItems,\n                    cursor: descriptor.cursor,\n                    id: paginationId,\n                    ...Match.value(options.maximumRowsRead).pipe(\n                      Match.when(undefined, () => ({})),\n                      Match.when(Match.defined, (maximumRowsRead) => ({\n                        maximumRowsRead,\n                      })),\n                      Match.exhaustive,\n                    ),\n                    ...Match.value(options.maximumBytesRead).pipe(\n                      Match.when(undefined, () => ({})),\n                      Match.when(Match.defined, (maximumBytesRead) => ({\n                        maximumBytesRead,\n                      })),\n                      Match.exhaustive,\n                    ),\n                    ...Option.match(descriptor.endCursor, {\n                      onNone: () => ({}),\n                      onSome: (endCursor) => ({ endCursor }),\n                    }),\n                  },\n                });\n                return client.reactiveQueryResult(ref, composedArgs).pipe(\n                  Stream.map((result) =>\n                    config.onSettled({\n                      request: allocatedRequest,\n                      result: Result.mapError(result, paginatedError),\n                    }),\n                  ),\n                );\n              }),\n            ),\n        }),\n    };\n  };\n"],"mappings":"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"}
+{"version":3,"file":"Subscription.js","names":["Client.WebSocketClientError","PaginatedQuery.FunctionError","PaginatedQuery.getSubscriptionRequest","Client.Client","PaginatedQuery.allocateRequest"],"sources":["../src/Subscription.ts"],"sourcesContent":["import * as PaginationError from \"@confect/core/PaginationError\";\nimport type * as Ref from \"@confect/core/Ref\";\nimport * as Effect from \"effect/Effect\";\nimport type * as Equivalence from \"effect/Equivalence\";\nimport * as Match from \"effect/Match\";\nimport * as Option from \"effect/Option\";\nimport * as Result from \"effect/Result\";\nimport * as Schema from \"effect/Schema\";\nimport * as Stream from \"effect/Stream\";\nimport type * as FoldkitSubscription from \"foldkit/subscription\";\nimport * as PaginatedQuery from \"./PaginatedQuery\";\nimport * as Client from \"./Client\";\n\n/**\n * Everything a reactive query subscription against `Query` can fail with: the\n * ref's typed error (if it declares an `error` schema), a transport-level\n * `WebSocketClientError`, or a `SchemaError` from encoding args or decoding\n * returns.\n */\nexport type Error<Query extends Ref.AnyConfectPublicQuery> =\n  | Ref.Error<Query>\n  | Client.WebSocketClientError\n  | Schema.SchemaError;\n\nconst paginatedError = <Query extends Ref.AnyConfectPublicPaginatedQuery>(\n  error: Error<Query>,\n): PaginatedQuery.Error<Query> =>\n  Match.value(error).pipe(\n    Match.when(Schema.isSchemaError, (schemaError) => schemaError),\n    Match.when(Match.instanceOf(Client.WebSocketClientError), (clientError) =>\n      PaginationError.fromConvexQueryError(clientError.cause).pipe(\n        Option.getOrElse(() => clientError),\n      ),\n    ),\n    Match.when(Match.any, (functionError) =>\n      PaginationError.fromConvexErrorData(functionError).pipe(\n        Option.getOrElse(() =>\n          PaginatedQuery.FunctionError({ error: functionError }),\n        ),\n      ),\n    ),\n    Match.exhaustive,\n  ) as PaginatedQuery.Error<Query>;\n\n/**\n * The dependency record of a `reactiveQuery` entry. `None` means the\n * subscription is closed; a change from one `Some` to another tears the server\n * subscription down and reopens it with the new args.\n */\nexport interface Dependencies<Query extends Ref.AnyConfectPublicQuery> {\n  readonly args: Option.Option<Ref.Args<Query>>;\n}\n\n/**\n * Maps a reactive query's emissions into the app's Messages. Every failure—the\n * ref's typed error, a transport error, or a codec error—arrives via `onError`,\n * so the resulting stream's error channel is `never`, as Foldkit requires.\n */\nexport interface Handlers<\n  Query extends Ref.AnyConfectPublicQuery,\n  SuccessMessage,\n  ErrorMessage,\n> {\n  readonly onSuccess: (returns: Ref.Returns<Query>) => SuccessMessage;\n  readonly onError: (error: Error<Query>) => ErrorMessage;\n}\n\n/**\n * The `args` extractor is required whenever the query declares args; queries\n * without args may omit it, in which case the subscription is always open.\n */\ntype ArgsConfig<Query extends Ref.AnyConfectPublicQuery, Model> = {\n  readonly args?: (model: Model) => Option.Option<Ref.Args<Query>>;\n} & (keyof Ref.Args<Query> extends never\n  ? unknown\n  : {\n      readonly args: (model: Model) => Option.Option<Ref.Args<Query>>;\n    });\n\n/**\n * A `dependenciesToStream` body for a hand-written subscription entry: runs the\n * ref as a reactive query against the `Client` resource and maps every emission\n * and every failure into a Message. Query failures are values, so the\n * subscription remains live and can later emit a successful result.\n *\n * Prefer `reactiveQuery`, which builds the whole entry; reach for this when you\n * need control over the entry's dependencies (custom gating, extra\n * dependencies).\n */\nexport const reactiveQueryStream =\n  <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(\n    ref: Query,\n    handlers: Handlers<Query, SuccessMessage, ErrorMessage>,\n  ) =>\n  (\n    ...args: Ref.OptionalArgs<Query>\n  ): Stream.Stream<SuccessMessage | ErrorMessage, never, Client.Client> =>\n    Client.Client.pipe(\n      Effect.map((client) => client.reactiveQueryResult(ref, ...args)),\n      Stream.unwrap,\n      Stream.map(\n        Result.match({\n          onSuccess: handlers.onSuccess,\n          onFailure: handlers.onError,\n        }),\n      ),\n    );\n\n/**\n * A complete Foldkit subscription entry for a Confect reactive query. The\n * leading thunk fixes the `Model` type (TypeScript cannot partially infer type\n * arguments), so the `args` extractor's parameter is already typed. Pass the\n * result as an entry value to `Subscription.make`:\n *\n * ```ts\n * import * as Confect from \"@confect/foldkit\";\n * import * as Subscription from \"foldkit/subscription\";\n *\n * const subscriptions = Subscription.make<\n *   Model,\n *   Message,\n *   Confect.Client.Client\n * >()(() => ({\n *   note: Confect.Subscription.reactiveQuery<Model>()(\n *     refs.public.notes.get,\n *     {\n *       args: (model) =>\n *         Option.map(model.noteId, (noteId) => ({ noteId })),\n *       onSuccess: (note) => SucceededGetNote({ note }),\n *       onError: (error) => FailedGetNote({ message: String(error) }),\n *     },\n *   ),\n * }));\n * ```\n *\n * The entry's dependencies are the query args wrapped in `Option`: `None`\n * closes the subscription, a change from one `Some` to another unsubscribes and\n * resubscribes with the new args, and structurally equal args leave the\n * subscription running (equivalence is derived from the ref's args schema).\n * Queries without args may omit `args`, leaving the subscription always open.\n */\nexport const reactiveQuery =\n  <Model>() =>\n  <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(\n    ref: Query,\n    config: Handlers<Query, SuccessMessage, ErrorMessage> &\n      ArgsConfig<Query, Model>,\n  ): FoldkitSubscription.EntryWithoutKeepAlive<\n    Model,\n    SuccessMessage | ErrorMessage,\n    Dependencies<Query>,\n    Client.Client\n  > => {\n    const modelToArgs = config.args;\n\n    return {\n      dependenciesSchema: Schema.Struct({\n        args: Schema.Option(ref.args),\n      }),\n      modelToDependencies: (model) => ({\n        args:\n          modelToArgs === undefined\n            ? Option.some({} as Ref.Args<Query>)\n            : modelToArgs(model),\n      }),\n      dependenciesToStream: ({ args }) =>\n        Option.match(args, {\n          onNone: () => Stream.empty,\n          onSome: (someArgs) => reactiveQueryStream(ref, config)(someArgs),\n        }),\n    };\n  };\n\n/**\n * A complete Foldkit subscription entry that keeps exactly one live reactive\n * page subscription in sync with a `PaginatedQuery` machine in the Model. The\n * machine state is the single source of truth: navigation and split-pinning\n * change the derived args, while `Idle` closes the subscription. Pagination ids\n * are allocated here and installed by the first settlement.\n *\n * The leading thunk fixes the `Model` type (TypeScript cannot partially infer\n * type arguments), so the `state` extractor's parameter is already typed:\n *\n * ```ts\n * import * as Confect from \"@confect/foldkit\";\n * import * as Subscription from \"foldkit/subscription\";\n *\n * const subscriptions = Subscription.make<\n *   Model,\n *   Message,\n *   Confect.Client.Client\n * >()(() => ({\n *   notesPage: Confect.Subscription.paginatedQuery<Model>()(Notes, {\n *     state: (model) => model.notes,\n *     onSettled: (settlement) => SettledGetNotesPage({ settlement }),\n *   }),\n * }));\n * ```\n *\n * Pass the settlement to `PaginatedQuery.settle` in `update`. The request\n * identity is included in both success and failure Messages, so superseded\n * outcomes cannot settle a newer page or pagination session. Query failures do\n * not close the Convex subscription; a later result can recover naturally.\n */\ntype DependenciesSchema<Dependencies_> = Schema.Schema<Dependencies_> & {\n  readonly fields: Schema.Struct.Fields;\n};\n\ntype EntryWithKeepAlive<Model, Message, Dependencies_, Services> = {\n  readonly dependenciesSchema: DependenciesSchema<Dependencies_>;\n  readonly modelToDependencies: (model: Model) => Dependencies_;\n  readonly keepAliveEquivalence: Equivalence.Equivalence<Dependencies_>;\n  readonly dependenciesToStream: (\n    dependencies: Dependencies_,\n    readDependencies: () => Dependencies_,\n  ) => Stream.Stream<Message, never, Services>;\n};\n\nexport const paginatedQuery =\n  <Model>() =>\n  <\n    PaginatedQueryRef extends Ref.AnyConfectPublicPaginatedQuery,\n    SettledMessage,\n  >(\n    machine: PaginatedQuery.PaginatedQuery<PaginatedQueryRef>,\n    config: {\n      readonly state: (\n        model: Model,\n      ) => PaginatedQuery.State<\n        PaginatedQuery.Item<PaginatedQueryRef>,\n        PaginatedQuery.UserArgs<PaginatedQueryRef>,\n        PaginatedQuery.Error<PaginatedQueryRef>\n      >;\n      readonly onSettled: (\n        settlement: PaginatedQuery.Settlement<\n          PaginatedQuery.Item<PaginatedQueryRef>,\n          PaginatedQuery.UserArgs<PaginatedQueryRef>,\n          PaginatedQuery.Error<PaginatedQueryRef>\n        >,\n      ) => SettledMessage;\n    },\n  ): EntryWithKeepAlive<\n    Model,\n    SettledMessage,\n    {\n      readonly request: Option.Option<\n        PaginatedQuery.SubscriptionRequest<\n          PaginatedQuery.UserArgs<PaginatedQueryRef>\n        >\n      >;\n    },\n    Client.Client\n  > => {\n    const ref = machine.ref;\n    const composedArgsSchema = ref.args;\n    const requestEquivalence = Schema.toEquivalence(\n      machine.subscriptionRequestSchema,\n    );\n    const optionalRequestEquivalence = Option.makeEquivalence<\n      PaginatedQuery.SubscriptionRequest<\n        PaginatedQuery.UserArgs<PaginatedQueryRef>\n      >\n    >((left, right) =>\n      requestEquivalence(\n        { ...left, paginationId: Option.none() },\n        { ...right, paginationId: Option.none() },\n      ),\n    );\n\n    return {\n      dependenciesSchema: Schema.Struct({\n        request: Schema.Option(machine.subscriptionRequestSchema),\n      }),\n      modelToDependencies: (model) => ({\n        request: Match.value(config.state(model)).pipe(\n          Match.tag(\"Idle\", () => Option.none()),\n          Match.tag(\"Active\", (state) =>\n            Option.some(PaginatedQuery.getSubscriptionRequest(state)),\n          ),\n          Match.exhaustive,\n        ),\n      }),\n      keepAliveEquivalence: (left, right) =>\n        optionalRequestEquivalence(left.request, right.request),\n      dependenciesToStream: ({\n        request,\n      }): Stream.Stream<SettledMessage, never, Client.Client> =>\n        Option.match(request, {\n          onNone: () => Stream.empty,\n          onSome: (subscriptionRequest) =>\n            Stream.unwrap(\n              Effect.gen(function* () {\n                const client = yield* Client.Client;\n                const paginationId = yield* client.resolvePaginationId(\n                  subscriptionRequest.paginationId,\n                );\n                const allocatedRequest = PaginatedQuery.allocateRequest(\n                  subscriptionRequest,\n                  paginationId,\n                );\n                const { descriptor, options } = allocatedRequest;\n                const composedArgs = composedArgsSchema.make({\n                  ...allocatedRequest.args,\n                  paginationOpts: {\n                    numItems: options.initialNumItems,\n                    cursor: descriptor.cursor,\n                    id: paginationId,\n                    ...Match.value(options.maximumRowsRead).pipe(\n                      Match.when(undefined, () => ({})),\n                      Match.when(Match.defined, (maximumRowsRead) => ({\n                        maximumRowsRead,\n                      })),\n                      Match.exhaustive,\n                    ),\n                    ...Match.value(options.maximumBytesRead).pipe(\n                      Match.when(undefined, () => ({})),\n                      Match.when(Match.defined, (maximumBytesRead) => ({\n                        maximumBytesRead,\n                      })),\n                      Match.exhaustive,\n                    ),\n                    ...Option.match(descriptor.endCursor, {\n                      onNone: () => ({}),\n                      onSome: (endCursor) => ({ endCursor }),\n                    }),\n                  },\n                });\n                return client.reactiveQueryResult(ref, composedArgs).pipe(\n                  Stream.map((result) =>\n                    config.onSettled({\n                      request: allocatedRequest,\n                      result: Result.mapError(result, paginatedError),\n                    }),\n                  ),\n                );\n              }),\n            ),\n        }),\n    };\n  };\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@confect/foldkit",
   "description": "Client-side bindings for Foldkit apps",
-  "version": "10.0.0-next.22",
+  "version": "10.0.0-next.23",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
@@ -9,6 +9,7 @@
   "devDependencies": {
     "@effect/vitest": "4.0.0-rc.115",
     "@types/node": "24.13.3",
+    "confect-test-types": "0.0.0",
     "convex": "1.45.0",
     "effect": "4.0.0-rc.115",
     "foldkit": "0.148.1",
@@ -50,8 +51,8 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "peerDependencies": {
-    "@confect/core": "^10.0.0-next.22",
-    "@confect/js": "^10.0.0-next.22",
+    "@confect/core": "^10.0.0-next.23",
+    "@confect/js": "^10.0.0-next.23",
     "effect": "^4.0.0-rc.115",
     "foldkit": "^0.148.0"
   },
@@ -66,6 +67,7 @@
     "clean": "shx rm -rf dist coverage node_modules",
     "dev": "tsdown --watch --no-clean --config-loader unrun",
     "test": "vitest run",
-    "typecheck": "tsc -b tsconfig.src.json"
+    "typecheck": "tsc -b tsconfig.src.json",
+    "typecheck:inexact": "tsc --noEmit --project tsconfig.json --exactOptionalPropertyTypes false"
   }
 }

package/src/Command.ts

@@ -6,10 +6,10 @@ import * as FoldkitCommand from "foldkit/command";
 import * as Client from "./Client";
 
 /**
- * Everything a Command against `Ref_` can fail with before it is folded into
- * an `onError` Message: the ref's typed error (if it declares an `error`
- * schema), a transport-level `WebSocketClientError`, or a `SchemaError` from
- * encoding args or decoding returns.
+ * Everything a Command against `Ref_` can fail with before it is folded into an
+ * `onError` Message: the ref's typed error (if it declares an `error` schema),
+ * a transport-level `WebSocketClientError`, or a `SchemaError` from encoding
+ * args or decoding returns.
  */
 export type Error<Ref_ extends Ref.AnyConfect> =
   | Ref.Error<Ref_>
@@ -17,9 +17,10 @@ export type Error<Ref_ extends Ref.AnyConfect> =
   | Schema.SchemaError;
 
 /**
- * Maps a Confect function's outcome into the app's Messages. Every failure—the ref's typed error, a transport error, or a codec error—arrives via
- * `onError`, so the resulting Command's error channel is `never`, as Foldkit
- * requires. Follow Foldkit's naming convention: past-tense facts like
+ * Maps a Confect function's outcome into the app's Messages. Every failure—the
+ * ref's typed error, a transport error, or a codec error—arrives via `onError`,
+ * so the resulting Command's error channel is `never`, as Foldkit requires.
+ * Follow Foldkit's naming convention: past-tense facts like
  * `SucceededSaveNote`/`FailedSaveNote`.
  */
 export interface Handlers<
@@ -49,13 +50,13 @@ type SchemaArgs<Ref_ extends Ref.AnyConfect> = Schema.Schema.Type<
 >;
 
 /**
- * A Foldkit Command definition whose args are the ref's args: our
- * ref-derived call signature (args optional when the ref declares none)
- * intersected with Foldkit's own `CommandDefinitionWithArgs`, which supplies
- * the `CommandDefinitionTypeId` brand and makes the definition assignable
- * wherever Foldkit accepts one—including Story/Scene `Command.resolve`
- * and `expectExact` matchers. Call it from `update` to construct a Command
- * instance; nothing runs until the Foldkit runtime executes it.
+ * A Foldkit Command definition whose args are the ref's args: our ref-derived
+ * call signature (args optional when the ref declares none) intersected with
+ * Foldkit's own `CommandDefinitionWithArgs`, which supplies the
+ * `CommandDefinitionTypeId` brand and makes the definition assignable wherever
+ * Foldkit accepts one—including Story/Scene `Command.resolve` and `expectExact`
+ * matchers. Call it from `update` to construct a Command instance; nothing runs
+ * until the Foldkit runtime executes it.
  */
 export type Definition<
   Name extends string,
@@ -76,8 +77,8 @@ export type Definition<
  * invocations can be targeted independently.
  *
  * Interrupting stops the client-side Effect and guarantees the invocation's
- * result Messages never dispatch—it does not cancel the Convex function on
- * the server, which runs to completion once the call is on the wire.
+ * result Messages never dispatch—it does not cancel the Convex function on the
+ * server, which runs to completion once the call is on the wire.
  */
 export type InterruptOption<
   Ref_ extends Ref.AnyConfect,
@@ -97,8 +98,8 @@ export type KeyedInterrupt<
 /**
  * An interruptible Command definition whose key is the Command name—the
  * ref-derived call signature intersected with Foldkit's
- * `Interruptible.DefinitionWithArgsNameKeyed`, which supplies the brand and
- * the `Interrupt` constructor.
+ * `Interruptible.DefinitionWithArgsNameKeyed`, which supplies the brand and the
+ * `Interrupt` constructor.
  */
 export type InterruptibleDefinition<
   Name extends string,
@@ -149,8 +150,8 @@ const run = <Ref_ extends Ref.AnyConfect, SuccessMessage, ErrorMessage>(
 
 /**
  * An execute body for a hand-written `Command.define`—every failure already
- * folded into a Message. Reach for these when the factory below doesn't fit:
- * a custom args schema, `interrupt`, or a Command that makes several calls.
+ * folded into a Message. Reach for these when the factory below doesn't fit: a
+ * custom args schema, `interrupt`, or a Command that makes several calls.
  */
 export const queryEffect =
   <Query extends Ref.AnyConfectPublicQuery, SuccessMessage, ErrorMessage>(
@@ -411,22 +412,26 @@ const makeFactory = <BoundRef extends Ref.AnyConfect>(
  *   messages: [SucceededGetNote, FailedGetNote],
  *   onSuccess: (note) => SucceededGetNote({ note }),
  *   onError: (error) => FailedGetNote({ message: String(error) }),
- * })
+ * });
  * // In update:
  * // [model, [FetchNote({ noteId })]]
  * ```
  *
  * Pass `interrupt` to make invocations interruptible via the returned
- * definition's `Interrupt` constructor—`true` keys them by the Command
- * name, `{ keyFields, toKey }` by a part derived from the ref's args:
+ * definition's `Interrupt` constructor—`true` keys them by the Command name, `{
+ * keyFields, toKey }` by a part derived from the ref's args:
  *
  * ```ts
- * const SaveDraft = Command.mutation("SaveDraft", refs.public.notes.insert, {
- *   messages: [SucceededSaveDraft, FailedSaveDraft],
- *   onSuccess: (noteId) => SucceededSaveDraft({ noteId }),
- *   onError: (error) => FailedSaveDraft({ message: String(error) }),
- *   interrupt: true,
- * })
+ * const SaveDraft = Command.mutation(
+ *   "SaveDraft",
+ *   refs.public.notes.insert,
+ *   {
+ *     messages: [SucceededSaveDraft, FailedSaveDraft],
+ *     onSuccess: (noteId) => SucceededSaveDraft({ noteId }),
+ *     onError: (error) => FailedSaveDraft({ message: String(error) }),
+ *     interrupt: true,
+ *   },
+ * );
  * // In update:
  * // [model, [SaveDraft.Interrupt((outcome) => CompletedCancelSaveDraft({ outcome }))]]
  * ```
@@ -443,8 +448,8 @@ export const mutation: ReturnType<
 > = makeFactory(mutationEffect);
 
 /**
- * A Foldkit Command definition for a Confect action whose Command args are
- * the ref's args. See `query`.
+ * A Foldkit Command definition for a Confect action whose Command args are the
+ * ref's args. See `query`.
  */
 export const action: ReturnType<
   typeof makeFactory<Ref.AnyConfectPublicAction>

package/src/PaginatedQuery.ts

@@ -11,7 +11,9 @@ import * as SchemaGetter from "effect/SchemaGetter";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as Client from "./Client";
 
-/** Identifies the cursor range fetched for one page. */
+/**
+ * Identifies the cursor range fetched for one page.
+ */
 export interface PageDescriptor {
   readonly cursor: string | null;
   readonly endCursor: Option.Option<string>;
@@ -22,7 +24,9 @@ export const PageDescriptor = Schema.Struct({
   endCursor: Schema.Option(Schema.String),
 });
 
-/** Options that remain fixed for one pagination session. */
+/**
+ * Options that remain fixed for one pagination session.
+ */
 export interface Options {
   readonly initialNumItems: number;
   readonly maximumRowsRead?: number;
@@ -38,7 +42,9 @@ export const Options = Schema.Struct({
   maximumBytesRead: Schema.optionalKey(PositiveInt),
 });
 
-/** Why the machine is fetching its current target. */
+/**
+ * Why the machine is fetching its current target.
+ */
 export type Direction =
   | "Initial"
   | "Next"
@@ -47,7 +53,9 @@ export type Direction =
   | "Split"
   | "Reset";
 
-/** A complete page that can remain on screen while another page is fetched. */
+/**
+ * A complete page that can remain on screen while another page is fetched.
+ */
 export interface Page<Item_> {
   readonly descriptor: PageDescriptor;
   readonly number: number;
@@ -89,12 +97,16 @@ interface PhaseDefinition extends Data.TaggedEnum.WithGenerics<2> {
 
 const Phase = Data.taggedEnum<PhaseDefinition>();
 
-/** A closed machine that retains its generation for stale-result rejection. */
+/**
+ * A closed machine that retains its generation for stale-result rejection.
+ */
 export type Idle = Data.TaggedEnum<{
   Idle: { readonly generation: number };
 }>;
 
-/** A live cursor-pagination session. */
+/**
+ * A live cursor-pagination session.
+ */
 export type Active<Item_, UserArgs_, Error_> = Data.TaggedEnum<{
   Active: {
     readonly generation: number;
@@ -108,7 +120,9 @@ export type Active<Item_, UserArgs_, Error_> = Data.TaggedEnum<{
   };
 }>;
 
-/** A schema-backed cursor-pagination machine. */
+/**
+ * A schema-backed cursor-pagination machine.
+ */
 export type State<Item_, UserArgs_, Error_> =
   | Idle
   | Active<Item_, UserArgs_, Error_>;
@@ -119,7 +133,9 @@ interface StateDefinition extends Data.TaggedEnum.WithGenerics<3> {
 
 const State = Data.taggedEnum<StateDefinition>();
 
-/** The logical request from which a subscription allocates a session id. */
+/**
+ * The logical request from which a subscription allocates a session id.
+ */
 export interface SubscriptionRequest<UserArgs_> {
   readonly generation: number;
   readonly args: UserArgs_;
@@ -129,7 +145,9 @@ export interface SubscriptionRequest<UserArgs_> {
   readonly descriptor: PageDescriptor;
 }
 
-/** The complete identity and arguments of a subscribed page request. */
+/**
+ * The complete identity and arguments of a subscribed page request.
+ */
 export interface Request<UserArgs_> {
   readonly generation: number;
   readonly args: UserArgs_;
@@ -139,7 +157,9 @@ export interface Request<UserArgs_> {
   readonly descriptor: PageDescriptor;
 }
 
-/** The successful payload returned by a Convex paginated query. */
+/**
+ * The successful payload returned by a Convex paginated query.
+ */
 export interface PageResult<Item_> {
   readonly page: ReadonlyArray<Item_>;
   readonly isDone: boolean;
@@ -149,8 +169,8 @@ export interface PageResult<Item_> {
 }
 
 /**
- * One correlated subscription outcome. Both success and failure travel
- * through this value so `settle` can mirror `AsyncData.settle`.
+ * One correlated subscription outcome. Both success and failure travel through
+ * this value so `settle` can mirror `AsyncData.settle`.
  */
 export interface Settlement<Item_, UserArgs_, Error_> {
   readonly request: Request<UserArgs_>;
@@ -173,18 +193,24 @@ interface FunctionErrorDefinition extends Data.TaggedEnum.WithGenerics<1> {
   readonly taggedEnum: TaggedFunctionError<this["A"]>;
 }
 
-/** Constructs a declared function or middleware failure envelope. */
+/**
+ * Constructs a declared function or middleware failure envelope.
+ */
 export const FunctionError =
   Data.taggedEnum<FunctionErrorDefinition>().FunctionError;
 
-/** A declared function or middleware failure, kept distinct from client errors. */
+/**
+ * A declared function or middleware failure, kept distinct from client errors.
+ */
 export type FunctionError<Query extends Ref.AnyConfectPublicPaginatedQuery> = [
   Ref.Error<Query>,
 ] extends [never]
   ? never
   : TaggedFunctionError<Ref.Error<Query>>;
 
-/** Every failure a paginated query subscription can settle with. */
+/**
+ * Every failure a paginated query subscription can settle with.
+ */
 export type Error<Query extends Ref.AnyConfectPublicPaginatedQuery> =
   | FunctionError<Query>
   | PaginationError.InvalidCursor
@@ -205,7 +231,9 @@ type MachineActive<Query extends Ref.AnyConfectPublicPaginatedQuery> = Active<
   Error<Query>
 >;
 
-/** The schema-and-constructor bundle returned by `make`. */
+/**
+ * The schema-and-constructor bundle returned by `make`.
+ */
 export interface PaginatedQuery<
   Query extends Ref.AnyConfectPublicPaginatedQuery,
 > {
@@ -295,7 +323,9 @@ const SerializableSchemaError = Schema.instanceOf(Schema.SchemaError, {
     }),
 });
 
-/** Builds a page machine from a paginated ref. */
+/**
+ * Builds a page machine from a paginated ref.
+ */
 export const make = <Query extends Ref.AnyConfectPublicPaginatedQuery>(
   ref: Query,
 ): PaginatedQuery<Query> => {
@@ -483,7 +513,9 @@ const descriptorEquals = (a: PageDescriptor, b: PageDescriptor): boolean =>
       }),
   });
 
-/** Returns the logical request currently driving the subscription. */
+/**
+ * Returns the logical request currently driving the subscription.
+ */
 export const getSubscriptionRequest = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): SubscriptionRequest<UserArgs_> => ({
@@ -495,7 +527,9 @@ export const getSubscriptionRequest = <Item_, UserArgs_, Error_>(
   descriptor: state.current,
 });
 
-/** Attaches the client-allocated pagination id to a logical request. */
+/**
+ * Attaches the client-allocated pagination id to a logical request.
+ */
 export const allocateRequest = <UserArgs_>(
   request: SubscriptionRequest<UserArgs_>,
   paginationId: number,
@@ -525,12 +559,16 @@ const pendingPhase = <Item_>(
     onSome: (page) => Phase.Refreshing<Item_, never>({ data: page, direction }),
   });
 
-/** Close the subscription while retaining its generation tombstone. */
+/**
+ * Close the subscription while retaining its generation tombstone.
+ */
 export const close = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Idle => State.Idle({ generation: state.generation });
 
-/** Start a fresh pagination session at page one while retaining visible data. */
+/**
+ * Start a fresh pagination session at page one while retaining visible data.
+ */
 export const reset = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Active<Item_, UserArgs_, Error_> => ({
@@ -546,13 +584,13 @@ export const reset = <Item_, UserArgs_, Error_>(
 /**
  * Navigate to the next page, retaining the current page while it loads.
  *
- * The page being left is pushed onto the stack *pinned* to the range it
- * displayed—its cursor to its continuation cursor—so `prev` reloads
- * exactly that range rather than the first `initialNumItems` documents
- * after its cursor, however the data has moved meanwhile. Convex's own
- * pagination keeps that range in its query journal; stream-paginated
- * queries have no journal, so the pin is what keeps consecutive pages
- * gap-free and duplicate-free for them.
+ * The page being left is pushed onto the stack _pinned_ to the range it
+ * displayed—its cursor to its continuation cursor—so `prev` reloads exactly
+ * that range rather than the first `initialNumItems` documents after its
+ * cursor, however the data has moved meanwhile. Convex's own pagination keeps
+ * that range in its query journal; stream-paginated queries have no journal, so
+ * the pin is what keeps consecutive pages gap-free and duplicate-free for
+ * them.
  */
 export const next = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
@@ -589,7 +627,9 @@ export const next = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Navigate to the previous page, retaining the current page while it loads. */
+/**
+ * Navigate to the previous page, retaining the current page while it loads.
+ */
 export const prev = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Option.Option<Active<Item_, UserArgs_, Error_>> =>
@@ -619,7 +659,9 @@ export const prev = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Navigate to page one without invalidating the current pagination session. */
+/**
+ * Navigate to page one without invalidating the current pagination session.
+ */
 export const first = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): Option.Option<Active<Item_, UserArgs_, Error_>> =>
@@ -641,7 +683,9 @@ export const first = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Whether a request still names the machine's live pagination session/page. */
+/**
+ * Whether a request still names the machine's live pagination session/page.
+ */
 export const isCurrentRequest = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
   candidate: Request<UserArgs_>,
@@ -810,7 +854,9 @@ export const settle: {
     ),
 );
 
-/** The complete page currently available to render. */
+/**
+ * The complete page currently available to render.
+ */
 export const getPage = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<Page<Item_>> =>
@@ -820,13 +866,17 @@ export const getPage = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** The items currently available to render. */
+/**
+ * The items currently available to render.
+ */
 export const getItems = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<ReadonlyArray<Item_>> =>
   Option.map(getPage(state), (page) => page.items);
 
-/** The error from the most recent failed request, if any. */
+/**
+ * The error from the most recent failed request, if any.
+ */
 export const getError = <Item_, UserArgs_, Error_>(
   state: State<Item_, UserArgs_, Error_>,
 ): Option.Option<Error_> =>
@@ -844,7 +894,9 @@ export const getError = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** The 1-indexed page number currently targeted by the subscription. */
+/**
+ * The 1-indexed page number currently targeted by the subscription.
+ */
 export const targetPageNumber = <Item_, UserArgs_, Error_>(
   state: Active<Item_, UserArgs_, Error_>,
 ): number => state.prevStack.length + 1;
@@ -959,7 +1011,9 @@ export const canPrev = <Item_, UserArgs_, Error_>(
     Match.exhaustive,
   );
 
-/** Pattern-match exhaustively on the machine's AsyncData-style state. */
+/**
+ * Pattern-match exhaustively on the machine's AsyncData-style state.
+ */
 export const match: {
   <Item_, Error_, A, B, C, D, E, F>(handlers: {
     readonly onIdle: (idle: Idle) => A;