zod-paginate 1.0.0

package/README.md

@@ -0,0 +1,427 @@
+# zod-paginate
+
+A small utility to **parse and validate pagination + select + sort + filters** from querystring-like objects using **Zod v4**, and to generate a **response validator** that automatically projects your `dataSchema` based on the requested `select`.
+
+It is designed for Node.js HTTP stacks where query parameters arrive as strings (or string arrays). It outputs a **typed, normalized** structure you can map to your ORM/query builder.
+
+- Supports **LIMIT/OFFSET pagination** (`limit` + `page`).
+- Supports **CURSOR pagination** with cursor coercion based on `cursorProperty` (number / string / ISO date string).
+- Supports **field projection** using `select` (CSV), including wildcard expansion (`*`) when enabled.
+- Supports **sorting** with an allowlist of sortable fields.
+- Supports a **filter DSL** with `$` operators and **nested AND/OR grouping**.
+- Provides a **response validator** (`validatorSchema`) to validate API responses against the projected schema.
+
+> This library does **not** bind DB queries automatically.
+> It gives you a safe parsed structure; you decide how to map it to your data layer.
+
+## Installation
+
+```bash
+npm i zod-paginate
+# or
+pnpm add zod-paginate
+# or
+yarn add zod-paginate
+```
+
+## Quick start
+
+```ts
+import { z } from "zod";
+import { paginate } from "zod-paginate";
+
+const ModelSchema = z.object({
+  id: z.number(),
+  status: z.string(),
+  createdAt: z.date(),
+  meta: z.object({
+    score: z.number(),
+  }),
+});
+
+const { queryParamsSchema, validatorSchema } = paginate({
+  paginationType: "LIMIT_OFFSET",
+  dataSchema: ModelSchema,
+
+  selectable: ["id", "status", "createdAt", "meta.score"],
+  sortable: ["createdAt", "id"],
+  filterable: {
+    status: { type: "string", ops: ["$eq", "$ilike"] },
+    createdAt: { type: "date", ops: ["$btw", "$null", "$eq", "$gt", "$lte"] },
+    id: { type: "number", ops: ["$gt", "$in", "$eq"] },
+    "meta.score": { type: "number", ops: ["$gte", "$lte"] },
+  },
+
+  defaultSortBy: [{ property: "createdAt", direction: "DESC" }],
+  defaultLimit: 20,
+  maxLimit: 100,
+  defaultSelect: ["*"],
+});
+
+// Example querystring-like input
+const parsed = queryParamsSchema.parse({
+  limit: "10",
+  page: "2",
+  sortBy: "createdAt:DESC",
+  select: "id,status",
+  "filter.status": "$ilike:act",
+});
+
+console.log(parsed.pagination);
+
+// Build the response validator from the request context
+const responseSchema = validatorSchema(parsed);
+```
+
+## API
+
+### `paginate(config)`
+
+Returns:
+
+- `queryParamsSchema`: Zod schema to parse query objects (strings / string arrays).
+- `validatorSchema(parsed?)`: function returning a Zod schema to validate the response payload.
+
+```ts
+export function paginate<TSchema extends DataSchema>(
+  config: QueryConfigFromSchema<TSchema>,
+): {
+  queryParamsSchema: z.ZodType<PaginationQueryParams<TSchema>>;
+  validatorSchema: (parsed?: PaginationQueryParams<TSchema>) => z.ZodType;
+}
+```
+
+## Configuration (`paginate({...})`)
+
+| Option | Type | Description |
+|---|---:|---|
+| `paginationType` | `"LIMIT_OFFSET"` \| `"CURSOR"` | Select pagination mode. |
+| `dataSchema` | `z.ZodObject` | Zod schema representing one **data item** returned by your API (used for projection + cursor inference). |
+| `selectable?` | `string[]` (typed paths) | Allowlist of selectable fields (dot paths supported). Enables `select`. |
+| `sortable?` | `string[]` (typed paths) | Allowlist of sortable fields. Enables `sortBy`. |
+| `filterable?` | object | Allowlist of filterable fields and allowed operators + field type. |
+| `defaultSortBy?` | `{ property, direction }[]` | Default sort if `sortBy` missing/empty. |
+| `defaultLimit?` | `number` | Default limit if `limit` missing. |
+| `maxLimit?` | `number` | Rejects `limit` values above this. |
+| `defaultSelect?` | `("*" \| field)[]` | Default select if `select` missing. `["*"]` expands to `selectable`. |
+| `cursorProperty` | (CURSOR only) typed path | The field used for cursor paging. Cursor type is inferred from `dataSchema` at that path and the query input cursor is coerced accordingly. |
+
+## Query input shape
+
+`queryParamsSchema` accepts any record-like input:
+
+```ts
+Record<string, unknown>
+```
+
+Typical querystring parsers produce values like:
+
+- `"10"` (string)
+- `["a", "b"]` (repeated query params)
+- everything else is ignored / treated as undefined
+
+## Query parameters
+
+### `limit`
+
+- Input: string numeric (e.g. `"10"`)
+- Output: number
+- Rules
+  - Must be a numeric string
+  - Must be `<= maxLimit` if configured
+  - Falls back to `defaultLimit` when missing
+
+### `page` (LIMIT_OFFSET only)
+
+- Input: string numeric (e.g. `"2"`)
+- Output: number
+- Rules
+  - Only valid when `paginationType: "LIMIT_OFFSET"`
+  - Forbidden in CURSOR mode
+
+### `cursor` (CURSOR only)
+
+- Input: string (querystring input is always string)
+- Output: `number | string` (coerced)
+- Rules
+  - Only valid when `paginationType: "CURSOR"`
+  - Forbidden in LIMIT_OFFSET mode
+  - If provided, it is coerced based on the Zod type of `cursorProperty` in `dataSchema`:
+    - `z.number()` field → `"123"` becomes `123` (integer-only)
+    - `z.string()` field → `"abc"` stays `"abc"`
+    - `z.date()` field → must be ISO date or ISO datetime, stays a string (`"2022-01-01"` or `"2022-01-01T12:00:00Z"`)
+
+### `sortBy`
+
+- Input: string or string[]
+- Output: `[{ property, direction }]`
+- Rules
+  - Requires `sortable` in config
+  - Format: `field:ASC` or `field:DESC`
+  - Empty items are ignored
+  - If missing (or becomes empty after cleanup), falls back to `defaultSortBy` if configured
+  - Properties are matched against the allowlist (unknown fields are dropped)
+
+### `select`
+
+- Input: CSV string
+- Output: string[] (typed paths)
+- Rules
+  - Requires `selectable` in config
+  - CSV is split by `,`, trimmed, empty items removed
+  - `*` expands to the configured `selectable` allowlist
+  - If missing, falls back to `defaultSelect` if configured
+  - `select=` (empty) is rejected
+  - Unknown fields are rejected at parse-time (strict allowlist)
+
+## Filters
+
+Filters are passed as query keys with this pattern:
+
+```txt
+filter.<field>=<dsl>
+```
+
+Where `<field>` is a dot-path field (example: `meta.score`).
+
+You configure which fields are filterable and which operators are allowed via `filterable`.
+
+### Operators
+
+| Operator | Meaning | Value format |
+|---|---|---|
+| `$eq` | equals | number / string / ISO date depending on field type |
+| `$null` | is null | no value |
+| `$in` | in list | `a,b,c` (comma-separated) |
+| `$contains` | contains values | `a,b,c` (comma-separated) |
+| `$gt` `$gte` `$lt` `$lte` | comparisons | number or ISO date |
+| `$btw` | between | `a,b` where both are numbers OR both are ISO dates |
+| `$ilike` | case-insensitive contains (string) | string |
+| `$sw` | starts with (string) | string |
+
+Runtime validation enforces:
+
+1) field allowlist (`filterable`)
+2) operator allowlist per field (`ops`)
+3) value type compatibility (number vs date vs string)
+
+### Default operator: `$eq`
+
+If the filter does **not** start with `$`, it is interpreted as `$eq:<value>`.
+
+### Negation: `$not`
+
+Prefix any operator with `$not:` to negate the condition.
+
+Examples:
+
+```txt
+filter.createdAt=$not:$null
+filter.status=$not:$eq:active
+```
+
+### Multiple conditions for the same field
+
+Use repeated query params:
+
+```txt
+filter.id=$gt:10&filter.id=$lt:100
+```
+
+Or in object form:
+
+```ts
+{
+  "filter.id": ["$gt:10", "$lt:100"]
+}
+```
+
+## Groups
+
+Groups let you build nested AND/OR boolean logic.
+
+There are two layers:
+
+1) Combine multiple conditions inside the same group
+2) Build a group tree (attach groups as children of other groups)
+
+### Put a condition into a group: `$g:<id>`
+
+Prefix any filter DSL with:
+
+```txt
+$g:<groupId>:
+```
+
+### Combine conditions inside a group: `$and` / `$or`
+
+Within a group, the **first** condition cannot have `$and`/`$or`. All following conditions may be prefixed with `$and` or `$or`.
+
+### Group tree definitions: `group.<id>.*`
+
+To nest groups, define these query keys:
+
+- `group.<id>.parent` — parent group id (integer string)
+- `group.<id>.join` — how this group is joined to its parent (`$and` or `$or`)
+- `group.<id>.op` — default join used when combining this group's children (optional)
+
+Rules:
+
+- Root group id is always `"0"`.
+- `group.0.parent` and `group.0.join` are forbidden.
+- Cycles are rejected.
+- Child groups are resolved in numeric order (deterministic).
+
+## Validating responses with `validatorSchema()`
+
+`validatorSchema(parsed)` returns a Zod schema you can use to validate your API response.
+
+What it does:
+
+- Uses the effective `select` (explicit `select`, else `defaultSelect`, else full schema) to project the item schema.
+- Validates cursor type (CURSOR mode) based on `cursorProperty`.
+- Enforces mode-specific pagination metadata shape.
+
+### What `validatorSchema(parsed)` expects
+
+**LIMIT/OFFSET mode**:
+
+```ts
+{
+  data: Array<ProjectedItem>,
+  pagination: {
+    itemsPerPage: number,
+    totalItems: number,
+    currentPage: number,
+    totalPages: number,
+    sortBy?: Array<{ property: string, direction: "ASC" | "DESC" }>,
+    filter?: WhereNode
+  }
+}
+```
+
+**CURSOR mode**:
+
+```ts
+{
+  data: Array<ProjectedItem>,
+  pagination: {
+    itemsPerPage: number,
+    cursor: number | string | Date,
+    sortBy?: Array<{ property: string, direction: "ASC" | "DESC" }>,
+    filter?: WhereNode
+  }
+}
+```
+
+Notes:
+
+- `ProjectedItem` is computed from `dataSchema` + the effective `select`.
+- If `cursorProperty` points to a `z.number()` field, `pagination.cursor` must be a number.
+- If `cursorProperty` points to a `z.string()` field, `pagination.cursor` must be a string.
+- If `cursorProperty` points to a `z.date()` field, this library accepts an ISO string or a `Date` (depending on implementation).
+
+You can call `validatorSchema()` without arguments to build a validator based on defaults (`defaultSelect`, `cursorProperty`, etc.).
+
+## End-to-end examples
+
+### Example 1 — LIMIT/OFFSET
+
+HTTP query:
+
+```txt
+?limit=20&page=1&select=id,status,createdAt&sortBy=createdAt:DESC&filter.status=$ilike:act&filter.id=$gt:10
+```
+
+Parsing:
+
+```ts
+const parsed = queryParamsSchema.parse({
+  limit: "20",
+  page: "1",
+  select: "id,status,createdAt",
+  sortBy: "createdAt:DESC",
+  "filter.status": "$ilike:act",
+  "filter.id": "$gt:10",
+});
+
+// parsed.pagination
+// {
+//   type: "LIMIT_OFFSET",
+//   limit: 20,
+//   page: 1,
+//   select: ["id", "status", "createdAt"],
+//   sortBy: [{ property: "createdAt", direction: "DESC" }],
+//   filters: { type: "and", items: [...] } // WhereNode AST
+// }
+```
+
+### Example 2 — CURSOR + coercion
+
+Config:
+
+```ts
+const { queryParamsSchema } = paginate({
+  paginationType: "CURSOR",
+  dataSchema: ModelSchema,
+  cursorProperty: "id", // id is z.number()
+  selectable: ["id", "status", "createdAt"],
+  defaultSelect: ["id", "createdAt"],
+});
+```
+
+Parsing:
+
+```ts
+const parsed = queryParamsSchema.parse({ cursor: "123", limit: "10" });
+
+// parsed.pagination
+// {
+//   type: "CURSOR",
+//   limit: 10,
+//   cursor: 123,            // <- coerced from "123" because cursorProperty is a number
+//   cursorProperty: "id",
+//   select: ["id", "createdAt"],
+//   filters: { type: "and", items: [] }
+// }
+```
+
+### Example 3 — groups
+
+Goal: `(status == active OR status == postponed) AND (id > 10)`
+
+```ts
+const parsed = queryParamsSchema.parse({
+  "filter.status": ["$g:1:$eq:active", "$g:1:$or:$eq:postponed"],
+  "filter.id": "$g:2:$gt:10",
+
+  "group.1.parent": "0",
+  "group.2.parent": "0",
+  "group.2.join": "$and",
+});
+
+// parsed.pagination.filters
+// {
+//   type: "and",
+//   items: [
+//     { type: "or", items: [ ...status filters... ] },
+//     { type: "filter", field: "id", condition: { op: "$gt", value: 10, ... } }
+//   ]
+// }
+```
+
+### Example 4 — validating your response
+
+```ts
+const parsed = queryParamsSchema.parse({ select: "id,status", limit: "10", page: "1" });
+const responseSchema = validatorSchema(parsed);
+
+// responseSchema expects:
+// - data items shaped like { id: number, status: string }
+// - pagination metadata for LIMIT/OFFSET
+
+responseSchema.parse({
+  data: [{ id: 1, status: "active" }],
+  pagination: { itemsPerPage: 10, totalItems: 1, currentPage: 1, totalPages: 1 },
+});
+```

