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

package/src/Ref.ts

@@ -1,6 +1,9 @@
 import type {
+  DefaultFunctionArgs,
   FunctionReference as ConvexFunctionReference,
   FunctionVisibility,
+  PaginationOptions,
+  PaginationResult,
 } from "convex/server";
 import { makeFunctionReference } from "convex/server";
 import type { Value } from "convex/values";
@@ -9,175 +12,307 @@ import * as Effect from "effect/Effect";
 import * as Match from "effect/Match";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
+import type * as FunctionProvenance from "./FunctionProvenance";
 import type * as FunctionSpec from "./FunctionSpec";
+import * as Lazy from "./Lazy";
+import * as MiddlewareSpec from "./MiddlewareSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
 
-export interface Ref<
-  _RuntimeAndFunctionType extends RuntimeAndFunctionType.RuntimeAndFunctionType,
-  _FunctionVisibility extends FunctionVisibility,
-  _Args,
-  _Returns,
-  _Error = never,
+export interface Base<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends DefaultFunctionArgs,
+  Returns_,
+  Error_ = never,
 > {
-  readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;
-  readonly _FunctionVisibility?: _FunctionVisibility;
-  readonly _Args?: _Args;
-  readonly _Returns?: _Returns;
-  readonly _Error?: _Error;
-  /** @internal */
-  readonly functionSpec: FunctionSpec.AnyWithProps;
-  /** @internal */
-  readonly functionNamespace: string;
+  readonly "~RuntimeAndFunctionType": RuntimeAndFunctionType_;
+  readonly "~FunctionVisibility": FunctionVisibility_;
+  readonly "~Args": Args_;
+  readonly "~Returns": Returns_;
+  readonly "~Error": Error_;
+  readonly convexFunctionName: string;
 }
 
-export interface Any extends Ref<any, any, any, any, any> {}
+/**
+ * A reference to a single Convex function, as callers see it: the wire name
+ * plus the data needed to encode args, decode returns, and decode typed
+ * errors. A ref is one of two shapes, keyed by the spec's provenance.
+ */
+export type Ref<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends DefaultFunctionArgs,
+  Returns_,
+  Error_ = never,
+> =
+  | ConfectRefWithTypes<
+      RuntimeAndFunctionType_,
+      FunctionVisibility_,
+      FunctionProvenance.ArgsFields,
+      Args_,
+      Returns_,
+      Error_
+    >
+  | ConvexRef<
+      RuntimeAndFunctionType_,
+      FunctionVisibility_,
+      Args_,
+      Returns_,
+      Error_
+    >;
+
+export type ConfectRef<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  ReturnsSchema_ extends Schema.Codec<any, any>,
+  ErrorSchema_ extends Schema.Codec<any, any> = never,
+  MiddlewareError_ = never,
+> = ConfectRefWithTypes<
+  RuntimeAndFunctionType_,
+  FunctionVisibility_,
+  ArgsFields_,
+  Schema.Struct.Type<ArgsFields_>,
+  ReturnsSchema_["Type"],
+  ErrorSchema_["Type"] | MiddlewareError_
+>;
+
+/**
+ * Internal form used while mapping a spec to a ref. Supplying the already
+ * derived value types avoids repeatedly expanding `Schema.Struct` for every
+ * leaf in a generated ref tree; the public `ConfectRef` alias still derives
+ * the same values from its fields and schemas.
+ */
+interface ConfectRefWithTypes<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  Args_ extends DefaultFunctionArgs,
+  Returns_,
+  Error_,
+> extends Base<
+  RuntimeAndFunctionType_,
+  FunctionVisibility_,
+  Args_,
+  Returns_,
+  Error_
+> {
+  readonly _tag: "Confect";
+  readonly args: FunctionProvenance.ArgsSchema<ArgsFields_>;
+  readonly returns: Schema.Codec<any, any>;
+  readonly kind: FunctionProvenance.ConfectKind;
+  readonly middlewareSpecs: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+  readonly error?: Schema.Codec<any, any>;
+}
+
+export interface ConvexRef<
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  Args_ extends DefaultFunctionArgs,
+  Returns_,
+  Error_ = never,
+> extends Base<
+  RuntimeAndFunctionType_,
+  FunctionVisibility_,
+  Args_,
+  Returns_,
+  Error_
+> {
+  readonly _tag: "Convex";
+}
 
