zod-paginate 1.0.1 → 1.1.0

package/README.md

@@ -6,10 +6,11 @@ It is designed for Node.js HTTP stacks where query parameters arrive as strings
 
 - 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 **field projection** using `select`, 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.
+- Also exports a lightweight **`select()`** utility for field-projection-only use cases.
 
 > 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.
@@ -164,11 +165,11 @@ Typical querystring parsers produce values like:
 
 ### `select`
 
-- Input: CSV string
+- Input: string
 - Output: string[] (typed paths)
 - Rules
   - Requires `selectable` in config
-  - CSV is split by `,`, trimmed, empty items removed
+  - string 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
@@ -194,11 +195,103 @@ You configure which fields are filterable and which operators are allowed via `f
 | `$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 |
+| `$gt` | greater than | number or ISO date |
+| `$gte` | greater than or equal | number or ISO date |
+| `$lt` | less than | number or ISO date |
+| `$lte` | less than or equal | 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 |
 
+#### `$eq` — equals
+
+Matches rows where the field is exactly equal to the given value. The value type must match the field type (number, string, or ISO date).
+
+```txt
+filter.status=$eq:active
+filter.id=$eq:42
+filter.createdAt=$eq:2025-01-15
+```
+
+#### `$null` — is null
+
+Matches rows where the field is `NULL`. No value is required after the operator.
+
+```txt
+filter.deletedAt=$null
+```
+
+To match rows where the field is **not** null, combine with `$not`:
+
+```txt
+filter.deletedAt=$not:$null
+```
+
+#### `$in` — in list
+
+Matches rows where the field value is one of the provided comma-separated values.
+
+```txt
+filter.status=$in:active,pending,review
+filter.id=$in:1,2,3,10
+```
+
+#### `$contains` — contains values
+
+Matches rows where the field (typically an array column) contains all the provided comma-separated values.
+
+```txt
+filter.tags=$contains:typescript,zod
+filter.roles=$contains:admin
+```
+
+#### `$gt` / `$gte` / `$lt` / `$lte` — comparisons
+
+Standard comparison operators: greater than, greater than or equal, less than, less than or equal. Works with numbers and ISO dates.
+
+```txt
+filter.id=$gt:100
+filter.id=$lte:500
+filter.createdAt=$gte:2025-01-01
+filter.createdAt=$lt:2025-06-01T00:00:00Z
+```
+
+Combine multiple comparisons to build ranges:
+
+```txt
+filter.id=$gt:10&filter.id=$lt:100
+```
+
+#### `$btw` — between
+
+Matches rows where the field value falls between two bounds (inclusive). Both bounds must be the same type — either both numbers or both ISO dates.
+
+```txt
+filter.id=$btw:10,100
+filter.createdAt=$btw:2025-01-01,2025-12-31
+filter.createdAt=$btw:2025-01-01T00:00:00Z,2025-06-30T23:59:59Z
+```
+
+#### `$ilike` — case-insensitive contains
+
+Matches rows where the string field contains the given substring, ignoring case. Useful for search-style filtering.
+
+```txt
+filter.status=$ilike:act
+filter.name=$ilike:john
+filter.email=$ilike:@example.com
+```
+
+#### `$sw` — starts with
+
+Matches rows where the string field starts with the given prefix.
+
+```txt
+filter.name=$sw:Jon
+filter.email=$sw:admin@
+filter.path=$sw:/api/v2
+```
+
 Runtime validation enforces:
 
 1) field allowlist (`filterable`)
@@ -381,8 +474,7 @@ const parsed = queryParamsSchema.parse({ cursor: "123", limit: "10" });
 //   limit: 10,
 //   cursor: 123,            // <- coerced from "123" because cursorProperty is a number
 //   cursorProperty: "id",
-//   select: ["id", "createdAt"],
-//   filters: { type: "and", items: [] }
+//   select: ["id", "createdAt"]
 // }
 ```
 
@@ -425,3 +517,77 @@ responseSchema.parse({
   pagination: { itemsPerPage: 10, totalItems: 1, currentPage: 1, totalPages: 1 },
 });
 ```
