@confect/core 9.2.4 → 9.3.0

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@confect/core",
   "description": "Shared specs and schemas used by all Confect packages",
-  "version": "9.2.4",
+  "version": "9.3.0",
   "author": "RJ Dellecese",
   "bugs": {
     "url": "https://github.com/rjdellecese/confect/issues"
   },
   "devDependencies": {
     "@ark/attest": "0.56.3",
-    "@effect/vitest": "0.29.0",
+    "@effect/vitest": "0.30.0",
     "@types/node": "26.1.1",
-    "effect": "3.21.2",
-    "tsdown": "0.22.7",
-    "tsx": "4.23.0",
+    "effect": "3.22.0",
+    "tsdown": "0.22.14",
+    "tsx": "4.23.1",
     "typescript": "6.0.3",
     "unrun": "0.3.1",
     "vitest": "4.1.10"

package/src/FunctionProvenance.ts

@@ -1,13 +1,16 @@
 import type { DefaultFunctionArgs } from "convex/server";
-import type { Schema } from "effect";
 import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
 import * as Lazy from "./Lazy";
+import * as PaginationOptions from "./PaginationOptions";
+import * as PaginationResult from "./PaginationResult";
 
 export type FunctionProvenance = Data.TaggedEnum<{
   Confect: {
     args: Schema.Schema.AnyNoContext;
     returns: Schema.Schema.AnyNoContext;
     error?: Schema.Schema.AnyNoContext;
+    kind: ConfectKind;
   };
   Convex: {
     /** @internal */
@@ -17,15 +20,43 @@ export type FunctionProvenance = Data.TaggedEnum<{
   };
 }>;
 
+/**
+ * The declaration shape of a Confect function — orthogonal to both the
+ * provenance origin (Confect vs Convex) and the function type
+ * (query/mutation/action). A `Standard` function declares its `args` and
+ * `returns` schemas directly; a `Paginated` function declares `userArgs` and
+ * `item` schemas from which the Convex-facing `args`/`returns` are composed.
+ */
+export type ConfectKind = Standard | Paginated;
+
+export interface Standard {
+  readonly _tag: "Standard";
+}
+
+export interface Paginated<
+  UserArgs extends AnyUserArgs = AnyUserArgs,
+  Item extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext,
+> {
+  readonly _tag: "Paginated";
+  /** User-declared args — no `paginationOpts`. */
+  readonly userArgs: UserArgs;
+  /** Page element schema. */
+  readonly item: Item;
+  /** Mutable array of items — the page decode target. */
+  readonly page: Schema.Schema.AnyNoContext;
+}
+
 export interface Confect<
   Args extends Schema.Schema.AnyNoContext,
   Returns extends Schema.Schema.AnyNoContext,
   Error extends Schema.Schema.AnyNoContext = never,
+  Kind extends ConfectKind = ConfectKind,
 > {
   readonly _tag: "Confect";
   readonly args: Args;
   readonly returns: Returns;
   readonly error?: Error;
+  readonly kind: Kind;
 }
 
 export interface AnyConfect extends Confect<
@@ -44,6 +75,8 @@ export interface AnyConvex extends Convex<DefaultFunctionArgs, any> {}
 
 export const FunctionProvenance = Data.taggedEnum<FunctionProvenance>();
 
+const Standard: Standard = { _tag: "Standard" };
+
 /**
  * Build a `Confect` provenance from lazy schema thunks. `args`, `returns`,
  * and `error` are exposed as sync lazy memoised getters (via {@link Lazy.defineProperty})
@@ -68,8 +101,8 @@ export const Confect = <
   args: () => Args,
   returns: () => Returns,
   error?: () => Error,
-): Confect<Args, Returns, Error> => {
-  const provenance = { _tag: "Confect" as const };
+): Confect<Args, Returns, Error, Standard> => {
+  const provenance = { _tag: "Confect" as const, kind: Standard };
 
   Lazy.defineProperty(provenance, "args", args);
   Lazy.defineProperty(provenance, "returns", returns);
@@ -77,7 +110,117 @@ export const Confect = <
     Lazy.defineProperty(provenance, "error", error);
   }
 
-  return provenance as Confect<Args, Returns, Error>;
+  return provenance as Confect<Args, Returns, Error, Standard>;
+};
+
+/**
+ * Any struct-shaped, context-free schema usable as a paginated query's user
+ * args. A structural bound rather than `Schema.Struct<Schema.Struct.Fields>`
+ * because `Schema.Struct` is not covariant in its fields parameter — concrete
+ * structs do not extend `Schema.Struct<Schema.Struct.Fields>`.
+ */
+// eslint-disable-next-line import/namespace -- oxlint's namespace resolution misses type-only exports, and `Schema` is an interface/namespace
+export interface AnyUserArgs extends Schema.Schema.AnyNoContext {
+  readonly fields: Schema.Struct.Fields;
+}
+
+/**
+ * The composed args schema of a paginated query: the user-declared fields
+ * plus the `paginationOpts` field managed by Convex's pagination protocol.
+ *
+ * The `extends infer ... extends` conditional lets TypeScript accept the
+ * composed struct where `Schema.Schema.AnyNoContext` is required even while
+ * `UserArgs` is an unresolved type parameter; for concrete user args it
+ * evaluates away entirely.
+ */
+export type PaginatedArgs<UserArgs extends AnyUserArgs> =
+  Schema.Struct<
+    UserArgs["fields"] & {
+      paginationOpts: typeof PaginationOptions.PaginationOptions;
+    }
+  > extends infer ComposedArgs extends Schema.Schema.AnyNoContext
+    ? ComposedArgs
+    : never;
+
+/**
+ * The composed returns schema of a paginated query: a `PaginationResult` of
+ * the item schema. Same deferred-conditional device as {@link PaginatedArgs}.
+ */
+export type PaginatedReturns<Item extends Schema.Schema.AnyNoContext> =
+  PaginationResult.PaginationResult<Item> extends infer ComposedReturns extends
+    Schema.Schema.AnyNoContext
+    ? ComposedReturns
+    : never;
+
+export interface ConfectPaginated<
+  UserArgs extends AnyUserArgs,
+  Item extends Schema.Schema.AnyNoContext,
+  Error extends Schema.Schema.AnyNoContext = never,
+> extends Confect<
+  PaginatedArgs<UserArgs>,
+  PaginatedReturns<Item>,
+  Error,
+  Paginated<UserArgs, Item>
+> {}
+
+export interface AnyConfectPaginated extends ConfectPaginated<
+  AnyUserArgs,
+  Schema.Schema.AnyNoContext,
+  Schema.Schema.AnyNoContext
+> {}
+
+/**
+ * Build the provenance of a paginated query from lazy schema thunks, with the
+ * same laziness contract as {@link Confect}. The user-facing schemas live on
+ * the `Paginated` kind (`kind.userArgs`, `kind.item`, `kind.page`) — the kind
+ * container is built eagerly (it is cheap) while the schemas inside it stay
+ * lazy. The composed Convex-facing `args`/`returns` are derived lazily from
+ * them: `args` spreads the user fields plus `paginationOpts`, and `returns`
+ * wraps the item in `PaginationResult`. Composition living here means the
+ * composed schemas can never drift from the stored user schemas.
+ */
+export const ConfectPaginated = <
+  UserArgs extends AnyUserArgs,
+  Item extends Schema.Schema.AnyNoContext,
+  Error extends Schema.Schema.AnyNoContext = never,
+>(
+  userArgs: () => UserArgs,
+  item: () => Item,
+  error?: () => Error,
+): ConfectPaginated<UserArgs, Item, Error> => {
+  const kind = { _tag: "Paginated" as const };
+  const paginatedKind = kind as Paginated<UserArgs, Item>;
+
+  Lazy.defineProperty(kind, "userArgs", userArgs);
+  Lazy.defineProperty(kind, "item", item);
+  Lazy.defineProperty(kind, "page", () =>
+    Schema.mutable(Schema.Array(paginatedKind.item)),
+  );
+
+  const provenance = { _tag: "Confect" as const, kind: paginatedKind };
+  const self = provenance as ConfectPaginated<UserArgs, Item, Error>;
+
+  Lazy.defineProperty(provenance, "args", () => {
+    const fields = paginatedKind.userArgs.fields;
+    if ("paginationOpts" in fields) {
+      throw new globalThis.Error(
+        "A paginated query's args schema must not declare `paginationOpts` — " +
+          "it is added automatically from the `PaginationOptions` schema",
+      );
+    }
+    return Schema.Struct({
+      ...fields,
+      paginationOpts: PaginationOptions.PaginationOptions,
+    });
+  });
+  Lazy.defineProperty(provenance, "returns", () =>
+    PaginationResult.PaginationResult(paginatedKind.item),
+  );
+  if (error !== undefined) {
+    Lazy.defineProperty(provenance, "error", error);
+  }
+
+  return self;
 };
 
 export const Convex = <_Args extends DefaultFunctionArgs, _Returns>() =>

package/src/FunctionSpec.ts

@@ -5,7 +5,7 @@ import type {
   RegisteredMutation,
   RegisteredQuery,
 } from "convex/server";
-import type { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import * as Predicate from "effect/Predicate";
 import * as FunctionProvenance from "./FunctionProvenance";
 import { validateConfectFunctionIdentifier } from "./Identifier";
@@ -244,11 +244,77 @@ const make =
     });
   };
 