-export interface AnyInternal extends Ref<any, "internal", any, any, any> {}
+export type Any = Ref<any, any, any, any, any>;
 
-export interface AnyPublic extends Ref<any, "public", any, any, any> {}
+/** Erased Confect-provenance ref used by provenance-specific APIs. */
+export type AnyConfect = Extract<Any, { readonly _tag: "Confect" }>;
 
-export interface AnyQuery extends Ref<
+export type AnyInternal = Ref<any, "internal", any, any, any>;
+
+export type AnyPublic = Ref<any, "public", any, any, any>;
+
+export type AnyQuery = Ref<
   RuntimeAndFunctionType.AnyQuery,
   FunctionVisibility,
   any,
   any,
   any
-> {}
+>;
+
+export type AnyPaginatedQuery = AnyQuery &
+  Base<
+    RuntimeAndFunctionType.AnyQuery,
+    FunctionVisibility,
+    {
+      [key: string]: any;
+      paginationOpts: PaginationOptions;
+    },
+    PaginationResult<any>,
+    any
+  >;
 
-export interface AnyMutation extends Ref<
+export type AnyMutation = Ref<
   RuntimeAndFunctionType.AnyMutation,
   FunctionVisibility,
   any,
   any,
   any
-> {}
+>;
 
-export interface AnyAction extends Ref<
+export type AnyAction = Ref<
   RuntimeAndFunctionType.AnyAction,
   FunctionVisibility,
   any,
   any,
   any
-> {}
+>;
 
-export interface AnyPublicQuery extends Ref<
+export type AnyPublicQuery = Ref<
   RuntimeAndFunctionType.AnyQuery,
   "public",
   any,
   any,
   any
-> {}
+>;
+
+export type AnyConfectPublicQuery = Extract<AnyPublicQuery, AnyConfect>;
+
+export type AnyPublicPaginatedQuery = AnyPublicQuery & AnyPaginatedQuery;
 
-export interface AnyPublicMutation extends Ref<
+export type AnyConfectPublicPaginatedQuery = AnyConfectPublicQuery &
+  AnyPublicPaginatedQuery;
+
+export type AnyPublicMutation = Ref<
   RuntimeAndFunctionType.AnyMutation,
   "public",
   any,
   any,
   any
-> {}
+>;
+
+export type AnyConfectPublicMutation = Extract<AnyPublicMutation, AnyConfect>;
 
-export interface AnyPublicAction extends Ref<
+export type AnyPublicAction = Ref<
   RuntimeAndFunctionType.AnyAction,
   "public",
   any,
   any,
   any
