feat: ez.paginated() (#3245)

- featuring proprietary schema `ez.paginated()` to simplify common tasks
on paginating data
- composable and configurable
- supports both offset and cursor pagination
- along with `Client::hasMore()` helper 

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added offset-style paginated users list endpoint with role filtering
at /v2/users/list
* Introduced unified pagination support (offset and cursor), exported
ez.paginated, a public Pagination type, and Client.hasMore helper

* **Documentation**
* Added OpenAPI docs and README pagination usage and examples for the
new endpoint and pagination features

* **Tests**
* Added comprehensive tests for paginated inputs, outputs, limits, and
composability
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Version 27
 
+### v27.1.0
+
+- Introducing `ez.paginated()` helper for creating paginated endpoints:
+  - The configurable helper returns `input` and `output` schemas for your Endpoint;
+  - Use the `style` option to choose between `offset` and `cursor` pagination;
+  - The `itemsName` option configures the name of the property containing the items array;
+- The `Integration` generator now equips the `Client` with a static `hasMore()` method.
+
+```ts
+import { z } from "zod";
+import { ez, defaultEndpointsFactory } from "express-zod-api";
+
+const pagination = ez.paginated({
+  style: "offset", // or "cursor"
+  itemSchema: z.object({ id: z.number(), name: z.string() }),
+  itemsName: "users", // defines the output name of the items array
+  maxLimit: 100,
+  defaultLimit: 20,
+});
+
+const listUsers = defaultEndpointsFactory.build({
+  input: pagination.input,
+  output: pagination.output,
+  handler: async ({ input: { limit, offset } }) => {
+    const { users, total } = await db.getUsers(limit, offset);
+    return { users, total, limit, offset }; // or { users, nextCursor, limit } for cursor pagination
+  },
+});
+```
+
 ### v27.0.1
 
 - Removed debug-level comments from the declaration files in the distribution.

README.md

@@ -26,11 +26,12 @@ Start your API server with I/O schema validation and custom middlewares in minut
    7. [Transformations](#transformations)
    8. [Top level transformations and mapping](#top-level-transformations-and-mapping)
    9. [Dealing with dates](#dealing-with-dates)
-   10. [Cross-Origin Resource Sharing](#cross-origin-resource-sharing) (CORS)
-   11. [Enabling HTTPS](#enabling-https)
-   12. [Enabling compression](#enabling-compression)
-   13. [Customizing logger](#customizing-logger)
-   14. [Child logger](#child-logger)
+   10. [Pagination](#pagination)
+   11. [Cross-Origin Resource Sharing](#cross-origin-resource-sharing) (CORS)
+   12. [Enabling HTTPS](#enabling-https)
+   13. [Enabling compression](#enabling-compression)
+   14. [Customizing logger](#customizing-logger)
+   15. [Child logger](#child-logger)
 5. [Advanced features](#advanced-features)
    1. [Customizing input sources](#customizing-input-sources)
    2. [Headers as input source](#headers-as-input-source)
@@ -612,6 +613,34 @@ const updateUserEndpoint = defaultEndpointsFactory.build({
 });
 ```
 
+## Pagination
+
+Consider using `ez.paginated()` to get reusable `input` and `output` schemas for offset or cursor-based pagination.
+Attach schemas to your endpoint and compose with other params (e.g. `.and(z.object({ ... }))`).
+To check if more pages are available, use [Client::hasMore()](#generating-a-frontend-client).
+
+```ts
+import { z } from "zod";
+import { ez, defaultEndpointsFactory } from "express-zod-api";
+
+const pagination = ez.paginated({
+  style: "offset", // or "cursor"
+  itemSchema: z.object({ id: z.number(), name: z.string() }),
+  itemsName: "users", // defines the output name of the items array
+  maxLimit: 100,
+  defaultLimit: 20,
+});
+
+const listUsers = defaultEndpointsFactory.build({
+  input: pagination.input,
+  output: pagination.output,
+  handler: async ({ input: { limit, offset } }) => {
+    const { users, total } = await db.getUsers(limit, offset);
+    return { users, total, limit, offset }; // or { users, nextCursor, limit } for cursor pagination
+  },
+});
+```
+
 ## Cross-Origin Resource Sharing
 
 You can enable your API for other domains using the corresponding configuration option `cors`. The value is required to

example/__snapshots__/index.spec.ts.snap

@@ -173,6 +173,51 @@ exports[`Example > Positive > Should respond with array (legacy API ResultHandle
 ]
 `;
 
+exports[`Example > Positive > Should respond with paginated list (ez.paginated) 1`] = `
+{
+  "data": {
+    "limit": 20,
+    "offset": 0,
+    "total": 8,
+    "users": [
+      {
+        "name": "Maria Merian",
+        "role": "manager",
+      },
+      {
+        "name": "Mary Anning",
+        "role": "operator",
+      },
+      {
+        "name": "Marie Skłodowska Curie",
+        "role": "admin",
+      },
+      {
+        "name": "Henrietta Leavitt",
+        "role": "manager",
+      },
+      {
+        "name": "Lise Meitner",
+        "role": "operator",
+      },
+      {
+        "name": "Alice Ball",
+        "role": "admin",
+      },
+      {
+        "name": "Gerty Cori",
+        "role": "manager",
+      },
+      {
+        "name": "Helen Taussig",
+        "role": "operator",
+      },
+    ],
+  },
+  "status": "success",
+}
+`;
+
 exports[`Example > Positive > Should send an image with a correct header 1`] = `"f39beeff92379dc935586d726211c2620be6f879"`;
 
 exports[`Example > Positive > Should serve static files 1`] = `"f39beeff92379dc935586d726211c2620be6f879"`;

example/config.ts

@@ -6,7 +6,8 @@ import qs from "qs";
 
 export const config = createConfig({
   http: { listen: givePort("example") },
-  queryParser: (query) => qs.parse(query, { comma: true }), // affects listUsersEndpoint
+  // required for listUsersPaginatedEndpoint and listUsersEndpoint (legacy API demo)
+  queryParser: (query) => qs.parse(query, { comma: true }),
   upload: {
     limits: { fileSize: 51200 },
     limitError: createHttpError(413, "The file is too large"), // affects uploadAvatarEndpoint

example/endpoints/list-users-paginated.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { defaultEndpointsFactory, ez } from "express-zod-api";
+
+const roleSchema = z.enum(["manager", "operator", "admin"]);
+
+const userSchema = z.object({
+  name: z.string(),
+  role: roleSchema,
+});
+
+const paginatedUsers = ez.paginated({
+  style: "offset",
+  itemSchema: userSchema,
+  itemsName: "users",
+  maxLimit: 100,
+  defaultLimit: 20,
+});
+
+const users: z.output<typeof userSchema>[] = [
+  { name: "Maria Merian", role: "manager" },
+  { name: "Mary Anning", role: "operator" },
+  { name: "Marie Skłodowska Curie", role: "admin" },
+  { name: "Henrietta Leavitt", role: "manager" },
+  { name: "Lise Meitner", role: "operator" },
+  { name: "Alice Ball", role: "admin" },
+  { name: "Gerty Cori", role: "manager" },
+  { name: "Helen Taussig", role: "operator" },
+];
+
+/**
+ * Lists users with offset pagination and optional role filter.
+ * Uses ez.paginated() for input params (limit, offset) and output shape (users, total, limit, offset).
+ */
+export const listUsersPaginatedEndpoint = defaultEndpointsFactory.build({
+  tag: "users",
+  shortDescription: "Lists users with pagination.",
+  description:
+    "Returns a page of users. Optionally filter by roles. Uses offset-based pagination (limit and offset).",
+  input: paginatedUsers.input.and(
+    z.object({
+      roles: z
+        .array(roleSchema)
+        .optional()
+        .describe("Filter by roles; omit for all"),
+    }),
+  ),
+  output: paginatedUsers.output,
+  handler: async ({ input: { limit, offset, roles } }) => {
+    const filtered = roles
+      ? users.filter(({ role }) => roles.includes(role))
+      : users;
+    const total = filtered.length;
+    const page = filtered.slice(offset, offset + limit);
+    return { users: page, total, limit, offset };
+  },
+});

example/example.client.ts

@@ -435,6 +435,78 @@ interface PostV1FormsFeedbackNegativeResponseVariants {
   400: PostV1FormsFeedbackNegativeVariant1;
 }
 
+/** get /v2/users/list */
+type GetV2UsersListInput = {
+  /** Page size (number of users per page) */
+  limit?: number | undefined;
+  /** Number of users to skip */
+  offset?: number | undefined;
+  /** Filter by roles; omit for all */
+  roles?: ("manager" | "operator" | "admin")[] | undefined;
+};
+
+/** get /v2/users/list */
+type GetV2UsersListPositiveVariant1 = {
+  status: "success";
+  data: {
+    /** Page of users */
+    users: {
+      name: string;
+      role: "manager" | "operator" | "admin";
+    }[];
+    /** Total number of users */
+    total: number;
+    /** Page size used */
+    limit: number;
+    /** Offset used */
+    offset: number;
+  };
+};
+
+/** get /v2/users/list */
+interface GetV2UsersListPositiveResponseVariants {
+  200: GetV2UsersListPositiveVariant1;
+}
+
+/** get /v2/users/list */
+type GetV2UsersListNegativeVariant1 = {
+  status: "error";
+  error: {
+    message: string;
+  };
+};
+
+/** get /v2/users/list */
+interface GetV2UsersListNegativeResponseVariants {
+  400: GetV2UsersListNegativeVariant1;
+}
+
+/** head /v2/users/list */
+type HeadV2UsersListInput = {
+  /** Page size (number of users per page) */
+  limit?: number | undefined;
+  /** Number of users to skip */
+  offset?: number | undefined;
+  /** Filter by roles; omit for all */
+  roles?: ("manager" | "operator" | "admin")[] | undefined;
+};
+
+/** head /v2/users/list */
+type HeadV2UsersListPositiveVariant1 = undefined;
+
+/** head /v2/users/list */
+interface HeadV2UsersListPositiveResponseVariants {
+  200: HeadV2UsersListPositiveVariant1;
+}
+
+/** head /v2/users/list */
+type HeadV2UsersListNegativeVariant1 = undefined;
+
+/** head /v2/users/list */
+interface HeadV2UsersListNegativeResponseVariants {
+  400: HeadV2UsersListNegativeVariant1;
+}
+
 export type Path =
   | "/v1/user/retrieve"
   | "/v1/user/:id/remove"
@@ -446,7 +518,8 @@ export type Path =
   | "/v1/avatar/upload"
   | "/v1/avatar/raw"
   | "/v1/events/stream"
-  | "/v1/forms/feedback";
+  | "/v1/forms/feedback"
+  | "/v2/users/list";
 
 export type Method = "get" | "post" | "put" | "delete" | "patch" | "head";
 
@@ -469,6 +542,8 @@ export interface Input {
   "get /v1/events/stream": GetV1EventsStreamInput;
   "head /v1/events/stream": HeadV1EventsStreamInput;
   "post /v1/forms/feedback": PostV1FormsFeedbackInput;
+  "get /v2/users/list": GetV2UsersListInput;
+  "head /v2/users/list": HeadV2UsersListInput;
 }
 
 export interface PositiveResponse {
@@ -490,6 +565,8 @@ export interface PositiveResponse {
   "get /v1/events/stream": SomeOf<GetV1EventsStreamPositiveResponseVariants>;
   "head /v1/events/stream": SomeOf<HeadV1EventsStreamPositiveResponseVariants>;
   "post /v1/forms/feedback": SomeOf<PostV1FormsFeedbackPositiveResponseVariants>;
+  "get /v2/users/list": SomeOf<GetV2UsersListPositiveResponseVariants>;
+  "head /v2/users/list": SomeOf<HeadV2UsersListPositiveResponseVariants>;
 }
 
 export interface NegativeResponse {
@@ -511,6 +588,8 @@ export interface NegativeResponse {
   "get /v1/events/stream": SomeOf<GetV1EventsStreamNegativeResponseVariants>;
   "head /v1/events/stream": SomeOf<HeadV1EventsStreamNegativeResponseVariants>;
   "post /v1/forms/feedback": SomeOf<PostV1FormsFeedbackNegativeResponseVariants>;
+  "get /v2/users/list": SomeOf<GetV2UsersListNegativeResponseVariants>;
+  "head /v2/users/list": SomeOf<HeadV2UsersListNegativeResponseVariants>;
 }
 
 export interface EncodedResponse {
@@ -548,6 +627,10 @@ export interface EncodedResponse {
     HeadV1EventsStreamNegativeResponseVariants;
   "post /v1/forms/feedback": PostV1FormsFeedbackPositiveResponseVariants &
     PostV1FormsFeedbackNegativeResponseVariants;
+  "get /v2/users/list": GetV2UsersListPositiveResponseVariants &
+    GetV2UsersListNegativeResponseVariants;
+  "head /v2/users/list": HeadV2UsersListPositiveResponseVariants &
+    HeadV2UsersListNegativeResponseVariants;
 }
 
 export interface Response {
@@ -601,6 +684,12 @@ export interface Response {
   "post /v1/forms/feedback":
     | PositiveResponse["post /v1/forms/feedback"]
     | NegativeResponse["post /v1/forms/feedback"];
+  "get /v2/users/list":
+    | PositiveResponse["get /v2/users/list"]
+    | NegativeResponse["get /v2/users/list"];
+  "head /v2/users/list":
+    | PositiveResponse["head /v2/users/list"]
+    | NegativeResponse["head /v2/users/list"];
 }
 
 export type Request = keyof Input;
@@ -622,6 +711,8 @@ export const endpointTags = {
   "get /v1/events/stream": ["subscriptions"],
   "head /v1/events/stream": ["subscriptions"],
   "post /v1/forms/feedback": ["forms"],
+  "get /v2/users/list": ["users"],
+  "head /v2/users/list": ["users"],
 };
 
 const parseRequest = (request: string) =>
@@ -645,6 +736,16 @@ export type Implementation<T = unknown> = (
   ctx?: T,
 ) => Promise<any>;
 
+type Pagination =
+  | {
+      nextCursor: string | null;
+    }
+  | {
+      total: number;
+      limit: number;
+      offset: number;
+    };
+
 const defaultImplementation: Implementation = async (method, path, params) => {
   const hasBody = !["get", "head", "delete"].includes(method);
   const searchParams = hasBody ? "" : `?${new URLSearchParams(params)}`;
@@ -674,6 +775,10 @@ export class Client<T> {
     const [method, path] = parseRequest(request);
     return this.implementation(method, ...substitute(path, params), ctx);
   }
+  public static hasMore(response: Pagination): boolean {
+    if ("nextCursor" in response) return response.nextCursor !== null;
+    return response.offset + response.limit < response.total;
+  }
 }
 
 export class Subscription<