+/**
+ * `Schema.Struct` fields that must not declare `paginationOpts`. Used to
+ * reject a user args schema that redeclares the field the paginated
+ * constructors add themselves; the check reports at the `args` thunk with an
+ * unsatisfiable type when violated.
+ */
+type ForbidPaginationOpts<UserArgs extends FunctionProvenance.AnyUserArgs> =
+  "paginationOpts" extends keyof UserArgs["fields"]
+    ? { readonly fields: { readonly paginationOpts: never } }
+    : unknown;
+
+const makePaginated =
+  <
+    RuntimeAndFunctionType_ extends
+      RuntimeAndFunctionType.RuntimeAndFunctionType,
+    FunctionVisibility_ extends FunctionVisibility,
+  >(
+    runtimeAndFunctionType: RuntimeAndFunctionType_,
+    functionVisibility: FunctionVisibility_,
+  ) =>
+  <
+    const Name_ extends string,
+    Item_ extends Schema.Schema.AnyNoContext,
+    UserArgs_ extends FunctionProvenance.AnyUserArgs = Schema.Struct<{}>,
+    Error_ extends Schema.Schema.AnyNoContext = never,
+  >({
+    name,
+    args,
+    item,
+    error,
+  }: {
+    name: Name_;
+    /** User-declared args, without `paginationOpts` — it is added automatically. */
+    args?: (() => UserArgs_) & ForbidPaginationOpts<UserArgs_>;
+    /** The page element schema. */
+    item: () => Item_;
+    error?: () => Error_;
+  }): FunctionSpec<
+    RuntimeAndFunctionType_,
+    FunctionVisibility_,
+    Name_,
+    FunctionProvenance.ConfectPaginated<UserArgs_, Item_, Error_>
+  > => {
+    validateConfectFunctionIdentifier(name);
+
+    return Object.assign(Object.create(Proto), {
+      runtimeAndFunctionType,
+      functionVisibility,
+      name,
+      functionProvenance: FunctionProvenance.ConfectPaginated(
+        // When `args` is omitted, `UserArgs_` is its `Schema.Struct<{}>` default.
+        args ?? ((() => Schema.Struct({})) as unknown as () => UserArgs_),
+        item,
+        error,
+      ),
+    });
+  };
+
 export const publicQuery = make(RuntimeAndFunctionType.ConvexQuery, "public");
 export const internalQuery = make(
   RuntimeAndFunctionType.ConvexQuery,
   "internal",
 );
