zod-paginate 1.10.2 → 2.0.0

package/README.md

@@ -18,6 +18,7 @@ It is designed for Node.js HTTP stacks where query parameters arrive as strings
 - **Filter DSL** with `$` operators and **nested AND/OR grouping**.
 - **Response validation** — `responseSchema` is a generic schema covering all possible responses based on your config; `validatorSchema(parsed.select)` validates outgoing data projected to the actual requested `select`. `z.infer<typeof responseSchema>` gives you **key autocompletion** narrowed to configured `selectable` paths.
 - **Discriminated union support** — `z.discriminatedUnion()` and `z.union()` as `dataSchema`, with compile-time and runtime discriminator enforcement.
+- **Decorative fields** — mark computed/manual fields as selectable-only (excluded from sort & filter)
 - **Standalone `select()`** utility for field-projection-only use cases.
 - Compatible with **OpenAPI tooling** ([zod-openapi](https://github.com/samchungy/zod-openapi) etc.).
 
@@ -105,7 +106,7 @@ const parsed = queryParamsSchema().parse({
   page: "2",
   sortBy: "createdAt:DESC",
   select: "id,status",
-  "filter.status": "$ilike:act",
+  "filter[status]": "$ilike:act",
 });
 
 console.log(parsed.pagination);
@@ -167,6 +168,7 @@ Returns:
 |---|---:|---|
 | `dataSchema` | `z.ZodObject` \| `z.ZodDiscriminatedUnion` \| `z.ZodUnion` | Zod schema representing one data item. |
 | `selectable` | `string[]` (typed paths) | Allowlist of selectable fields (dot paths supported). |
+| `decorative?` | `string[]` (typed paths) | Subset of `selectable`. Fields that are added manually (not from DB). Included in `decorativeFields` output. |
 | `defaultSelect` | `field[] \| "*"` | **Required.** Default when `select` is missing. `"*"` expands to `selectable`. |
 | `responseType` | `"many" \| "one"` | Shape of `data` in the response (default: `"many"`). |
 
@@ -271,6 +273,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) | **Required.** Allowlist of selectable fields (dot paths). Enables `select`. |
+| `decorative?` | `string[]` (typed paths) | Subset of `selectable`. Fields added manually (not from DB). Cannot be sorted or filtered. Included in `decorativeSelect` output. |
 | `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. |
@@ -423,23 +426,23 @@ contextSchema.parse({
 
 ## Filters
 
-Filters use query keys with the pattern `filter.<field>=<dsl>` where `<field>` is a dot-path (e.g. `meta.score`). Configure which fields and operators are allowed via the `filterable` option.
+Filters use query keys with bracket notation `filter[<field>]=<dsl>` where `<field>` is a dot-path (e.g. `meta.score`). Configure which fields and operators are allowed via the `filterable` option.
 
 ### Operators
 
 | Operator | Meaning | Value format | Example |
 |---|---|---|---|
-| `$eq` | equals | number / string / ISO date | `filter.status=$eq:active` |
-| `$null` | is null | _(no value)_ | `filter.deletedAt=$null` |
-| `$in` | in list | comma-separated | `filter.status=$in:active,pending` |
-| `$contains` | contains values | comma-separated | `filter.tags=$contains:typescript,zod` |
-| `$gt` | greater than | number or ISO date | `filter.id=$gt:100` |
-| `$gte` | greater than or equal | number or ISO date | `filter.createdAt=$gte:2025-01-01` |
-| `$lt` | less than | number or ISO date | `filter.id=$lt:500` |
-| `$lte` | less than or equal | number or ISO date | `filter.id=$lte:500` |
-| `$btw` | between (inclusive) | `a,b` (same type) | `filter.id=$btw:10,100` |
-| `$ilike` | case-insensitive contains | string | `filter.name=$ilike:john` |
-| `$sw` | starts with | string | `filter.name=$sw:Jon` |
+| `$eq` | equals | number / string / ISO date | `filter[status]=$eq:active` |
+| `$null` | is null | _(no value)_ | `filter[deletedAt]=$null` |
+| `$in` | in list | comma-separated | `filter[status]=$in:active,pending` |
+| `$contains` | contains values | comma-separated | `filter[tags]=$contains:typescript,zod` |
+| `$gt` | greater than | number or ISO date | `filter[id]=$gt:100` |
+| `$gte` | greater than or equal | number or ISO date | `filter[createdAt]=$gte:2025-01-01` |
+| `$lt` | less than | number or ISO date | `filter[id]=$lt:500` |
+| `$lte` | less than or equal | number or ISO date | `filter[id]=$lte:500` |
+| `$btw` | between (inclusive) | `a,b` (same type) | `filter[id]=$btw:10,100` |
+| `$ilike` | case-insensitive contains | string | `filter[name]=$ilike:john` |
+| `$sw` | starts with | string | `filter[name]=$sw:Jon` |
 
 If the filter value does **not** start with `$`, it is interpreted as `$eq:<value>`.
 
@@ -448,20 +451,20 @@ If the filter value does **not** start with `$`, it is interpreted as `$eq:<valu
 Prefix any operator with `$not:` to negate the condition:
 
 ```txt
-filter.deletedAt=$not:$null
-filter.status=$not:$eq:active
+filter[deletedAt]=$not:$null
+filter[status]=$not:$eq:active
 ```
 
 ### Multiple conditions for the same field
 
-Use repeated query params or pass an array:
+Repeat the same query param key to pass multiple conditions:
 
 ```txt
-filter.id=$gt:10&filter.id=$lt:100
+filter[id]=$gt:10&filter[id]=$lt:100
 ```
 
 ```ts
-{ "filter.id": ["$gt:10", "$lt:100"] }
+{ "filter[id]": ["$gt:10", "$lt:100"] }
 ```
 
 Runtime validation enforces: field allowlist (`filterable`), operator allowlist per field (`ops`), and value type compatibility.
@@ -475,31 +478,35 @@ Groups let you build nested AND/OR boolean logic.
 Prefix any filter DSL with `$g:<groupId>:`:
 
 ```txt
-filter.status=$g:1:$eq:active
+filter[status]=$g:1:$eq:active
 ```
 
 Within a group, the **first** condition cannot have `$and`/`$or`. Following conditions may be prefixed with `$and` or `$or`.
 
-### Group tree definitions: `group.<id>.*`
+### Group tree definitions: `group`
 
-Define parent-child relationships between groups:
+Define parent-child relationships between groups using the repeated `group` query parameter. Each entry has the format `id:key=value,key=value`.
 
-- `group.<id>.parent` — parent group id (integer string)
-- `group.<id>.join` — how this group joins its parent (`$and` or `$or`)
-- `group.<id>.op` — default join for this group's children (optional)
+Available keys:
 
-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.
+- `parent` — parent group id (integer string)
+- `join` — how this group joins its parent (`$and` or `$or`)
+- `op` — default join for this group's children (optional)
+
+Rules: root group id is always `"0"`. `parent` and `join` are forbidden on group `0`. Cycles are rejected. Child groups are resolved in numeric order.
 
 **Example:** `(status == active OR status == postponed) AND (id > 10)`
 
+```txt
+?filter[status]=$g:1:$eq:active&filter[status]=$g:1:$or:$eq:postponed&filter[id]=$g:2:$gt:10&group=1:parent=0&group=2:parent=0,join=$and
+```
+
 ```ts
 const parsed = queryParamsSchema().parse({
-  "filter.status": ["$g:1:$eq:active", "$g:1:$or:$eq:postponed"],
-  "filter.id": "$g:2:$gt:10",
+  "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",
+  group: ["1:parent=0", "2:parent=0,join=$and"],
 });
 
 // parsed.pagination.filters
@@ -629,6 +636,99 @@ schema.safeParse({ data: [{ id: 1, type: "video", bitrate: 320 }] });
 // → fails validation
 ```
 
+## Decorative fields
+
+Some fields in your schema may be computed or added manually at runtime (e.g. image URLs, aggregated values) rather than stored in and fetched from the database. Marking them as `decorative` tells zod-paginate that they are **selectable** but must **not be sorted or filtered**.
+
+### Configuration
+
+```ts
+import { z } from "zod";
+import { paginate } from "zod-paginate";
+
+const ShowSummary = z.object({
+  id: z.number(),
+  title: z.string(),
+  urlAlias: z.string(),
+  image: z.string(),
+  genres: z.string().nullable(),
+});
+
+const PublicFeed = z.object({
+  id: z.number(),
+  title: z.string(),
+  shows: z.array(ShowSummary),
+});
+
+const { queryParamsSchema } = paginate({
+  paginationType: "LIMIT_OFFSET",
+  dataSchema: PublicFeed,
+  selectable: ["id", "title", "shows.id", "shows.title", "shows.image", "shows.genres"],
+  decorative: ["shows.image"],   // ← added at runtime, not from DB
+  sortable: ["id", "title"],     // "shows.image" here would be a type error
+  filterable: {
+    id: { type: "number", ops: ["$eq"] },
+    // "shows.image" here would be a type error
+  },
+  defaultSelect: "*",
+  defaultLimit: 20,
+  maxLimit: 100,
+});
+```
+
+### Parsed output
+
+The parsed payload includes `decorativeSelect` (or `decorativeFields` for `select()`), containing only the decorative fields that were actually requested:
+
+```ts
+const parsed = queryParamsSchema().parse({ select: "*" });
+
+parsed.pagination.select;
+// → ["id", "title", "shows.id", "shows.title", "shows.image", "shows.genres"]
+
+parsed.pagination.decorativeSelect;
+// → ["shows.image"]
+```
+
+When none of the requested fields are decorative, `decorativeSelect` is `undefined`.
+
+### Usage in adapters
+
+Your adapter can use `decorativeSelect` to skip those fields when building the database query:
+
+```ts
+const { select, decorativeSelect } = parsed.pagination;
+
+// Only query real DB fields
+const dbFields = select?.filter(f => !decorativeSelect?.includes(f));
+// → ["id", "title", "shows.id", "shows.title", "shows.genres"]
+
+const rows = await db.query(dbFields);
+
+// Then enrich with decorative fields manually
+const data = rows.map(row => ({
+  ...row,
+  shows: row.shows.map(s => ({ ...s, image: buildImageUrl(s) })),
+}));
+```
+
+### With `select()` standalone
+
+The same option works with `select()` — the output uses `decorativeFields` instead:
+
+```ts
+const { queryParamsSchema } = select({
+  dataSchema: ShowSummary,
+  selectable: ["id", "title", "urlAlias", "image", "genres"],
+  decorative: ["image"],
+  defaultSelect: "*",
+});
+
+const parsed = queryParamsSchema().parse({ select: "id,title,image" });
+parsed.select.fields;           // → ["id", "title", "image"]
+parsed.select.decorativeFields; // → ["image"]
+```
+
 ## Extending `queryParamsSchema`
 
 Both `select()` and `paginate()` support extending `queryParamsSchema` with additional fields:
@@ -659,7 +759,7 @@ Extra fields are validated together — errors from both sides are collected in
 ### LIMIT/OFFSET
 
 ```txt
-?limit=20&page=1&select=id,status,createdAt&sortBy=createdAt:DESC&filter.status=$ilike:act&filter.id=$gt:10
+?limit=20&page=1&select=id,status,createdAt&sortBy=createdAt:DESC&filter[status]=$ilike:act&filter[id]=$gt:10
 ```
 
 ```ts
@@ -668,8 +768,8 @@ const parsed = queryParamsSchema().parse({
   page: "1",
   select: "id,status,createdAt",
   sortBy: "createdAt:DESC",
-  "filter.status": "$ilike:act",
-  "filter.id": "$gt:10",
+  "filter[status]": "$ilike:act",
+  "filter[id]": "$gt:10",
 });
 
 // parsed.pagination
@@ -777,7 +877,7 @@ export function select<
 | `SelectConfig<TSchema, TSelectable>` | Configuration for `select()` |
 | `SelectResult<TSchema, TSelectable, TResponseType?>` | Return type of `select()`. `TResponseType` narrows `validatorSchema` return and `responseType` property. |
 | `SelectQueryParams<TSchema, TSelectable>` | Parsed output of `select()` — `{ select: SelectQueryPayload }` |
-| `SelectQueryPayload<TSchema, TSelectable, TResponseType?>` | Inner select payload — `{ fields, responseType }`. Passed to `validatorSchema()`. |
+| `SelectQueryPayload<TSchema, TSelectable, TResponseType?>` | Inner select payload — `{ fields, decorativeFields?, responseType }`. Passed to `validatorSchema()`. |
 | `SelectOneQueryPayload<TSchema, TSelectable?>` | Shorthand for `SelectQueryPayload<…, 'one'>` |
 | `SelectManyQueryPayload<TSchema, TSelectable?>` | Shorthand for `SelectQueryPayload<…, 'many'>` |
 | `SelectResponse<TSchema, TSelect, TResponseType?>` | Response type: `{ data: … }` — array when `'many'`, single object when `'one'` |

package/dist/paginate.d.ts

@@ -163,9 +163,11 @@ export interface CommonQueryConfigFromSchema<TSchema extends DataSchema, TSelect
     dataSchema: TSchema;
     /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
     selectable: readonly TSelectable[];
+    /** Fields that are decorative (added manually, not from DB). Cannot be sorted or filtered. Subset of selectable. */
+    decorative?: readonly AllowedPath<TSchema>[];
     /** 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. */
+    /** 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>>>;
     }>;
@@ -195,6 +197,8 @@ export interface LimitOffsetPaginationPayload<TSchema extends DataSchema> {
     page?: number;
     sortBy?: SortItemTyped<TSchema>[];
     select?: AllowedPath<TSchema>[];
+    /** Subset of `select` that are decorative (not from DB, added manually). */
+    decorativeSelect?: AllowedPath<TSchema>[];
     filters?: WhereNode;
 }
 /**
@@ -208,6 +212,8 @@ export interface CursorPaginationPayload<TSchema extends DataSchema> {
     cursorProperty: AllowedPath<TSchema>;
     sortBy?: SortItemTyped<TSchema>[];
     select?: AllowedPath<TSchema>[];
+    /** Subset of `select` that are decorative (not from DB, added manually). */
+    decorativeSelect?: AllowedPath<TSchema>[];
     filters?: WhereNode;
 }
 export type PaginationType = 'LIMIT_OFFSET' | 'CURSOR';
@@ -309,13 +315,15 @@ export declare function paginate<TSchema extends DataSchema, const TSelectable e
 }[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & LimitOffsetPaginationConfig & {
     /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
     selectable: NoDuplicates<TSelectable> & EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Fields that are decorative (added manually, not from DB). Cannot be sorted or filtered. */
+    decorative?: readonly NoInfer<TSelectable[number]>[];
     /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: NoDuplicates<TDefaultSelect> | '*';
     /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: NoDuplicates<TSortable>;
     /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: NoDuplicateProperties<TDefaultSortBy>;
-    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
+    /** 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>>>;
     }>;
@@ -329,13 +337,15 @@ export declare function paginate<TSchema extends DataSchema, const TSelectable e
 }[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & CursorPaginationConfig<InferData<TSchema>> & {
     /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
     selectable: NoDuplicates<TSelectable> & EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Fields that are decorative (added manually, not from DB). Cannot be sorted or filtered. */
+    decorative?: readonly NoInfer<TSelectable[number]>[];
     /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: NoDuplicates<TDefaultSelect> | '*';
     /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: NoDuplicates<TSortable>;
     /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: NoDuplicateProperties<TDefaultSortBy>;
-    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
+    /** 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>>>;
     }>;
@@ -349,13 +359,15 @@ export declare function paginate<TSchema extends DataSchema, const TSelectable e
 }[]>(config: Omit<CommonQueryConfigFromSchema<TSchema, TSelectable[number]>, 'selectable' | 'defaultSelect' | 'sortable' | 'defaultSortBy' | 'filterable'> & {
     /** Allowlist of selectable fields (dot-notation paths). Enables the `select` query parameter. */
     selectable: NoDuplicates<TSelectable> & EnsureDiscriminatorInSelectable<TSchema, TSelectable>;
+    /** Fields that are decorative (added manually, not from DB). Cannot be sorted or filtered. */
+    decorative?: readonly NoInfer<TSelectable[number]>[];
     /** Default fields returned when `select` is omitted. Use `"*"` to select all. */
     defaultSelect: NoDuplicates<TDefaultSelect> | '*';
     /** Allowlist of sortable fields. Enables the `sortBy` query parameter. Unknown sort fields are rejected. */
     sortable?: NoDuplicates<TSortable>;
     /** Default sort order applied when `sortBy` is omitted from the query. */
     defaultSortBy?: NoDuplicateProperties<TDefaultSortBy>;
-    /** Map of filterable fields to their allowed type and operators. Enables the `filter.*` query parameters. */
+    /** 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

@@ -174,41 +174,55 @@ const WhereNodeSchema = zod_1.z
 });
 function extractGroupDefs(q) {
     const defs = {};
-    for (const [k, v] of Object.entries(q)) {
-        if (!k.startsWith('group.'))
-            continue;
-        const rest = k.slice('group.'.length);
-        const dotIdx = rest.indexOf('.');
-        if (dotIdx === -1)
+    const raw = q.group;
+    if (raw === undefined || raw === null)
+        return defs;
+    let entries;
+    if (Array.isArray(raw)) {
+        entries = raw.filter((x) => typeof x === 'string');
+    }
+    else if (typeof raw === 'string') {
+        entries = [raw];
+    }
+    else {
+        entries = [];
+    }
+    for (const entry of entries) {
+        // Format: "id:key=value,key=value"
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1)
             continue;
-        const groupIdRaw = rest.slice(0, dotIdx).trim();
-        const prop = rest.slice(dotIdx + 1).trim();
-        const parsedId = exports.IntegerStringSchema.safeParse(groupIdRaw);
+        const idRaw = entry.slice(0, colonIdx).trim();
+        const propsRaw = entry.slice(colonIdx + 1).trim();
+        const parsedId = exports.IntegerStringSchema.safeParse(idRaw);
         if (!parsedId.success)
             continue;
         const id = parsedId.data;
-        const first = Array.isArray(v) ? v[0] : v;
-        const valueStr = typeof first === 'string' ? first : '';
         const current = defs[id] ?? {};
-        if (prop === 'parent') {
-            defs[id] = { ...current, parent: exports.IntegerStringSchema.parse(valueStr.trim()) };
-            continue;
-        }
-        if (prop === 'join') {
-            defs[id] = { ...current, join: exports.CombinatorSchema.parse(valueStr.trim()) };
-            continue;
-        }
-        if (prop === 'op') {
-            defs[id] = { ...current, op: exports.CombinatorSchema.parse(valueStr.trim()) };
-            continue;
+        for (const pair of propsRaw.split(',')) {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const prop = pair.slice(0, eqIdx).trim();
+            const value = pair.slice(eqIdx + 1).trim();
+            if (prop === 'parent') {
+                current.parent = exports.IntegerStringSchema.parse(value);
+            }
+            else if (prop === 'join') {
+                current.join = exports.CombinatorSchema.parse(value);
+            }
+            else if (prop === 'op') {
+                current.op = exports.CombinatorSchema.parse(value);
+            }
         }
+        defs[id] = current;
     }
     return defs;
 }
 function validateGroupDefs(defs) {
     const root = defs[ROOT_GROUP_ID];
     if (root && (root.parent !== undefined || root.join !== undefined)) {
-        throw new Error(`group.0 can only define "op". "parent" and "join" are not allowed on root group "0".`);
+        throw new Error(`Group "0" can only define "op". "parent" and "join" are not allowed on root group "0".`);
     }
     for (const [id, def] of Object.entries(defs)) {
         if (id === ROOT_GROUP_ID)
@@ -367,7 +381,7 @@ function assertSameKind(a, b, ctx) {
         throw new Error(`$btw bounds must be same type (both number or both date) for ${ctx}`);
     }
 }
-/** Parse a single "filter.<field>" DSL string into a Condition. */
+/** Parse a single "filter[field]" DSL string into a Condition. */
 function parseSingleCondition(raw) {
     const parts = raw.split(':');
     let group = ROOT_GROUP_ID;
@@ -444,9 +458,10 @@ function parseSingleCondition(raw) {
 function extractAndNormalizeRawFilters(q) {
     const result = {};
     for (const [k, v] of Object.entries(q)) {
-        if (!k.startsWith('filter.'))
+        const match = /^filter\[([^\]]+)\]$/.exec(k);
+        if (!match)
             continue;
-        const field = k.slice('filter.'.length).trim();
+        const field = (match[1] ?? '').trim();
         if (!field)
             continue;
         const rawList = toStringArrayFromQueryString(v);
@@ -729,6 +744,7 @@ function paginate(config) {
         defaultSelect: config.defaultSelect === '*' ? '*' : Array.from(config.defaultSelect, String),
     };
     const allowedSelectable = new Set(selectableStrings);
+    const decorativeSet = new Set((config.decorative ?? []).map(String));
     const allowedSortable = new Set();
     for (const f of config.sortable ?? [])
         allowedSortable.add(`${f}`);
@@ -754,9 +770,9 @@ function paginate(config) {
     /*
      * Build the root ZodObject with explicit named properties so that
      * OpenAPI tooling (zod-openapi, fastify-zod-openapi) can introspect
-     * the query parameters. Dynamic keys (filter.*, group.*) pass through
-     * via .catchall(z.unknown()). The actual validation/transforms happen
-     * in the piped baseSchema below.
+     * the query parameters. Filter fields use bracket notation (filter[field])
+     * and group uses a repeated "group" param. The actual validation/transforms
+     * happen in the piped baseSchema below.
      */
     const rootShape = {
         limit: zod_1.z
@@ -801,6 +817,26 @@ function paginate(config) {
             example: defaultSelectDesc,
         });
     }
+    // Add filter[field] entries and group param only when filterable is configured
+    if (config.filterable) {
+        for (const [field, def] of Object.entries(filterable)) {
+            const ops = def.ops.join(', ');
+            rootShape[`filter[${field}]`] = zod_1.z
+                .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+                .optional()
+                .meta({
+                description: `Filter on "${field}" (${def.type}). Supported operators: ${ops}. Format: "$op:value"`,
+                example: `${def.ops[0]}:value`,
+            });
+        }
+        rootShape.group = zod_1.z
+            .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+            .optional()
+            .meta({
+            description: 'Group definitions for complex filter logic. Format: "id:key=value,key=value". Keys: parent, join ($and/$or), op ($and/$or)',
+            example: '1:parent=0,join=$and',
+        });
+    }
     const baseQueryParamsSchema = zod_1.z
         .object(rootShape)
         .catchall(zod_1.z.unknown())
@@ -982,7 +1018,7 @@ function paginate(config) {
             ctx.addIssue({
                 code: 'custom',
                 path: ['groupDefs'],
-                message: `group.* is not allowed without any filter.*`,
+                message: `group is not allowed without any filter[*]`,
             });
         }
         else if (hasAnyFilter) {
@@ -1009,6 +1045,7 @@ function paginate(config) {
             ? { filters: buildWhereAstWithGroups(val.rawFilters, val.groupDefs) }
             : {};
         if (config.paginationType === 'LIMIT_OFFSET') {
+            const decorativeSelect = select?.filter((f) => decorativeSet.has(f));
             return {
                 pagination: {
                     type: 'LIMIT_OFFSET',
@@ -1016,6 +1053,7 @@ function paginate(config) {
                     page: val.page,
                     sortBy,
                     select,
+                    ...(decorativeSelect && decorativeSelect.length > 0 ? { decorativeSelect } : {}),
                     ...maybeFilters,
                 },
             };
@@ -1025,6 +1063,7 @@ function paginate(config) {
         if (val.cursor !== undefined) {
             cursor = coerceCursorFromProperty(config.dataSchema, config.cursorProperty, val.cursor);
         }
+        const decorativeSelect = select?.filter((f) => decorativeSet.has(f));
         return {
             pagination: {
                 type: 'CURSOR',
@@ -1033,6 +1072,7 @@ function paginate(config) {
                 cursorProperty: config.cursorProperty,
                 sortBy,
                 select,
+                ...(decorativeSelect && decorativeSelect.length > 0 ? { decorativeSelect } : {}),
                 ...maybeFilters,
             },
         };