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

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>();
+});

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(),
+      ),
+    ),
+  });
+}