+export const publicPaginatedQuery = makePaginated(
+  RuntimeAndFunctionType.ConvexQuery,
+  "public",
+);
+export const internalPaginatedQuery = makePaginated(
+  RuntimeAndFunctionType.ConvexQuery,
+  "internal",
+);
 export const publicMutation = make(
   RuntimeAndFunctionType.ConvexMutation,
   "public",

package/src/PaginationOptions.ts

@@ -0,0 +1,25 @@
+import * as Schema from "effect/Schema";
+
+/**
+ * Schema for the `paginationOpts` argument that every paginated query
+ * receives. Mirrors `paginationOptsValidator` from `convex/server`.
+ *
+ * Use this as the `paginationOpts` field of a paginated query's args schema.
+ * Beyond `numItems` and `cursor`, Convex's pagination protocol sends the
+ * optional fields (`endCursor`, `id`, `maximumRowsRead`, `maximumBytesRead`)
+ * with real requests — most notably `usePaginatedQuery` from `convex/react`
+ * always includes `id`, and includes `endCursor` when splitting pages.
+ * Declaring them is required for the generated Convex argument validator to
+ * accept those requests and for the fields to survive decoding and reach
+ * `paginate`.
+ */
+export const PaginationOptions = Schema.Struct({
+  numItems: Schema.Number,
+  cursor: Schema.Union(Schema.String, Schema.Null),
+  endCursor: Schema.optionalWith(Schema.Union(Schema.String, Schema.Null), {
+    exact: true,
+  }),
+  id: Schema.optionalWith(Schema.Number, { exact: true }),
+  maximumRowsRead: Schema.optionalWith(Schema.Number, { exact: true }),
+  maximumBytesRead: Schema.optionalWith(Schema.Number, { exact: true }),
+});

package/src/PaginationResult.ts

@@ -1,5 +1,8 @@
 import * as Schema from "effect/Schema";
 
+export type PaginationResult<Doc extends Schema.Schema.AnyNoContext> =
+  ReturnType<typeof PaginationResult<Doc>>;
+
 export const PaginationResult = <Doc extends Schema.Schema.AnyNoContext>(
   Doc: Doc,
 ) =>

package/src/Ref.ts

@@ -1,6 +1,8 @@
 import type {
   FunctionReference as ConvexFunctionReference,
   FunctionVisibility,
+  PaginationOptions,
+  PaginationResult,
 } from "convex/server";
 import { makeFunctionReference } from "convex/server";
 import type { Value } from "convex/values";
@@ -45,6 +47,17 @@ export interface AnyQuery extends Ref<
   any
 > {}
 
+export interface AnyPublicPaginatedQuery extends Ref<
+  RuntimeAndFunctionType.AnyQuery,
+  "public",
+  {
+    [key: string]: any;
+    paginationOpts: PaginationOptions;
+  },
+  PaginationResult<any>,
+  any
+> {}
+
 export interface AnyMutation extends Ref<
   RuntimeAndFunctionType.AnyMutation,
   FunctionVisibility,
@@ -239,7 +252,7 @@ export const decodeReturns = <Ref_ extends Any>(
 ): Effect.Effect<Returns<Ref_>, ParseResult.ParseError> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decode(confectFunctionProvenance.returns)(returns),
+      Schema.decodeUnknown(confectFunctionProvenance.returns)(returns),
     ),
     Match.tag("Convex", () => Effect.succeed(returns)),
     Match.exhaustive,