-> {}
-
-export type GetRuntimeAndFunctionType<Ref_> =
-  Ref_ extends Ref<
-    infer RuntimeAndFunctionType_,
-    infer _FunctionVisibility,
-    infer _Args,
-    infer _Returns,
-    infer _Error
-  >
-    ? RuntimeAndFunctionType_
-    : never;
-
-export type GetRuntime<Ref_> =
-  Ref_ extends Ref<
-    infer RuntimeAndFunctionType_,
-    infer _FunctionVisibility,
-    infer _Args,
-    infer _Returns,
-    infer _Error
-  >
-    ? RuntimeAndFunctionType.GetRuntime<RuntimeAndFunctionType_>
-    : never;
-
-export type GetFunctionType<Ref_> =
-  Ref_ extends Ref<
-    infer RuntimeAndFunctionType_,
-    infer _FunctionVisibility,
-    infer _Args,
-    infer _Returns,
-    infer _Error
-  >
-    ? RuntimeAndFunctionType.GetFunctionType<RuntimeAndFunctionType_>
-    : never;
-
-export type GetFunctionVisibility<Ref_> =
-  Ref_ extends Ref<
-    infer _RuntimeAndFunctionType,
-    infer FunctionVisibility_,
-    infer _Args,
-    infer _Returns,
-    infer _Error
-  >
-    ? FunctionVisibility_
-    : never;
-
-export type Args<Ref_> =
-  Ref_ extends Ref<
-    infer _RuntimeAndFunctionType,
-    infer _FunctionVisibility,
-    infer Args_,
-    infer _Returns,
-    infer _Error
-  >
-    ? Args_
-    : never;
+>;
+
+export type AnyConfectPublicAction = Extract<AnyPublicAction, AnyConfect>;
+
+export type GetRuntimeAndFunctionType<Ref_> = Ref_ extends {
+  readonly "~RuntimeAndFunctionType": infer RuntimeAndFunctionType_ extends
+    RuntimeAndFunctionType.RuntimeAndFunctionType;
+}
+  ? RuntimeAndFunctionType_
+  : never;
+
+export type GetRuntime<Ref_> = RuntimeAndFunctionType.GetRuntime<
+  GetRuntimeAndFunctionType<Ref_>
+>;
+
+export type GetFunctionType<Ref_> = RuntimeAndFunctionType.GetFunctionType<
+  GetRuntimeAndFunctionType<Ref_>
+>;
+
+export type GetFunctionVisibility<Ref_> = Ref_ extends {
+  readonly "~FunctionVisibility": infer FunctionVisibility_;
+}
+  ? FunctionVisibility_
+  : never;
+
+export type Args<Ref_> = Ref_ extends { readonly "~Args": infer Args_ }
+  ? Args_
+  : never;
+
+/** The field map captured by a Confect-provenance ref. */
+export type ArgsFields<Ref_> = Ref_ extends {
+  readonly _tag: "Confect";
+  readonly args: {
+    readonly fields: infer ArgsFields_ extends FunctionProvenance.ArgsFields;
+  };
+}
+  ? ArgsFields_
+  : never;
+
+/** The assembled args schema carried by a Confect-provenance ref. */
+export type ArgsSchema<Ref_> = Ref_ extends {
+  readonly _tag: "Confect";
+  readonly args: infer ArgsSchema_ extends FunctionProvenance.AnyArgsSchema;
+}
+  ? ArgsSchema_
+  : never;
 
 export type OptionalArgs<Ref_ extends Any> = keyof Args<Ref_> extends never
   ? [args?: Args<Ref_>]
   : [args: Args<Ref_>];
 
-export type Returns<Ref_> =
-  Ref_ extends Ref<
-    infer _RuntimeAndFunctionType,
-    infer _FunctionVisibility,
-    infer _Args,
-    infer Returns_,
-    infer _Error
-  >
-    ? Returns_
-    : never;
-
-export type Error<Ref_> =
-  Ref_ extends Ref<
-    infer _RuntimeAndFunctionType,
-    infer _FunctionVisibility,
-    infer _Args,
-    infer _Returns,
-    infer Error_
-  >
-    ? Error_
-    : never;
+export type Returns<Ref_> = Ref_ extends { readonly "~Returns": infer Returns_ }
+  ? Returns_
+  : never;
+
+export type Error<Ref_> = Ref_ extends { readonly "~Error": infer Error_ }
+  ? Error_
+  : never;
 
 export type FunctionReference<Ref_ extends Any> = ConvexFunctionReference<
   GetFunctionType<Ref_>,
   GetFunctionVisibility<Ref_>
 >;
 
