add pagination result validation helper (#42729)

with returns validators being more important for components & static codegen, it's often necessary to generate the type for pagination results, and as we may change this type over time, it's important that we offer a safe version of it GitOrigin-RevId: b3d4bc3b8d7f60fc2a8ae4b887203f32198aff9c

Author: ianmacartney

npm-packages/convex/src/server/pagination.test.ts

@@ -1,7 +1,12 @@
 import { assert } from "../test/type_testing.js";
 import { test } from "vitest";
-import { PaginationOptions, paginationOptsValidator } from "./pagination.js";
-import { Infer } from "../values/validator.js";
+import {
+ PaginationOptions,
+ PaginationResult,
+ paginationOptsValidator,
+ paginationResultValidator,
+} from "./pagination.js";
+import { Infer, v } from "../values/validator.js";
 
 test("paginationOptsValidator matches the paginationOpts type", () => {
  type validatorType = Infer<typeof paginationOptsValidator>;
@@ -11,3 +16,34 @@ test("paginationOptsValidator matches the paginationOpts type", () => {
  Required<validatorType> extends Required<PaginationOptions> ? true : false
  >();
 });
+
+test("paginationResultValidator with string items", () => {
+ const _validator = paginationResultValidator(v.string());
+ type validatorType = Infer<typeof _validator>;
+ type expectedType = PaginationResult<string>;
+
+ // Check that the inferred type matches PaginationResult<string>
+ assert<validatorType extends expectedType ? true : false>();
+ assert<expectedType extends validatorType ? true : false>();
+});
+
+test("paginationResultValidator with object items", () => {
+ const itemValidator = v.object({
+ _id: v.id("users"),
+ _creationTime: v.number(),
+ name: v.string(),
+ email: v.optional(v.string()),
+ });
+ const _validator = paginationResultValidator(itemValidator);
+ type validatorType = Infer<typeof _validator>;
+ type itemType = Infer<typeof itemValidator>;
+ type expectedType = PaginationResult<itemType>;
+
+ // Check that the inferred type matches PaginationResult with the correct item type
+ assert<validatorType extends expectedType ? true : false>();
+ assert<expectedType extends validatorType ? true : false>();
+
+ // Verify the page array has the correct item type
+ type pageType = validatorType["page"];
+ assert<pageType extends itemType[] ? true : false>();
+});

npm-packages/convex/src/server/pagination.ts

@@ -1,4 +1,6 @@
 import { v } from "../values/validator.js";
+import type { Validator } from "../values/validators.js";
+import type { Value } from "../values/value.js";
 
 /**
  * An opaque identifier used for paginating a database query.
@@ -136,3 +138,41 @@ export const paginationOptsValidator = v.object({
  maximumRowsRead: v.optional(v.number()),
  maximumBytesRead: v.optional(v.number()),
 });
+
+/**
+ * A {@link values.Validator} factory for {@link PaginationResult}.
+ *
+ * Create a validator for the result of calling {@link OrderedQuery.paginate}
+ * with a given item validator.
+ *
+ * For example:
+ * ```ts
+ * const paginationResultValidator = paginationResultValidator(v.object({
+ * _id: v.id("users"),
+ * _creationTime: v.number(),
+ * name: v.string(),
+ * }));
+ * ```
+ *
+ * @param itemValidator - A validator for the items in the page
+ * @returns A validator for the pagination result
+ *
+ * @public
+ */
+export function paginationResultValidator<
+ T extends Validator<Value, "required", string>,
+>(itemValidator: T) {
+ return v.object({
+ page: v.array(itemValidator),
+ continueCursor: v.string(),
+ isDone: v.boolean(),
+ splitCursor: v.optional(v.union(v.string(), v.null())),
+ pageStatus: v.optional(
+ v.union(
+ v.literal("SplitRecommended"),
+ v.literal("SplitRequired"),
+ v.null(),
+ ),
+ ),
+ });
+}