@@ -263,7 +276,7 @@ export const decodeArgsSync = <Ref_ extends Any>(
 ): Args<Ref_> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeSync(confectFunctionProvenance.args)(encodedArgs),
+      Schema.decodeUnknownSync(confectFunctionProvenance.args)(encodedArgs),
     ),
     Match.tag("Convex", () => encodedArgs),
     Match.exhaustive,
@@ -287,7 +300,9 @@ export const decodeReturnsSync = <Ref_ extends Any>(
 ): Returns<Ref_> =>
   Match.value(ref.functionSpec.functionProvenance).pipe(
     Match.tag("Confect", (confectFunctionProvenance) =>
-      Schema.decodeSync(confectFunctionProvenance.returns)(encodedReturns),
+      Schema.decodeUnknownSync(confectFunctionProvenance.returns)(
+        encodedReturns,
+      ),
     ),
     Match.tag("Convex", () => encodedReturns),
     Match.exhaustive,
@@ -314,7 +329,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;
       }
@@ -337,7 +352,7 @@ export const decodeError = <Ref_ extends Any>(
     Match.tag("Confect", (confectFunctionProvenance) =>
       "error" in confectFunctionProvenance
         ? Effect.map(
-            Schema.decode(confectFunctionProvenance.error)(encodedError),
+            Schema.decodeUnknown(confectFunctionProvenance.error)(encodedError),
             Option.some,
           )
         : Effect.succeed(Option.none<Error<Ref_>>()),
@@ -347,42 +362,96 @@ export const decodeError = <Ref_ extends Any>(
   );
 
 /**
- * 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.decodeSync(confectFunctionProvenance.error)(
-              encodedError,
-            ) as Error<Ref_>,
-          )
+        ? (Schema.decodeUnknownOption(confectFunctionProvenance.error)(
+            encodedError,
+          ) as Option.Option<Error<Ref_>>)
         : Option.none<Error<Ref_>>(),
     ),
     Match.tag("Convex", () => Option.none<Error<Ref_>>()),
     Match.exhaustive,
   );
 
-export const maybeDecodeErrorSync = <Ref_ extends Any>(
+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: () => Schema.Struct({ ... }), // optional; without paginationOpts\n" +
+      "    item: () => ItemSchema,\n" +
+      "  })",
+  );
+
+/**
+ * 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.decodeSync(confectFunctionProvenance.error)(error.data)
-            : error,
-        ),
-        Match.tag("Convex", () => error),
-        Match.exhaustive,
-      )
-    : error;
+  Match.value(ref.functionSpec.functionProvenance).pipe(
+    Match.tag("Confect", (confectFunctionProvenance) => {
+      if (confectFunctionProvenance.kind._tag !== "Paginated") {
+        throw missingPaginatedProvenanceError(ref);
+      }
+      return Schema.encodeUnknownSync(confectFunctionProvenance.kind.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(ref.functionSpec.functionProvenance).pipe(
+    Match.tag("Confect", (confectFunctionProvenance) => {
+      if (confectFunctionProvenance.kind._tag !== "Paginated") {
+        throw missingPaginatedProvenanceError(ref);
+      }
+      return Schema.decodeUnknownSync(confectFunctionProvenance.kind.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
@@ -411,7 +480,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;
             }
@@ -429,7 +498,7 @@ export const runWithCodec = <Ref_ extends Any, E = never>(
             confectFunctionProvenance.args,
           )(args);
           const encodedReturns = yield* invoke(encodedArgs);
-          return yield* Schema.decode(confectFunctionProvenance.returns)(
+          return yield* Schema.decodeUnknown(confectFunctionProvenance.returns)(
             encodedReturns,
           );
         }),

package/src/index.ts

@@ -5,6 +5,7 @@ export * as GroupPath from "./GroupPath";
 export * as GroupSpec from "./GroupSpec";
 export * as Identifier from "./Identifier";
 export * as Lazy from "./Lazy";
+export * as PaginationOptions from "./PaginationOptions";
 export * as PaginationResult from "./PaginationResult";
 export * as Ref from "./Ref";
 export * as Refs from "./Refs";