-export type FromFunctionSpec<FunctionSpec_ extends FunctionSpec.AnyWithProps> =
-  Ref<
-    FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,
-    FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
-    FunctionSpec.Args<FunctionSpec_>,
-    FunctionSpec.Returns<FunctionSpec_>,
-    FunctionSpec.Error<FunctionSpec_>
-  >;
+export type FromFunctionSpec<
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+  MiddlewareError = never,
+> = FromFunctionSpecHelper<
+  FunctionSpec_,
+  FunctionSpec.GetRuntimeAndFunctionType<FunctionSpec_>,
+  FunctionSpec.GetFunctionVisibility<FunctionSpec_>,
+  FunctionSpec.ArgsFields<FunctionSpec_>,
+  FunctionSpec.Args<FunctionSpec_>,
+  FunctionSpec.Returns<FunctionSpec_>,
+  FunctionSpec.Error<FunctionSpec_> | MiddlewareError
+>;
+
+type FromFunctionSpecHelper<
+  FunctionSpec_ extends FunctionSpec.AnyWithProps,
+  RuntimeAndFunctionType_ extends RuntimeAndFunctionType.RuntimeAndFunctionType,
+  FunctionVisibility_ extends FunctionVisibility,
+  ArgsFields_ extends FunctionProvenance.ArgsFields,
+  Args_ extends DefaultFunctionArgs,
+  Returns_,
+  Error_,
+> =
+  FunctionSpec_ extends FunctionSpec.WithFunctionProvenance<
+    FunctionSpec_,
+    FunctionProvenance.AnyConvex
+  >
+    ? ConvexRef<
+        RuntimeAndFunctionType_,
+        FunctionVisibility_,
+        Args_ extends DefaultFunctionArgs ? Args_ : never,
+        Returns_,
+        never
+      >
+    : FunctionSpec_ extends FunctionSpec.WithFunctionProvenance<
+          FunctionSpec_,
+          FunctionProvenance.AnyConfect
+        >
+      ? ConfectRefWithTypes<
+          RuntimeAndFunctionType_,
+          FunctionVisibility_,
+          ArgsFields_,
+          Args_,
+          Returns_,
+          Error_
+        >
+      : Ref<
+          RuntimeAndFunctionType_,
+          FunctionVisibility_,
+          Args_,
+          Returns_,
+          Error_
+        >;
 
 export const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(
   /**
@@ -185,36 +320,74 @@ export const make = <FunctionSpec_ extends FunctionSpec.AnyWithProps>(
    * colon. For example, for `myGroupDir/myGroupMod:myFunc` this would be
    * `myGroupDir/myGroupMod`.
    */
-  functionNamespace: string,
+  convexFunctionNamespace: string,
   functionSpec: FunctionSpec_,
-): FromFunctionSpec<FunctionSpec_> => ({ functionSpec, functionNamespace });
+  groupMiddlewareSpecs: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec> = [],
+): FromFunctionSpec<FunctionSpec_> => {
+  const convexFunctionName = `${convexFunctionNamespace}:${functionSpec.name}`;
+
+  return Match.value(functionSpec.functionProvenance).pipe(
+    Match.tag(
+      "Convex",
+      (): Any =>
+        ({
+          _tag: "Convex",
+          convexFunctionName,
+        }) as Any,
+    ),
+    Match.tag("Confect", (provenance): Any => {
+      const ref = {
+        _tag: "Confect" as const,
+        convexFunctionName,
+        kind: provenance.kind,
+        middlewareSpecs: [
+          ...groupMiddlewareSpecs,
+          ...functionSpec.middlewareSpecs,
+        ],
+      };
+
+      Lazy.defineProperty(ref, "args", () => provenance.args);
+      Lazy.defineProperty(ref, "returns", () => provenance.returns);
+      if ("error" in provenance) {
+        Lazy.defineProperty(ref, "error", () => provenance.error);
+      }
+
+      return ref as unknown as Any;
+    }),
+    Match.exhaustive,
+  ) as FromFunctionSpec<FunctionSpec_>;
+};
 
 export const getConvexFunctionName = (ref: Any): string =>
-  `${ref.functionNamespace}:${ref.functionSpec.name}`;
+  ref.convexFunctionName;
 
 const functionReferenceCache = new Map<string, FunctionReference<Any>>();
 
 export const getFunctionReference = <Ref_ extends Any>(
   ref: Ref_,
 ): FunctionReference<Ref_> => {
-  const functionName = getConvexFunctionName(ref);
+  const convexFunctionName = getConvexFunctionName(ref);
 
-  const cached = functionReferenceCache.get(functionName);
+  const cached = functionReferenceCache.get(convexFunctionName);
   if (cached !== undefined) {
     return cached as FunctionReference<Ref_>;
   }
 
-  const functionReference = makeFunctionReference(functionName);
-  functionReferenceCache.set(functionName, functionReference);
+  const functionReference = makeFunctionReference(convexFunctionName);
+  functionReferenceCache.set(convexFunctionName, functionReference);
 
   return functionReference as FunctionReference<Ref_>;
 };
 
 export const hasErrorSchema = (ref: Any): boolean =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