+
+## `select()` — standalone field projection
+
+If you only need **field projection** without pagination, sorting, or filters, you can use the `select()` utility directly.
+
+### API
+
+```ts
+import { select } from "zod-paginate";
+
+export function select<TSchema extends DataSchema>(
+  config: SelectConfig<TSchema>,
+): {
+  queryParamsSchema: z.ZodType<SelectQueryParams<TSchema>>;
+  validatorSchema: (parsed?: SelectQueryParams<TSchema>) => z.ZodType;
+}
+```
+
+#### `SelectConfig`
+
+| Option | Type | Description |
+|---|---:|---|
+| `dataSchema` | `z.ZodObject` | Zod schema representing one data item. |
+| `selectable` | `string[]` (typed paths) | Allowlist of selectable fields (dot paths supported). |
+| `defaultSelect?` | `("*" \| field)[]` | Default select if `select` is missing. `["*"]` expands to `selectable`. |
+
+#### Output
+
+- `queryParamsSchema` parses `{ select: "id,name" }` into `{ select: ["id", "name"] }`.
+- `validatorSchema(parsed?)` returns a Zod schema expecting `{ data: Array<ProjectedItem> }`.
+
+#### Example
+
+```ts
+import { z } from "zod";
+import { select } from "zod-paginate";
+
+const ProductSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  price: z.number(),
+  details: z.object({
+    weight: z.number(),
+    color: z.string(),
+  }),
+});
+
+const { queryParamsSchema, validatorSchema } = select({
+  dataSchema: ProductSchema,
+  selectable: ["id", "name", "price", "details.weight", "details.color"],
+  defaultSelect: ["id", "name", "price"],
+});
+
+// select=* expands to all selectable fields
+const parsed = queryParamsSchema.parse({ select: "*" });
+// parsed.select → ["id", "name", "price", "details.weight", "details.color"]
+
+// With specific fields
+const parsed2 = queryParamsSchema.parse({ select: "id,name,details.color" });
+// parsed2.select → ["id", "name", "details.color"]
+
+// Validate response shape
+const responseSchema = validatorSchema(parsed2);
+responseSchema.parse({
+  data: [
+    { id: 1, name: "Widget", details: { color: "red" } },
+    { id: 2, name: "Gadget", details: { color: "blue" } },
+  ],
+});
+
+// Missing select → uses defaultSelect
+const parsed3 = queryParamsSchema.parse({});
+// parsed3.select → ["id", "name", "price"]
+```

package/dist/main.d.ts

@@ -1,238 +1,2 @@
-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>;
-}
-export declare const SortDirectionSchema: z.ZodEnum<{
-    ASC: "ASC";
-    DESC: "DESC";
-}>;
-export type SortDirection = z.infer<typeof SortDirectionSchema>;
-export declare const SortItemSchema: z.ZodObject<{
-    property: z.ZodString;
-    direction: z.ZodEnum<{
-        ASC: "ASC";
-        DESC: "DESC";
-    }>;
-}, z.core.$strip>;
-export type SortItem = z.infer<typeof SortItemSchema>;
-/**
- * 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)
- */
-export 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";
-}>;
-export type Operator = z.infer<typeof OperatorSchema>;
-/**
- * Logical combinators for grouping conditions. $and and $or can be used to combine multiple conditions within the same group.
- */
-export declare const CombinatorSchema: z.ZodEnum<{
-    $and: "$and";
-    $or: "$or";
-}>;
-export type Combinator = z.infer<typeof CombinatorSchema>;
-export declare const IntegerStringSchema: z.ZodString;
-/**
- * Regex for validating ISO date strings (YYYY-MM-DD).
- */
-export declare const ISO_DATE_RE: RegExp;
-/**
- * Regex for validating ISO datetime strings (YYYY-MM-DDTHH:mm:ss.sssZ or with timezone offset).
- */
-export declare const ISO_DATETIME_RE: RegExp;
-export declare const NumericStringSchema: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
-export declare const NumOrDateSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
-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;
-export 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">;
-export type Condition = z.infer<typeof ConditionSchema>;
-export interface WhereFilter {
-    type: 'filter';
-    field: string;
-    condition: Condition;
-}
-export interface WhereAnd {
-    type: 'and';
-    items: WhereNode[];
-}
-export interface WhereOr {
-    type: 'or';
-    items: WhereNode[];
-}
-export 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 {};
+export * from './paginate';
+export * from './select';