zod-paginate 1.6.0 → 1.7.0

package/README.md

@@ -52,7 +52,7 @@ const { queryParamsSchema, validatorSchema, responseSchema } = select({
 });
 
 const parsed = queryParamsSchema().parse({ select: "id,name,price" });
-// parsed.select → ["id", "name", "price"]
+// parsed.select.fields → ["id", "name", "price"]
 
 // Generic response schema — valid for all possible responses based on config
 responseSchema.parse({
@@ -194,11 +194,11 @@ const { queryParamsSchema, validatorSchema, responseSchema } = select({
 
 // select=* expands to all selectable fields
 const parsed = queryParamsSchema().parse({ select: "*" });
-// parsed.select → ["id", "name", "price", "details.weight", "details.color"]
+// parsed.select.fields → ["id", "name", "price", "details.weight", "details.color"]
 
 // Specific fields
 const parsed2 = queryParamsSchema().parse({ select: "id,name,details.color" });
-// parsed2.select → ["id", "name", "details.color"]
+// parsed2.select.fields → ["id", "name", "details.color"]
 
 // Generic response schema (based on defaultSelect)
 responseSchema.parse({
@@ -216,7 +216,7 @@ contextSchema.parse({
 
 // Missing select → uses defaultSelect
 const parsed3 = queryParamsSchema().parse({});
-// parsed3.select → ["id", "name", "price"]
+// parsed3.select.fields → ["id", "name", "price"]
 ```
 
 Use `SelectResult<TSchema, TSelectable>` instead of `ReturnType<typeof select>` for explicit return types:
@@ -270,7 +270,7 @@ Returns:
 |---|---:|---|
 | `paginationType` | `"LIMIT_OFFSET"` \| `"CURSOR"` | Pagination mode. |
 | `dataSchema` | `z.ZodObject` \| `z.ZodDiscriminatedUnion` \| `z.ZodUnion` | Zod schema for one data item (used for projection + cursor inference). |
-| `selectable?` | `string[]` (typed paths) | Allowlist of selectable fields (dot paths). Enables `select`. |
+| `selectable` | `string[]` (typed paths) | **Required.** Allowlist of selectable fields (dot paths). 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. |
@@ -335,7 +335,7 @@ function createPaginatorUnion(): PaginateResult<typeof ModelSchema, "id" | "stat
 
 - **Input:** string or string[] — format: `field:ASC` or `field:DESC`
 - **Output:** `[{ property, direction }]`
-- Properties are matched against the `sortable` allowlist (unknown fields are dropped).
+- Properties are matched against the `sortable` allowlist (unknown fields are **rejected**).
 - Falls back to `defaultSortBy` when missing.
 
 ### `select`
@@ -371,7 +371,7 @@ responseSchema.parse({
 
 // Type-safe: z.infer narrows data keys to selectable paths
 type Response = z.infer<typeof responseSchema>;
-// Response["data"][0] → { id?: unknown; status?: unknown; createdAt?: unknown; meta?: unknown }
+// Response["data"][0] → { id?: number; status?: string; createdAt?: Date; meta?: { score: number } }
 // Response["pagination"].totalItems → number  ✓ (no manual narrowing)
 ```
 
@@ -648,7 +648,7 @@ const parsed = queryParamsSchema({ search: z.string().optional() }).parse({
   select: "id,name",
   search: "widget",
 });
-// parsed.select → ["id", "name"]
+// parsed.select.fields → ["id", "name"]
 // parsed.search → "widget"
 ```
 
@@ -716,7 +716,7 @@ responseSchema.parse({
 });
 
 type Response = z.infer<typeof responseSchema>;
-// Response["data"][0] → { id?: unknown; status?: unknown; createdAt?: unknown; meta?: unknown }
+// Response["data"][0] → { id?: number; status?: string; createdAt?: Date; meta?: { score: number } }
 // Response["pagination"].totalItems → number  ✓
 ```
 
@@ -767,6 +767,9 @@ export function select<
 | `AllowedPath<TSchema>` | All valid dot-notation paths for a given schema |
 | `SelectConfig<TSchema, TSelectable>` | Configuration for `select()` |
 | `SelectResult<TSchema, TSelectable>` | Return type of `select()` |
+| `SelectQueryPayload<TSchema, TSelectable>` | Parsed output of `select()` — `{ select: { fields, responseType? } }` |
+| `TypedProjectedData<TSchema, TSelect>` | Projected data item with real value types (used in response types) |
+| `ProjectedData<TSchema, TSelect>` | Projected data item with `unknown` values (key autocompletion only) |
 | `PaginateResult<TSchema, TSelectable?, TType?>` | Return type of `paginate()` |
 
 ## Adapters

package/dist/paginate.d.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod';
-import { type AllowedPath, type DataSchema, type EnsureDiscriminatorInSelectable, type InferData, type Path, type PathValue, type ProjectedData, type ZodShape } from './select';
+import { type AllowedPath, type DataSchema, type EnsureDiscriminatorInSelectable, type InferData, type Path, type PathValue, type TypedProjectedData, type ZodShape } from './select';
 interface LimitOffsetPaginationConfig {
+    /** Pagination mode: classic limit/offset with page numbers. */
     paginationType: 'LIMIT_OFFSET';
 }
 interface CursorPaginationConfig<T> {
+    /** Pagination mode: cursor-based (keyset). */
     paginationType: 'CURSOR';
+    /** Field used as cursor. Its Zod type determines cursor coercion (number, string, or ISO date). */
     cursorProperty: Path<T>;
 }
 export declare const SortDirectionSchema: z.ZodEnum<{
@@ -154,19 +157,28 @@ interface FilterableFieldConfig<TKind extends FieldType> {
     type: TKind;
     ops: readonly OpsForFieldType<TKind>[];
 }
+/** Configuration shared by all pagination modes. */
 export interface CommonQueryConfigFromSchema<TSchema extends DataSchema, TSelectable extends AllowedPath<TSchema> = AllowedPath<TSchema>> {
+    /** Zod schema representing one data item (object, discriminated union, or union). */
     dataSchema: TSchema;
-    selectable?: readonly TSelectable[];
+    /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
+    selectable: readonly TSelectable[];
+    /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: readonly AllowedPath<TSchema>[];
+    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
     filterable?: Partial<{
         [P in AllowedPath<TSchema>]: FilterableFieldConfig<FieldTypeFromValue<PathValue<InferData<TSchema>, P>>>;
     }>;
+    /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: readonly {
         property: AllowedPath<TSchema>;
         direction: SortDirection;
     }[];
+    /** Default number of items per page when `limit` is omitted. */
     defaultLimit: number;
+    /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: readonly TSelectable[] | '*';
+    /** Maximum allowed value for `limit`. Requests exceeding this are rejected. */
     maxLimit: number;
 }
 /**
@@ -224,11 +236,11 @@ export interface CursorPaginationResponseMeta {
     filter?: WhereNode;
 }
 export interface LimitOffsetPaginationResponse<TSchema extends DataSchema, TSelect extends AllowedPath<TSchema> = AllowedPath<TSchema>> {
-    data: ProjectedData<TSchema, TSelect>[];
+    data: TypedProjectedData<TSchema, TSelect>[];
     pagination: LimitOffsetPaginationResponseMeta;
 }
 export interface CursorPaginationResponse<TSchema extends DataSchema, TSelect extends AllowedPath<TSchema> = AllowedPath<TSchema>> {
-    data: ProjectedData<TSchema, TSelect>[];
+    data: TypedProjectedData<TSchema, TSelect>[];
     pagination: CursorPaginationResponseMeta;
 }
 export type PaginationResponse<TSchema extends DataSchema, TSelect extends AllowedPath<TSchema> = AllowedPath<TSchema>, TType extends PaginationType = PaginationType> = TType extends 'LIMIT_OFFSET' ? LimitOffsetPaginationResponse<TSchema, TSelect> : TType extends 'CURSOR' ? CursorPaginationResponse<TSchema, TSelect> : never;
@@ -276,7 +288,7 @@ export interface PaginateResult<TSchema extends DataSchema, TType extends Pagina
         (): z.ZodType<PaginationQueryParams<TSchema, TType>>;
         <TExtraShape extends z.ZodRawShape>(extraShape: TExtraShape): z.ZodType<PaginationQueryParams<TSchema, TType> & z.infer<z.ZodObject<TExtraShape>>>;
     };
-    validatorSchema: (parsed?: PaginationPayload<TSchema>) => z.ZodType;
+    validatorSchema: (parsed?: PaginationPayload<TSchema>) => z.ZodType<PaginationResponse<TSchema, AllowedPath<TSchema>, TType>>;
     responseSchema: z.ZodObject<PaginationResponseSchemaShape<TType>>;
 }
 /**
@@ -288,37 +300,52 @@ export interface PaginateResult<TSchema extends DataSchema, TType extends Pagina
  *   - `responseSchema`: A pre-built Zod schema for validating the response (uses defaultSelect or all selectable fields).
  */
 export declare function paginate<TSchema extends DataSchema, const TSelectable extends readonly AllowedPath<TSchema>[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & LimitOffsetPaginationConfig & {
-    selectable?: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
+    selectable: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: readonly NoInfer<TSelectable[number]>[] | '*';
+    /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: readonly NoInfer<TSelectable[number]>[];
+    /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: readonly {
         property: NoInfer<TSelectable[number]>;
         direction: SortDirection;
     }[];
+    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
     filterable?: Partial<{
         [P in NoInfer<TSelectable[number]>]: FilterableFieldConfig<FieldTypeFromValue<PathValue<InferData<TSchema>, P>>>;
     }>;
 }): PaginateResult<TSchema, 'LIMIT_OFFSET'>;
 export declare function paginate<TSchema extends DataSchema, const TSelectable extends readonly AllowedPath<TSchema>[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & CursorPaginationConfig<InferData<TSchema>> & {
-    selectable?: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
+    selectable: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: readonly NoInfer<TSelectable[number]>[] | '*';
+    /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: readonly NoInfer<TSelectable[number]>[];
+    /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: readonly {
         property: NoInfer<TSelectable[number]>;
         direction: SortDirection;
     }[];
+    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
     filterable?: Partial<{
         [P in NoInfer<TSelectable[number]>]: FilterableFieldConfig<FieldTypeFromValue<PathValue<InferData<TSchema>, P>>>;
     }>;
 }): PaginateResult<TSchema, 'CURSOR'>;
 export declare function paginate<TSchema extends DataSchema, const TSelectable extends readonly AllowedPath<TSchema>[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & {
-    selectable?: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
+    selectable: EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: readonly NoInfer<TSelectable[number]>[] | '*';
+    /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: readonly NoInfer<TSelectable[number]>[];
+    /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: readonly {
         property: NoInfer<TSelectable[number]>;
         direction: SortDirection;
     }[];
+    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
     filterable?: Partial<{
         [P in NoInfer<TSelectable[number]>]: FilterableFieldConfig<FieldTypeFromValue<PathValue<InferData<TSchema>, P>>>;
     }>;

package/dist/paginate.js

@@ -547,12 +547,16 @@ function computeSortBy(sortByRaw, config) {
     if (sortByRaw) {
         const cleaned = sortByRaw.map((s) => s.trim()).filter(Boolean);
         if (cleaned.length > 0) {
+            const seen = new Set();
             const out = [];
             for (const raw of cleaned) {
                 const parsed = parseSortItem(raw);
                 const picked = (0, select_1.pickFromAllowlist)(config.sortable, parsed.property);
                 if (!picked)
                     continue;
+                if (seen.has(picked))
+                    continue;
+                seen.add(picked);
                 out.push({ property: picked, direction: parsed.direction });
             }
             return out.length > 0 ? out : undefined;
@@ -719,7 +723,7 @@ function buildCursorResponseSchema(dataItemSchema, parts) {
 function paginate(config) {
     const discriminatorKey = (0, select_1.getDiscriminatorKey)(config.dataSchema);
     const nestedDiscriminators = (0, select_1.findNestedDiscriminators)(config.dataSchema);
-    const selectableStrings = [...(config.selectable ?? [])];
+    const selectableStrings = [...config.selectable];
     const effectiveConfig = {
         selectable: selectableStrings,
         defaultSelect: config.defaultSelect === '*' ? '*' : Array.from(config.defaultSelect, String),
@@ -787,7 +791,7 @@ function paginate(config) {
             example: `${String(config.sortable[0])}:ASC`,
         });
     }
-    if (config.selectable && config.selectable.length > 0) {
+    if (config.selectable.length > 0) {
         const defaultSelectDesc = config.defaultSelect === '*' ? '*' : [...config.defaultSelect].join(', ');
         rootShape.select = zod_1.z
             .string()
@@ -858,14 +862,6 @@ function paginate(config) {
                 message: `limit must be <= ${config.maxLimit}`,
             });
         }
-        // select forbidden if no selectable configured
-        if (val.select && (!config.selectable || config.selectable.length === 0)) {
-            ctx.addIssue({
-                code: 'custom',
-                path: ['select'],
-                message: `select is not allowed (no selectable fields configured)`,
-            });
-        }
         // select allowlist + "*" expandability
         const selectForValidation = val.select ??
             (effectiveConfig.defaultSelect === '*' ? ['*'] : effectiveConfig.defaultSelect);
@@ -923,7 +919,6 @@ function paginate(config) {
             }
         }
         // sort allowlist
-        const sortItems = computeSortBy(val.sortBy, config);
         if (val.sortBy) {
             if (!config.sortable || config.sortable.length === 0) {
                 ctx.addIssue({
@@ -932,14 +927,16 @@ function paginate(config) {
                     message: `sortBy is not allowed (no sortable fields configured)`,
                 });
             }
-            else if (sortItems) {
+            else {
+                const cleaned = val.sortBy.map((s) => s.trim()).filter(Boolean);
                 let index = 0;
-                for (const item of sortItems) {
-                    if (!allowedSortable.has(item.property)) {
+                for (const raw of cleaned) {
+                    const parsed = parseSortItem(raw);
+                    if (!allowedSortable.has(parsed.property)) {
                         ctx.addIssue({
                             code: 'custom',
                             path: ['sortBy', index],
-                            message: `sort property "${item.property}" is not allowed`,
+                            message: `sort property "${parsed.property}" is not allowed`,
                         });
                     }
                     index += 1;
@@ -1059,7 +1056,7 @@ function paginate(config) {
     const LIMIT_OFFSET_META_DESC = 'Pagination metadata for limit/offset mode';
     const CURSOR_META_DESC = 'Pagination metadata for cursor mode';
     const CURSOR_VALUE_DESC = 'Cursor value pointing to the last item returned';
-    const validatorSchema = (parsed) => {
+    function validatorSchema(parsed) {
         const effectiveSelect = parsed?.select ?? (0, select_1.computeSelect)(undefined, effectiveConfig) ?? undefined;
         const dataItemSchema = effectiveSelect && effectiveSelect.length > 0
             ? (0, select_1.projectDataSchemaPreservingUnion)(config.dataSchema, effectiveSelect.map(String))
@@ -1091,7 +1088,7 @@ function paginate(config) {
             })
                 .meta({ description: CURSOR_META_DESC }),
         });
-    };
+    }
     const partialDataItemSchema = selectableStrings.length > 0
         ? (0, select_1.projectDataSchemaPreservingUnion)(config.dataSchema, selectableStrings, { partial: true })
         : (0, select_1.resolveToZodObject)(config.dataSchema);