+  Match.value(ref).pipe(
     Match.tag(
       "Confect",
-      (confectFunctionProvenance) => "error" in confectFunctionProvenance,
+      (confectRef) =>
+        "error" in confectRef ||
+        confectRef.middlewareSpecs.some(
+          (middlewareSpec) => "error" in middlewareSpec,
+        ),
     ),
     Match.tag("Convex", () => false),
     Match.exhaustive,
@@ -224,9 +397,9 @@ export const encodeArgs = <Ref_ extends Any>(
   ref: Ref_,
   args: Args<Ref_>,
 ): Effect.Effect<unknown, Schema.SchemaError> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.encodeEffect(confectFunctionProvenance.args)(args),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.encodeEffect(confectRef.args)(args),
     ),
     Match.tag("Convex", () => Effect.succeed(args)),
     Match.exhaustive,
@@ -236,11 +409,11 @@ export const decodeReturns = <Ref_ extends Any>(
   ref: Ref_,
   returns: unknown,
 ): Effect.Effect<Returns<Ref_>, Schema.SchemaError> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeUnknownEffect(confectFunctionProvenance.returns)(returns),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.decodeUnknownEffect(confectRef.returns)(returns),
     ),
-    Match.tag("Convex", () => Effect.succeed(returns)),
+    Match.tag("Convex", () => Effect.succeed(returns as Returns<Ref_>)),
     Match.exhaustive,
   );
 
@@ -248,9 +421,9 @@ export const encodeArgsSync = <Ref_ extends Any>(
   ref: Ref_,
   args: Args<Ref_>,
 ): unknown =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.encodeSync(confectFunctionProvenance.args)(args),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.encodeSync(confectRef.args)(args),
     ),
     Match.tag("Convex", () => args),
     Match.exhaustive,
@@ -260,9 +433,9 @@ export const decodeArgsSync = <Ref_ extends Any>(
   ref: Ref_,
   encodedArgs: unknown,
 ): Args<Ref_> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeUnknownSync(confectFunctionProvenance.args)(encodedArgs),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.decodeUnknownSync(confectRef.args)(encodedArgs),
     ),
     Match.tag("Convex", () => encodedArgs),
     Match.exhaustive,
@@ -272,9 +445,9 @@ export const encodeReturnsSync = <Ref_ extends Any>(
   ref: Ref_,
   returns: Returns<Ref_>,
 ): unknown =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.encodeSync(confectFunctionProvenance.returns)(returns),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.encodeSync(confectRef.returns)(returns),
     ),
     Match.tag("Convex", () => returns),
     Match.exhaustive,
@@ -284,11 +457,9 @@ export const decodeReturnsSync = <Ref_ extends Any>(
   ref: Ref_,
   encodedReturns: unknown,
 ): Returns<Ref_> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeUnknownSync(confectFunctionProvenance.returns)(
-        encodedReturns,
-      ),
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.decodeUnknownSync(confectRef.returns)(encodedReturns),
     ),
     Match.tag("Convex", () => encodedReturns),
     Match.exhaustive,