package/dist/main.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+/**
+ * Primitive types that we consider as leaves in the Path type. Arrays are also considered leaves, since we don't want to generate paths like "arrayField.0.someProp".
+ */
+type Primitive = string | number | boolean | bigint | symbol | null | undefined | Date;
+/**
+ * Join two path segments K and P with a dot, if both are strings. Otherwise, return never.
+ */
+type Join<K, P> = K extends string ? (P extends string ? `${K}.${P}` : never) : never;
+/**
+ * Generate dot notation paths for a given type T, up to a certain depth D (default 5).
+ * For example, for { a: { b: string }, c: number }, we would generate "a", "a.b", and "c". We stop recursion at depth 0 to prevent infinite types.
+ */
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/**
+ * Generate dot notation paths for a given type T. For example, for { a: { b: string }, c: number }, we would generate "a", "a.b", and "c".
+ */
+type Path<T, D extends number = 5> = D extends 0 ? never : T extends Primitive ? never : T extends readonly unknown[] ? never : {
+    [K in Extract<keyof T, string>]: T[K] extends Primitive | readonly unknown[] ? K : K | Join<K, Path<T[K], Prev[D]>>;
+}[Extract<keyof T, string>];
+/**
+ * Given a type T and a dot notation path P, resolve the type at that path.
+ * For example, for T = { a: { b: string }, c: number } and P = "a.b", we would get string.
+ */
+type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+interface LimitOffsetPaginationConfig {
+    paginationType: 'LIMIT_OFFSET';
+}
+interface CursorPaginationConfig<T> {
+    paginationType: 'CURSOR';
+    cursorProperty: Path<T>;
+}
+declare const SortDirectionSchema: z.ZodEnum<{
+    ASC: "ASC";
+    DESC: "DESC";
+}>;
+type SortDirection = z.infer<typeof SortDirectionSchema>;
+/**
+ * Supported operators.
+ * $eq: equality (for strings, numbers, dates)
+ * $null: checks for null (ignores the value)
+ * $in: checks if the field value is in the provided array (for strings, numbers, dates)
+ * $gt, $gte, $lt, $lte: comparison operators (for numbers and dates)
+ * $btw: checks if the field value is between two values (for numbers and dates)
+ * $ilike: case-insensitive substring match (for strings)
+ * $sw: case-insensitive starts-with match (for strings)
+ * $contains: checks if the field value contains the provided value (for strings)
+ */
+declare const OperatorSchema: z.ZodEnum<{
+    $eq: "$eq";
+    $null: "$null";
+    $in: "$in";
+    $gt: "$gt";
+    $gte: "$gte";
+    $lt: "$lt";
+    $lte: "$lte";
+    $btw: "$btw";
+    $ilike: "$ilike";
+    $sw: "$sw";
+    $contains: "$contains";
+}>;
+type Operator = z.infer<typeof OperatorSchema>;
+type FieldType = 'string' | 'number' | 'date' | 'any';
+type FieldTypeFromValue<V> = V extends Date ? 'date' : V extends number ? 'number' : V extends string ? 'string' : 'any';
+type CommonOps = '$eq' | '$null' | '$in' | '$contains';
+type StringOnlyOps = '$ilike' | '$sw';
+type ComparableOps = '$gt' | '$gte' | '$lt' | '$lte' | '$btw';
+type OpsForFieldType<TKind extends FieldType> = TKind extends 'string' ? CommonOps | StringOnlyOps : TKind extends 'number' ? CommonOps | ComparableOps : TKind extends 'date' ? CommonOps | ComparableOps : Operator;
+declare const ConditionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodLiteral<"$null">;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodLiteral<"$eq">;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+    value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodEnum<{
+        $ilike: "$ilike";
+        $sw: "$sw";
+    }>;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodEnum<{
+        $in: "$in";
+        $contains: "$contains";
+    }>;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+    value: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodEnum<{
+        $gt: "$gt";
+        $gte: "$gte";
+        $lt: "$lt";
+        $lte: "$lte";
+    }>;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+    value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$strip>, z.ZodObject<{
+    group: z.ZodString;
+    combinator: z.ZodOptional<z.ZodEnum<{
+        $and: "$and";
+        $or: "$or";
+    }>>;
+    op: z.ZodLiteral<"$btw">;
+    not: z.ZodOptional<z.ZodLiteral<true>>;
+    value: z.ZodTuple<[z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>], null>;
+}, z.core.$strip>], "op">;
+type Condition = z.infer<typeof ConditionSchema>;
+interface WhereFilter {
+    type: 'filter';
+    field: string;
+    condition: Condition;
+}
+interface WhereAnd {
+    type: 'and';
+    items: WhereNode[];
+}
+interface WhereOr {
+    type: 'or';
+    items: WhereNode[];
+}
+type WhereNode = WhereFilter | WhereAnd | WhereOr;
+export type DataSchema = z.ZodObject<z.ZodRawShape>;
+export type InferData<TSchema extends DataSchema> = z.infer<TSchema>;
+export type AllowedPath<TSchema extends DataSchema> = Path<InferData<TSchema>>;
+interface FilterableFieldConfig<TKind extends FieldType> {
+    type: TKind;
+    ops: readonly OpsForFieldType<TKind>[];
+}
+export interface CommonQueryConfigFromSchema<TSchema extends DataSchema> {
+    dataSchema: TSchema;
+    selectable?: readonly AllowedPath<TSchema>[];
+    sortable?: readonly AllowedPath<TSchema>[];
+    filterable?: Partial<{
+        [P in AllowedPath<TSchema>]: FilterableFieldConfig<FieldTypeFromValue<PathValue<InferData<TSchema>, P>>>;
+    }>;
+    defaultSortBy?: readonly {
+        property: AllowedPath<TSchema>;
+        direction: SortDirection;
+    }[];
+    defaultLimit?: number;
+    defaultSelect?: readonly (AllowedPath<TSchema> | '*')[];
+    maxLimit?: number;
+}
+export type QueryConfigFromSchema<TSchema extends DataSchema> = CommonQueryConfigFromSchema<TSchema> & (LimitOffsetPaginationConfig | CursorPaginationConfig<InferData<TSchema>>);
+export interface SortItemTyped<TSchema extends DataSchema> {
+    property: AllowedPath<TSchema>;
+    direction: SortDirection;
+}
+export interface LimitOffsetPaginationPayload<TSchema extends DataSchema> {
+    type: 'LIMIT_OFFSET';
+    limit?: number;
+    page?: number;
+    sortBy?: SortItemTyped<TSchema>[];
+    select?: AllowedPath<TSchema>[];
+    filters?: WhereNode;
+}
+/**
+ * Cursor is always a string in the query input, BUT we coerce it at parse-time
+ * to match the type of cursorProperty (number / string / ISO date string).
+ */
+export interface CursorPaginationPayload<TSchema extends DataSchema> {
+    type: 'CURSOR';
+    limit?: number;
+    cursor?: number | string;
+    cursorProperty: AllowedPath<TSchema>;
+    sortBy?: SortItemTyped<TSchema>[];
+    select?: AllowedPath<TSchema>[];
+    filters?: WhereNode;
+}
+export interface PaginationQueryParams<TSchema extends DataSchema> {
+    pagination: LimitOffsetPaginationPayload<TSchema> | CursorPaginationPayload<TSchema>;
+}
+/**
+ * Generate Zod schemas and runtime validators for pagination query parameters, based on a config object.
+ * @param config The configuration object defining the pagination behavior and allowed fields.
+ * @returns An object containing:
+ *   - `queryParamsSchema`: A Zod schema for validating and parsing the raw query parameters.
+ *   - `validatorSchema`: A function that takes the already-parsed query parameters and returns a Zod schema for further validation (e.g. filters).
+ */
+export declare function paginate<TSchema extends DataSchema>(config: QueryConfigFromSchema<TSchema>): {
+    queryParamsSchema: z.ZodType<PaginationQueryParams<TSchema>>;
+    validatorSchema: (parsed?: PaginationQueryParams<TSchema>) => z.ZodType;
+};
+export {};