@@ -315,7 +486,7 @@ export const decodeErrorOrElse =
   <Ref_ extends Any, E>(ref: Ref_, mapUnknownError: (error: unknown) => E) =>
   (error: unknown): Error<Ref_> | E => {
     if (isConvexError(error)) {
-      const decoded = decodeErrorSync(ref, error.data);
+      const decoded = decodeErrorOption(ref, error.data);
       if (Option.isSome(decoded)) {
         return decoded.value;
       }
@@ -323,10 +494,31 @@ export const decodeErrorOrElse =
     return mapUnknownError(error);
   };
 
+const errorSchemaOf = (ref: Any): Option.Option<Schema.Codec<any, any>> =>
+  Match.value(ref).pipe(
+    Match.tag("Confect", (confectRef) => {
+      const schemas = [
+        ...("error" in confectRef && confectRef.error !== undefined
+          ? [confectRef.error]
+          : []),
+        ...MiddlewareSpec.errorSchemas(confectRef.middlewareSpecs),
+      ];
+      return schemas.length === 0
+        ? Option.none<Schema.Codec<any, any>>()
+        : Option.some(
+            schemas.length === 1 ? schemas[0]! : Schema.Union(schemas),
+          );
+    }),
+    Match.tag("Convex", () => Option.none<Schema.Codec<any, any>>()),
+    Match.exhaustive,
+  );
+
 /**
- * Decode `encodedError` against the ref's error schema. Returns `None` if the
- * ref doesn't declare a typed error (Confect ref without an `error` schema, or
- * a Convex-provenance ref)—by definition there's nothing to decode the value
+ * Decode `encodedError` against the ref's error schema — the function's
+ * declared `error` schema unioned with its covering middlewares' error
+ * schemas. Returns `None` if the ref declares no typed error at all (Confect
+ * ref without an `error` schema and without failing middleware, or a
+ * Convex-provenance ref)—by definition there's nothing to decode the value
  * into, and the caller is responsible for deciding what to do (typically:
  * surface the original value as a defect).
  */
@@ -334,60 +526,101 @@ export const decodeError = <Ref_ extends Any>(
   ref: Ref_,
   encodedError: unknown,
 ): Effect.Effect<Option.Option<Error<Ref_>>, Schema.SchemaError> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      "error" in confectFunctionProvenance
-        ? Effect.map(
-            Schema.decodeUnknownEffect(confectFunctionProvenance.error)(
-              encodedError,
-            ),
-            Option.some,
-          )
-        : Effect.succeed(Option.none<Error<Ref_>>()),
-    ),
-    Match.tag("Convex", () => Effect.succeed(Option.none<Error<Ref_>>())),
-    Match.exhaustive,
-  );
+  Option.match(errorSchemaOf(ref), {
+    onNone: () => Effect.succeed(Option.none<Error<Ref_>>()),
+    onSome: (schema) =>
+      Effect.map(
+        Schema.decodeUnknownEffect(schema)(encodedError),
+        Option.some,
+      ) as Effect.Effect<Option.Option<Error<Ref_>>, Schema.SchemaError>,
+  });
 
 /**
- * Synchronous counterpart to `decodeError`. Throws on schema decode failure;
- * returns `None` when the ref doesn't declare a typed error.
+ * Synchronous counterpart to `decodeError`. Returns `None` when the value is
+ * not this ref's typed error — either because the ref declares no `error`
+ * schema, or because `encodedError` doesn't match the one it declares.
+ *
+ * The second case is reachable in normal operation: Convex raises its own
+ * `ConvexError`s (an `InvalidCursor` pagination error, for instance), and
+ * those never match a user-declared error schema. Callers pair this with a
+ * fallback that surfaces the original error, so failing to decode must not
+ * throw — a `ParseError` here would replace the real error with an opaque one
+ * and lose the only useful diagnostic. Hence the `Option` suffix rather than
+ * `Sync`, matching `Schema.decodeUnknownOption`: the sibling `*Sync` helpers
+ * in this module all throw on a parse failure, and this one deliberately
+ * doesn't.
  */
-export const decodeErrorSync = <Ref_ extends Any>(
+export const decodeErrorOption = <Ref_ extends Any>(
   ref: Ref_,
   encodedError: unknown,
 ): Option.Option<Error<Ref_>> =>
-  Match.value(ref.functionSpec.functionProvenance).pipe(
-    Match.tag("Confect", (confectFunctionProvenance) =>
-      "error" in confectFunctionProvenance
-        ? Option.some(
-            Schema.decodeUnknownSync(confectFunctionProvenance.error)(
-              encodedError,
-            ) as Error<Ref_>,
-          )
-        : Option.none<Error<Ref_>>(),
-    ),
-    Match.tag("Convex", () => Option.none<Error<Ref_>>()),
+  Option.flatMap(
+    errorSchemaOf(ref),
+    (schema) =>
+      Schema.decodeUnknownOption(schema)(encodedError) as Option.Option<
+        Error<Ref_>
+      >,
+  );
+
+const missingPaginatedProvenanceError = (ref: Any) =>
+  new globalThis.Error(
+    `Paginated query ref "${getConvexFunctionName(ref)}" was not built with ` +
+      "`FunctionSpec.publicPaginatedQuery` (or `FunctionSpec.internalPaginatedQuery`). " +
+      "Paginated encoding and decoding require the user-args and item schemas " +
+      "those constructors store. Define the function as, e.g.:\n\n" +
+      "  FunctionSpec.publicPaginatedQuery({\n" +
+      '    name: "...",\n' +
+      "    args: () => ({ ... }), // optional; without paginationOpts\n" +
+      "    item: () => ItemSchema,\n" +
+      "  })",
+  );
+
+const paginatedKind = (ref: AnyConfect): FunctionProvenance.Paginated =>
+  Match.value(ref.kind).pipe(
+    Match.tag("Paginated", (kind) => kind),
+    Match.tag("Standard", () => {
+      throw missingPaginatedProvenanceError(ref);
+    }),
     Match.exhaustive,
   );
 
-export const maybeDecodeErrorSync = <Ref_ extends Any>(
+/**
+ * Encode the args of a paginated query ref via its user-args schema —
+ * `paginationOpts` is excluded, since the pagination protocol fields are
+ * managed by the client (e.g. `usePaginatedQuery` from `convex/react`), not by
+ * the caller. Requires a ref built with `FunctionSpec.publicPaginatedQuery`
+ * (or `internalPaginatedQuery`).
+ */
+export const encodePaginatedQueryArgsSync = <
+  Ref_ extends AnyPublicPaginatedQuery,
+>(
   ref: Ref_,
-  error: unknown,
+  args: Omit<Args<Ref_>, "paginationOpts">,
 ): unknown =>
-  isConvexError(error)
-    ? Match.value(ref.functionSpec.functionProvenance).pipe(
-        Match.tag("Confect", (confectFunctionProvenance) =>
-          "error" in confectFunctionProvenance
-            ? Schema.decodeUnknownSync(confectFunctionProvenance.error)(
-                error.data,
-              )
-            : error,
-        ),
-        Match.tag("Convex", () => error),
-        Match.exhaustive,
-      )
-    : error;
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.encodeUnknownSync(paginatedKind(confectRef).userArgs)(args),
+    ),
+    Match.tag("Convex", () => args),
+    Match.exhaustive,
+  );
+
+/**
+ * Decode a page of a paginated query's results via the ref's item schema.
+ * Requires a ref built with `FunctionSpec.publicPaginatedQuery` (or
+ * `internalPaginatedQuery`).
+ */
+export const decodePaginationPageSync = <Ref_ extends AnyPublicPaginatedQuery>(
+  ref: Ref_,
+  encodedPage: unknown,
+): Returns<Ref_>["page"] =>
+  Match.value<Any>(ref).pipe(
+    Match.tag("Confect", (confectRef) =>
+      Schema.decodeUnknownSync(paginatedKind(confectRef).page)(encodedPage),
+    ),
+    Match.tag("Convex", () => encodedPage),
+    Match.exhaustive,
+  ) as Returns<Ref_>["page"];
 
 /**
  * Encode args via the ref's args schema, invoke `call`, decode returns via the
@@ -408,7 +641,6 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
 ): Effect.Effect<Returns<Ref_>, E | Error<Ref_> | Schema.SchemaError> =>
   Effect.gen(function* () {
     const functionReference = getFunctionReference(ref);
-    const functionProvenance = ref.functionSpec.functionProvenance;
     const invoke = (
       encodedArgs: unknown,
     ): Effect.Effect<unknown, Error<Ref_> | E> =>
@@ -416,7 +648,7 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
         try: () => Promise.resolve(call(functionReference, encodedArgs)),
         catch: (error): Error<Ref_> | E => {
           if (isConvexError(error)) {
-            const decoded = decodeErrorSync(ref, error.data);
+            const decoded = decodeErrorOption(ref, error.data);
             if (Option.isSome(decoded)) {
               return decoded.value;
             }
@@ -427,19 +659,8 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
           throw error;
         },
       });
-    return yield* Match.value(functionProvenance).pipe(
-      Match.tag("Confect", (confectFunctionProvenance) =>
-        Effect.gen(function* () {
-          const encodedArgs = yield* Schema.encodeEffect(
-            confectFunctionProvenance.args,
-          )(args);
-          const encodedReturns = yield* invoke(encodedArgs);
-          return yield* Schema.decodeUnknownEffect(
-            confectFunctionProvenance.returns,
-          )(encodedReturns);
-        }),
-      ),
-      Match.tag("Convex", () => invoke(args)),
-      Match.exhaustive,
-    );
+
+    const encodedArgs = yield* encodeArgs(ref, args);
+    const encodedReturns = yield* invoke(encodedArgs);
+    return yield* decodeReturns(ref, encodedReturns);
   });