@dudousxd/nestjs-filter 1.24.0 → 1.28.0

package/dist/runner.js

@@ -28,10 +28,25 @@ import { resolveDispatchTarget } from './input/dispatcher.js';
 import { normalizeInput } from './input/normalizer.js';
 import { parseSpatieInput } from './input/spatie-parser.js';
 import { validateInput } from './input/validator.js';
-import { normalizeOperator, validateColumnFilters } from './operators/validate-column-filter.js';
+import { isValidFieldPath, normalizeOperator, validateColumnFilters, } from './operators/validate-column-filter.js';
 import { buildKeyset, decodeCursor, encodeCursor, extractCursorValues, } from './pagination/cursor.js';
 import { CONTEXT_ACCESSOR, FILTER_ADAPTER, FILTER_MODULE_OPTIONS } from './tokens.js';
 const MATCH_ALL_SET = { has: () => true };
+/**
+ * Bars behind a range control when the request names no `buckets` count. Ten is
+ * what a slider-width strip of bars reads as; the exact number matters less
+ * than having one, because the alternative is a caller inventing a bucket WIDTH
+ * — which is the thing it cannot compute (see {@link FilterRunner.fieldHistogram}).
+ */
+const DEFAULT_HISTOGRAM_BUCKETS = 10;
+/**
+ * Ceiling on the requested bucket count. The SQL costs the same whatever the
+ * width is, but the RESULT does not: the runner materializes one entry per
+ * bucket including empty ones, so `buckets: 1e9` would be a gigabyte of JSON
+ * describing a control a thousand pixels wide. Clamped rather than rejected —
+ * the number is a rendering hint, not a semantic choice.
+ */
+const MAX_HISTOGRAM_BUCKETS = 1000;
 /**
  * Merges the inline `@Filterable.computed` map and `@Computed`-decorated
  * methods into a single alias → {@link ComputedRegistryEntry} registry.
@@ -300,7 +315,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         const { computed, applyComputed, computedUnsupported } = opts;
         const fields = this.remapFieldAliases(this.parseDistinct(rawFields), aliasMeta);
         if (fields.length === 0)
-            return false;
+            return [];
         // Split computed aliases and aggregate paths (both dev-declared or
         // synthesized, neither a real column — same rationale as computed sorts)
         // from plain column fields. Without the aggregate split, a path the
@@ -312,13 +327,19 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         const plainFields = computedAliases.length > 0 || aggregateFields.length > 0
             ? fields.filter((f) => !computed?.has(f) && parseAggregatePath(f) === null)
             : fields;
-        let applied = false;
+        // The fields that reached the projection, NOT the ones that were asked
+        // for: everything dropped on the way (failed validation, refused by the
+        // allowlist, an aggregate outside the auto-field set) has to stay out, so a
+        // caller can order by what this returns and still emit a legal
+        // `SELECT DISTINCT` — see `apply()`'s distinct-ordering fallback.
+        const applied = new Set();
         if (plainFields.length > 0) {
             if (apply && adapter && entity) {
                 const valid = this.validateDistinct(plainFields, allowed, adapter, entity, throwOnInvalid);
                 if (valid.length > 0) {
                     apply(qb, valid, entity);
-                    applied = true;
+                    for (const field of valid)
+                        applied.add(field);
                 }
             }
             else if (apply === undefined && unsupported) {
@@ -329,8 +350,8 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             if (applyComputed) {
                 for (const alias of computedAliases) {
                     applyComputed(qb, alias, computed.get(alias).source);
+                    applied.add(alias);
                 }
-                applied = true;
             }
             else if (computedUnsupported) {
                 this.warnUnsupported(computedUnsupported.feature, computedUnsupported.method);
@@ -351,14 +372,17 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                     if (!aggregatePath)
                         continue;
                     adapter.applyAggregateDistinct(qb, aggregatePath);
-                    applied = true;
+                    applied.add(field);
                 }
             }
             else {
                 this.warnUnsupported('Distinct on an aggregate field requested', 'applyAggregateDistinct');
             }
         }
-        return applied;
+        // Request order, not the order the three branches above ran in: the ORDER
+        // BY a caller derives from this should read like the projection the client
+        // asked for.
+        return fields.filter((field) => applied.has(field));
     }
     /**
      * Projects every `project: true` computed-registry entry into the SELECT
@@ -457,7 +481,17 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             const { plain: plainColumnFilters, computed: computedColumnFilters, aggregate: aggregateColumnFilters, } = this.splitSpecialColumnFilters(scopedColumnFilters, computedRegistry);
             // Apply column filters via adapter before @FilterFor dispatch
             if (plainColumnFilters.length > 0 && adapter?.applyColumnFilters) {
-                const opAllowed = this.enforceOperatorAllowlist(plainColumnFilters, normalizedAllowed, throwOnInvalidPolicy);
+                // Everything left in `plain` is claimed to be a real column path, so
+                // it has to actually BE one. Runs before the operator allowlist: a
+                // field the entity does not have has no operator policy to violate,
+                // and reporting "operator X is not allowed on ghostColumn" would
+                // name the wrong problem. Needs `entity` to check against — a filter
+                // class without `@Filterable` metadata keeps the pre-fix
+                // pass-through, same as every other metadata-dependent gate here.
+                const knownColumnFilters = filterableMeta?.entity
+                    ? this.pruneUnknownColumnFilters(plainColumnFilters, filterableMeta.entity, adapter, throwOnInvalidPolicy)
+                    : plainColumnFilters;
+                const opAllowed = this.enforceOperatorAllowlist(knownColumnFilters, normalizedAllowed, throwOnInvalidPolicy);
                 if (opAllowed.length > 0) {
                     validateColumnFilters(opAllowed);
                     adapter.applyColumnFilters(qb, opAllowed, filterableMeta?.entity);
@@ -679,7 +713,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             // A computed alias in the distinct list routes to applyComputedDistinct
             // (the computed registry bypasses column validation, like computed
             // sorts do); plain columns still batch through applyDistinct first.
-            const distinctApplied = this.applyProjection(qb, rawDistinct, {
+            const distinctFields = this.applyProjection(qb, rawDistinct, {
                 entity: filterableMeta?.entity,
                 adapter,
                 allowed: FilterClass.distinct,
@@ -716,7 +750,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             // Skipped when a distinct projection was applied: distinct replaces
             // entity-row output, and a computed value participates in a distinct
             // projection only by being listed in `distinct` explicitly.
-            if (!distinctApplied) {
+            if (distinctFields.length === 0) {
                 this.applyProjectedComputed(qb, computedRegistry, adapter);
             }
             // Apply sort — falling back to defaultSort when the client gave none.
@@ -726,9 +760,28 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             const sorts = parsedSorts.length > 0
                 ? parsedSorts
                 : this.parseSorts(this.resolveDefaultSort(FilterClass));
-            if (sorts.length > 0 && adapter?.applySort) {
+            // Opt-in last fallback (`distinctOrder`), for a DISTINCT projection
+            // nothing else ordered: sort ascending by what was projected. Off
+            // unless asked for — see `FilterableOptions.distinctOrder` for why the
+            // default is not to invent an ORDER BY.
+            //
+            // Derived from `distinctFields` (what the projection KEPT) rather than
+            // from the request, so every term is in the select list and the query
+            // stays legal under DISTINCT.
+            const effectiveSorts = sorts.length > 0
+                ? sorts
+                : this.resolveDistinctOrder(FilterClass, internal.distinctOrder)
+                    ? distinctFields.map((field) => ({ field, direction: 'asc' }))
+                    : [];
+            if (effectiveSorts.length > 0 && adapter?.applySort) {
                 const allowedSorts = FilterClass.sort;
-                this.applySortsWithComputed(qb, sorts, allowedSorts, adapter, filterableMeta?.entity, this.resolveThrowOnInvalid(FilterClass), computedRegistry, autoFieldSet);
+                this.applySortsWithComputed(qb, effectiveSorts, allowedSorts, adapter, filterableMeta?.entity, 
+                // NEVER throw for the derived ordering, whatever `throwOnInvalid`
+                // says: a `sort` the CLIENT sent is its request to get wrong, but
+                // this one it never asked for. A narrowed `static sort` allowlist
+                // that excludes a projected column must drop the ORDER BY, not turn
+                // an otherwise valid distinct request into a 400.
+                sorts.length > 0 ? this.resolveThrowOnInvalid(FilterClass) : false, computedRegistry, autoFieldSet);
             }
             // Apply pagination
             this.applyPagination(qb, rawPaginate, adapter);
@@ -812,6 +865,8 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                 distinct: undefined,
                 select: undefined,
                 groupByCount: undefined,
+                extent: undefined,
+                histogram: undefined,
                 paginate: undefined,
             };
         }
@@ -829,6 +884,8 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             'distinct',
             'select',
             'groupByCount',
+            'extent',
+            'histogram',
             'paginate',
         ];
         if (STRUCTURED_KEYS.some((k) => k in inputObj)) {
@@ -840,6 +897,8 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                 distinct: inputObj.distinct ?? undefined,
                 select: inputObj.select ?? undefined,
                 groupByCount: inputObj.groupByCount ?? undefined,
+                extent: inputObj.extent ?? undefined,
+                histogram: inputObj.histogram ?? undefined,
                 paginate: inputObj.paginate ?? undefined,
             };
         }
@@ -852,6 +911,8 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             distinct: undefined,
             select: undefined,
             groupByCount: undefined,
+            extent: undefined,
+            histogram: undefined,
             paginate: undefined,
         };
     }
@@ -1158,7 +1219,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             });
         }
         // Distinct projection (SELECT DISTINCT) — validate against entity metadata
-        this.applyProjection(qb, rawDistinct, {
+        const distinctFields = this.applyProjection(qb, rawDistinct, {
             entity,
             adapter,
             allowed: undefined,
@@ -1182,14 +1243,25 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             // Fall back to defaultSort when the client gave none.
             const parsedSorts = this.remapSortAliases(this.parseSorts(rawSort), filterableMeta);
             const sorts = parsedSorts.length > 0 ? parsedSorts : this.parseSorts(this.resolveDefaultSort());
-            if (sorts.length > 0 && adapter?.applySort) {
-                const validSorts = this.validateSorts(sorts, undefined, adapter, entity, throwOnInvalid);
+            // Same distinct-ordering fallback `apply()` has, for the same reason —
+            // dynamic mode's DISTINCT is no more ordered than a filter class's. Here
+            // the caller IS the call site (there is no route decorator and no filter
+            // class), so the per-call flag is the only way in.
+            const effectiveSorts = sorts.length > 0
+                ? sorts
+                : internal.distinctOrder
+                    ? distinctFields.map((field) => ({ field, direction: 'asc' }))
+                    : [];
+            if (effectiveSorts.length > 0 && adapter?.applySort) {
+                // `throwOnInvalid` only for a sort the CLIENT sent — the derived one
+                // drops instead of failing a request that never asked for it.
+                const validSorts = this.validateSorts(effectiveSorts, undefined, adapter, entity, sorts.length > 0 ? throwOnInvalid : false);
                 if (validSorts.length > 0) {
                     adapter.applySort(qb, validSorts);
                 }
             }
             // Pagination
-            this.applyPagination(qb, rawPaginate, adapter);
+            this.applyPagination(qb, rawPaginate, adapter, internal.trustedPageSize === true);
         }
         return qb;
     }
@@ -1205,6 +1277,14 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      *
      * Requires an adapter implementing `getResultAndCount` (and `populate` for
      * to-many includes). `applyDynamic` is unchanged; this is additive.
+     *
+     * `opts.trustedPageSize` declares that `paginate.size` was written by the
+     * server, not received from a client, and lifts the module-level
+     * `maxPageSize` ceiling for this call — see
+     * {@link FilterRunner.resolvePageSize}. This is the entry point exports and
+     * batch jobs use, so it is where the escape hatch is needed; without it they
+     * abandon `paginate` for hand-built `limit`/`offset` and lose everything
+     * else this method does.
      */
     async findAndCount(entity, input, opts = {}) {
         const adapter = this.resolveAdapter();
@@ -1225,7 +1305,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             select: structured.select,
             paginate: structured.paginate,
             include: joinIncludes,
-        }, qb, opts.context, { native: true });
+        }, qb, opts.context, { native: true, trustedPageSize: opts.trustedPageSize === true });
         if (distinctFields.length > 0) {
             if (!adapter?.getDistinctResultAndCount) {
                 throw new Error('findAndCount requires an adapter that implements getDistinctResultAndCount() for distinct projections.');
@@ -1377,6 +1457,473 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             : undefined;
         return { field: obj.field, ...(bucket !== undefined && { bucket }) };
     }
+    /**
+     * **Field extent**: the `MIN`/`MAX` of the requested field(s) over the rows
+     * the active `where`/`search` select — what a range control (numeric slider,
+     * date-range calendar) needs before it can place its endpoints. Reads the
+     * `extent` structured key (`{ extent: ['price', 'createdAt'] }`, or the
+     * comma-separated string a GET route carries, parsed exactly like `distinct`).
+     *
+     * Unlike {@link groupByCount} this is NOT terminal — it measures the same
+     * filtered set the rows come from, so a route answers with rows AND extent
+     * from two builders. Sort/pagination/distinct/select are not part of the
+     * question and are not applied (`skipSortAndPagination`).
+     *
+     * **Why this lives in the runner and not in the route.** Reading
+     * `@Body('extent')` and handing it straight to `adapter.fieldExtent` bypasses
+     * the filter class's field governance: `static distinct` narrowing, the
+     * entity-metadata check that rejects a bare relation or an unknown
+     * identifier, and the alias remapping every other key gets. That is not an
+     * injection hole — the adapter resolves names through ORM metadata — but it
+     * IS a surface leak: a caller could measure a column the filter class
+     * deliberately does not expose. Routing every requested field through
+     * {@link validateDistinct} here closes it, and it is also the only place
+     * that can tell a computed alias from a typo (see below).
+     *
+     * **Allowlist.** The same one `distinct` uses: the filter class's static
+     * `distinct` list when `opts.filterClass` declares one, else the entity's
+     * columns via adapter metadata. `distinct` and `extent` answer the same
+     * question about a column — what values can this control offer — so a class
+     * that has already narrowed which columns a control may read must narrow
+     * this too, or `extent` becomes the way around that narrowing.
+     *
+     * **Disallowed/unknown fields are DROPPED**, and the request still answers
+     * for the fields that survived — matching `distinct` (which drops an invalid
+     * projected field rather than failing the query) rather than `groupByCount`
+     * (which always rejects, because there the field IS the whole query). Under
+     * the ambient `throwOnInvalid` policy the drop becomes a
+     * `BadRequestException`, again as `distinct`. A dropped field is simply
+     * absent from the result, which the `fieldExtent` contract already defines as
+     * "not measured" — the caller cannot tell it apart from a field the adapter
+     * could not resolve, and does not need to.
+     *
+     * **Computed members** route as `{ alias, source }` rather than a bare name,
+     * mirroring {@link groupByCount}'s grouping field: the adapter measures the
+     * dev-provided expression instead of resolving a column that does not exist.
+     * The registry comes from `opts.filterClass` when given, else from
+     * `@Filterable` metadata on the entity itself. Computed aliases bypass column
+     * validation — dev-declared, never client input — exactly like computed
+     * sort/distinct.
+     *
+     * Requires an adapter implementing the optional `fieldExtent` method; when
+     * absent, a clear error is thrown rather than a silent empty answer, which a
+     * range control would render as a collapsed (0, 0) span.
+     *
+     * @returns One entry per measured field keyed by field name (or computed
+     *   alias). `{}` when the request named no extent fields at all.
+     */
+    async fieldExtent(entity, input, opts = {}) {
+        const structured = this.extractStructuredInput(input);
+        // Same parser as `distinct`: the client sends an array on a POST body and a
+        // comma-joined string on a GET query, and both mean the same list.
+        const requested = this.parseDistinct(structured.extent);
+        // No `extent` key is not an error — a route can call this unconditionally
+        // alongside its rows read and get nothing back when nobody asked.
+        if (requested.length === 0)
+            return {};
+        const adapter = this.resolveAdapter();
+        if (!adapter?.fieldExtent) {
+            throw new Error('extent is not supported by the active adapter (it does not implement fieldExtent()).');
+        }
+        // Aliases resolve against the filter class when one is given (its `aliases`
+        // are what the client was told to use), else against entity-level metadata
+        // — the same fallback dynamic mode uses everywhere else.
+        const aliasMeta = getFilterableMetadata(opts.filterClass ?? entity);
+        const fields = this.remapFieldAliases(requested, aliasMeta);
+        // Registry source mirrors groupByCount's: the DI-resolved filter class when
+        // given (so `@Computed` methods bind), else `@Filterable` declared on the
+        // entity itself, which is all dynamic mode has.
+        const entityProto = Object.create(entity.prototype);
+        const computedRegistry = opts.filterClass
+            ? buildComputedRegistry(opts.filterClass, await this.resolveFilter(opts.filterClass))
+            : buildComputedRegistry(entity, entityProto);
+        const allowlist = this.resolveDistinctAllowlist(opts.filterClass);
+        const throwOnInvalid = this.resolveThrowOnInvalid(opts.filterClass);
+        const targets = [];
+        for (const field of fields) {
+            const target = this.resolveMeasurableField(field, entity, adapter, allowlist, computedRegistry);
+            if (!target) {
+                // The rejection message names `extent` instead of borrowing distinct's
+                // — the policy (drop, or throw when configured to) is still distinct's,
+                // just worded for the key the client actually sent.
+                if (throwOnInvalid) {
+                    throw new BadRequestException(`Invalid extent field: "${field}".`);
+                }
+                continue;
+            }
+            targets.push(target);
+        }
+        // Everything was dropped — the adapter is not called at all. An empty
+        // `fields` list would otherwise be a `SELECT` with no aggregates.
+        if (targets.length === 0)
+            return {};
+        const qb = opts.qb ?? adapter.createQueryBuilder(entity);
+        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, opts.context, { skipSortAndPagination: true, native: true });
+        return adapter.fieldExtent(qb, targets, entity);
+    }
+    /**
+     * Resolves ONE requested field to the shape an adapter measurement takes: the
+     * `{ alias, source }` pair of a computed member, or the validated column
+     * name. `null` when it is neither.
+     *
+     * Shared by {@link fieldExtent} and {@link fieldHistogram} so both obey the
+     * same allowlist, and so the one judgement nothing outside the runner can
+     * make — computed alias, or typo? both are strings no column matches — is
+     * made once. What the two callers differ on is only what `null` MEANS (a
+     * dropped field there, a rejected request here), which is why that decision
+     * stays with them.
+     *
+     * Validation runs with `throwOnInvalid: false` unconditionally: the caller
+     * words its own rejection for the key the client actually sent, rather than
+     * surfacing `Invalid distinct field` for a request that never said `distinct`.
+     */
+    resolveMeasurableField(field, entity, adapter, allowlist, computedRegistry) {
+        const computedEntry = computedRegistry.get(field);
+        if (computedEntry)
+            return { alias: field, source: computedEntry.source };
+        const validated = this.validateDistinct([field], allowlist, adapter, entity, false);
+        return validated[0] ?? null;
+    }
+    /**
+     * A fresh builder carrying the request's WHERE/search and nothing else — the
+     * scope every measurement in this file asks its question over.
+     *
+     * `skipSortAndPagination` is the load-bearing part: an aggregate over a
+     * LIMITed builder answers for a page and looks exactly like an answer for the
+     * set, and an ORDER BY on a column an aggregate SELECT no longer projects is
+     * MySQL error 3065.
+     */
+    async buildFilteredQb(entity, structured, adapter, context) {
+        const qb = adapter.createQueryBuilder(entity);
+        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, context, { skipSortAndPagination: true, native: true });
+        return qb;
+    }
+    /**
+     * The static `distinct` allowlist declared on a filter class, if any — the
+     * one {@link applyProjection} gates the DISTINCT projection with, reused by
+     * {@link fieldExtent} so both reads of a column obey the same narrowing.
+     *
+     * Read defensively rather than through a cast: `static distinct` is a plain
+     * class property no type checks, so a class can carry anything under that
+     * name. A non-array (or a list holding non-strings) yields `undefined`/the
+     * string entries, which degrades to entity-metadata validation instead of
+     * silently comparing field names against garbage and refusing everything.
+     */
+    resolveDistinctAllowlist(FilterClass) {
+        if (!FilterClass)
+            return undefined;
+        const declared = Reflect.get(FilterClass, 'distinct');
+        if (!Array.isArray(declared))
+            return undefined;
+        return declared.filter((entry) => typeof entry === 'string');
+    }
+    /**
+     * **Field histogram**: one numeric field's extent AND its bucketed
+     * distribution over the same filtered set — the two halves of a faceted range
+     * control, from one request. Reads the `histogram` structured key
+     * (`{ histogram: { field: 'price', buckets: 20 } }`).
+     *
+     * **Why this is a method and not two calls in a route.** The halves already
+     * exist — {@link fieldExtent} places a slider's endpoints,
+     * {@link FilterAdapter.groupByCount}'s bucketed variant draws the
+     * distribution behind them — but they are circular for the caller: the
+     * bucketed variant needs a WIDTH, and a width that is not derived from the
+     * data is either arbitrary (a hardcoded 1000 that yields two bars on one
+     * filter and four hundred on the next) or requires the extent the caller is
+     * asking for in the same breath. Nobody can break that cycle from outside:
+     * you must measure, then divide. So the runner measures, then divides.
+     *
+     * **Two round trips, and it cannot be one.** The width is a function of the
+     * first query's OUTPUT, so the second query's text does not exist until the
+     * first has returned. Folding them into one statement means either a
+     * correlated `(SELECT MAX(col)) - (SELECT MIN(col))` inside the bucket
+     * expression — the same scan twice, once per row-group, to avoid a round trip
+     * — or window functions the adapter contract does not have. Two plain
+     * aggregate queries over an indexable column is the cheaper shape, and it
+     * keeps this a composition of capabilities adapters already implement.
+     *
+     * **Not on the adapter contract, deliberately.** Every optional method added
+     * to `FilterAdapter` is a cost each adapter author pays forever, and this one
+     * would buy nothing: it is arithmetic between two existing calls, identical
+     * for every ORM. An adapter implementing `fieldExtent` and `groupByCount`
+     * gets this for free, and one implementing neither is told which is missing.
+     *
+     * **No `opts.qb`**, unlike its neighbours. Two passes need two builders — the
+     * first is consumed by an aggregate SELECT — and a single caller-supplied
+     * builder can only serve one of them. Silently creating a fresh builder for
+     * the second pass would drop whatever pre-scoping the caller put on theirs,
+     * so the distribution would describe a WIDER set than the extent: a chart
+     * with bars outside its own axis, and nothing to make it obvious.
+     *
+     * Field governance is {@link fieldExtent}'s, through the same
+     * {@link resolveMeasurableField}: alias remapping, the filter class's static
+     * `distinct` allowlist (else entity metadata), and computed members routed as
+     * `{ alias, source }`. The one divergence is what an invalid field means —
+     * rejected here, as in {@link groupByCount}, because the field IS the query
+     * and there is no partial answer to fall back to.
+     *
+     * **Dates are refused, not bucketed.** `fieldExtent` supports DATE columns on
+     * purpose, but bucketing is `FLOOR(value / width)`, and a date divided by a
+     * number is nonsense that no database announces: MySQL coerces the column to
+     * `20240131` and buckets THAT, which produces plausible-looking bars over an
+     * axis that skips two thirds of every year. See {@link assertBucketable}.
+     *
+     * @returns `{ min, max, bucketWidth, buckets }` — null ends and an empty
+     *   bucket list when no row in scope carries a value.
+     */
+    async fieldHistogram(entity, input, opts = {}) {
+        const structured = this.extractStructuredInput(input);
+        const spec = this.parseHistogram(structured.histogram);
+        if (!spec) {
+            throw new BadRequestException('histogram requires a `{ field }` specification (with an optional positive `buckets` count).');
+        }
+        const adapter = this.resolveAdapter();
+        // Named separately: an adapter can plausibly have one and not the other,
+        // and "histogram is unsupported" would send its author looking for a method
+        // by that name, which does not and will not exist.
+        if (!adapter?.fieldExtent) {
+            throw new Error('histogram is not supported by the active adapter (it does not implement fieldExtent()).');
+        }
+        if (!adapter.groupByCount) {
+            throw new Error('histogram is not supported by the active adapter (it does not implement groupByCount()).');
+        }
+        // Aliases against the filter class when one is given, else entity-level
+        // metadata — the fallback dynamic mode uses everywhere else.
+        const aliasMeta = getFilterableMetadata(opts.filterClass ?? entity);
+        const [remapped] = this.remapFieldAliases([spec.field], aliasMeta);
+        const field = remapped ?? spec.field;
+        const entityProto = Object.create(entity.prototype);
+        const computedRegistry = opts.filterClass
+            ? buildComputedRegistry(opts.filterClass, await this.resolveFilter(opts.filterClass))
+            : buildComputedRegistry(entity, entityProto);
+        const target = this.resolveMeasurableField(field, entity, adapter, this.resolveDistinctAllowlist(opts.filterClass), computedRegistry);
+        // Rejected regardless of the ambient `throwOnInvalid`, exactly as
+        // `groupByCount` rejects its grouping field: dropping the only field there
+        // is would leave an empty histogram that reads as "no matching rows".
+        if (!target) {
+            throw new BadRequestException(`Invalid histogram field: "${spec.field}".`);
+        }
+        this.assertBucketable(target, entity, adapter);
+        // ── pass 1: where do the endpoints sit ───────────────────────────────────
+        const extentQb = await this.buildFilteredQb(entity, structured, adapter, opts.context);
+        const measured = await adapter.fieldExtent(extentQb, [target], entity);
+        const key = typeof target === 'string' ? target : target.alias;
+        const bounds = measured[key];
+        // The `fieldExtent` contract defines an ABSENT key as "the adapter could not
+        // turn this into an expression". The field passed validation, so that is a
+        // metadata disagreement, not a client mistake — and it must not be reported
+        // as `{ min: null }`, which the same contract defines as "no row carries a
+        // value" and which a control would render as a legitimately empty facet.
+        if (!bounds) {
+            throw new Error(`histogram could not measure "${key}": the active adapter's fieldExtent() returned no entry for it.`);
+        }
+        const min = this.toBucketableNumber(bounds.min, key);
+        const max = this.toBucketableNumber(bounds.max, key);
+        // Empty set, or a column that is null throughout it. No second query: there
+        // is nothing to bin, and a width derived from null is NaN — which reaches
+        // SQL as `FLOOR(col / NaN)` and groups every row into one null bucket.
+        if (min === null || max === null) {
+            return { min: null, max: null, bucketWidth: null, buckets: [] };
+        }
+        // ── pass 2: how are the rows distributed across them ─────────────────────
+        const countQb = await this.buildFilteredQb(entity, structured, adapter, opts.context);
+        // Degenerate span: one row, or many rows sharing one value. A width of
+        // (max - min) / n is 0, and `FLOOR(col / 0)` is a null group on MySQL and a
+        // division-by-zero ERROR on Postgres — so the bucketed variant must not be
+        // asked for at all. The plain group-by answers instead: with a single
+        // distinct value it returns that one group, whose count is the bar's
+        // height. The bucket is reported as the point `[min, min]` rather than
+        // given a fabricated width, which would draw a bar spanning values no row
+        // in scope has.
+        if (min === max) {
+            const rows = await adapter.groupByCount(countQb, target, entity);
+            const count = rows.reduce((sum, row) => row.value === null || row.value === undefined ? sum : sum + Number(row.count), 0);
+            return { min, max, bucketWidth: 0, buckets: [{ bucketStart: min, bucketEnd: min, count }] };
+        }
+        const bucketWidth = this.niceBucketWidth(max - min, spec.buckets ?? DEFAULT_HISTOGRAM_BUCKETS);
+        const rows = await adapter.groupByCount(countQb, target, entity, { bucket: bucketWidth });
+        return { min, max, bucketWidth, buckets: this.assembleBuckets(min, max, bucketWidth, rows) };
+    }
+    /**
+     * Parses the raw `histogram` block into a canonical `{ field, buckets }`.
+     * `null` when no usable `field` is present — the caller rejects, since a
+     * histogram of nothing has no meaningful empty answer.
+     *
+     * `buckets` accepts a numeric string as well as a number: on a GET route
+     * `?histogram[buckets]=20` arrives as text, and rejecting it there while
+     * accepting `20` from a POST body would make the two transports disagree
+     * about the same request. Anything unusable (absent, zero, negative, NaN,
+     * an object) degrades to the default rather than 400ing: it is a rendering
+     * hint, and a request that says nothing about bar count still has an answer.
+     */
+    parseHistogram(raw) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            return null;
+        const field = Reflect.get(raw, 'field');
+        if (typeof field !== 'string' || field.length === 0)
+            return null;
+        const rawBuckets = Reflect.get(raw, 'buckets');
+        const parsed = typeof rawBuckets === 'string'
+            ? Number(rawBuckets)
+            : typeof rawBuckets === 'number'
+                ? rawBuckets
+                : Number.NaN;
+        const buckets = Number.isFinite(parsed) && parsed >= 1
+            ? Math.min(Math.floor(parsed), MAX_HISTOGRAM_BUCKETS)
+            : DEFAULT_HISTOGRAM_BUCKETS;
+        return { field, buckets };
+    }
+    /**
+     * Refuses a field whose column type cannot survive `FLOOR(value / width)`,
+     * BEFORE either query runs.
+     *
+     * A DATE column is the case this exists for. `fieldExtent` supports dates
+     * deliberately (a calendar sizes itself from one), so `extent` and
+     * `histogram` accept the same field names right up to this point — and the
+     * failure mode without the check is not an error but a wrong answer: MySQL
+     * coerces a date to `20240131` before dividing, so the query succeeds and
+     * returns bars over an axis where two thirds of every year does not exist.
+     *
+     * Only ROOT-column metadata can answer this, so anything it cannot type — a
+     * relation path, a JSON sub-path, a computed source — passes here and is
+     * caught by {@link toBucketableNumber} once the extent comes back with actual
+     * values. Refusing everything untypeable instead would reject `author.age`,
+     * which `where`, `sort` and `distinct` all accept.
+     */
+    assertBucketable(target, entity, adapter) {
+        if (typeof target !== 'string')
+            return;
+        const info = adapter.getEntityFields?.(entity)?.find((f) => f.name === target);
+        if (!info || info.type === 'number' || info.type === 'unknown')
+            return;
+        throw new BadRequestException(`Invalid histogram field: "${target}" is a ${info.type} column and histogram buckets are numeric (FLOOR(value / width)). Use \`extent\` for its range, or \`groupByCount\` to group by its values.`);
+    }
+    /**
+     * Coerces one measured extent end to the number the width arithmetic needs,
+     * or `null` for "no row carries a value".
+     *
+     * Not a `typeof value === 'number'` check, in either direction:
+     *
+     *  - a DECIMAL column hydrates to a STRING on mysql2 and pg, so the strict
+     *    check would refuse the most ordinary histogram there is — a price;
+     *  - `Number(new Date())` is a finite epoch, so a bare numeric coercion would
+     *    wave a date extent straight through into `FLOOR(ms / width)`. Dates are
+     *    therefore tested for FIRST, by identity, not by what they coerce to.
+     *
+     * This is the net under {@link assertBucketable}, which only sees root-column
+     * metadata: a computed source, a relation path or a JSON sub-path is typed by
+     * nothing until its value arrives here.
+     */
+    toBucketableNumber(value, field) {
+        if (value === null || value === undefined)
+            return null;
+        if (value instanceof Date) {
+            throw new BadRequestException(`Invalid histogram field: "${field}" measures dates and histogram buckets are numeric (FLOOR(value / width)). Use \`extent\` for its range.`);
+        }
+        const numeric = typeof value === 'number' || typeof value === 'bigint' || typeof value === 'string'
+            ? Number(value)
+            : Number.NaN;
+        if (!Number.isFinite(numeric)) {
+            throw new BadRequestException(`Invalid histogram field: "${field}" did not measure to a finite number, so it cannot be bucketed.`);
+        }
+        return numeric;
+    }
+    /**
+     * Derives a bucket width from the measured span and the desired bar count,
+     * snapped to the nearest 1/2/5 × 10ⁿ step.
+     *
+     * The raw `span / desired` is the arithmetically correct width and the wrong
+     * answer for a control. Two reasons, both visible to a user:
+     *
+     *  - buckets are anchored at multiples of the width (`FLOOR(col / w) * w`,
+     *    which the adapter capability defines and which is what lets the grouping
+     *    be one expression), so an ugly width means ugly edges: a span of
+     *    499–128000 over 10 gives 12750.1, and axis labels at 12750.1, 25500.2,
+     *    38250.3;
+     *  - a raw width changes on every row inserted, so the bars re-partition and
+     *    visibly jump whenever the filtered set shifts slightly. A snapped width
+     *    holds still across a range of spans, which is the hysteresis a facet
+     *    that redraws on every keystroke needs.
+     *
+     * Snapped to the NEAREST step in log space (the √2 / √10 / √50 thresholds),
+     * not upward: rounding up turns a span of 101 over 10 buckets into a width of
+     * 20 and six bars, which is a worse lie about the request than eleven bars.
+     * The count therefore lands within about √2 of `desired` in either direction
+     * — `buckets` is a target, and the returned `bucketWidth` is authoritative.
+     *
+     * `span` is strictly positive here: the `min === max` case never reaches this.
+     */
+    niceBucketWidth(span, desired) {
+        const raw = span / desired;
+        const magnitude = 10 ** Math.floor(Math.log10(raw));
+        const normalized = raw / magnitude; // [1, 10)
+        const step = normalized >= Math.sqrt(50)
+            ? 10
+            : normalized >= Math.sqrt(10)
+                ? 5
+                : normalized >= Math.SQRT2
+                    ? 2
+                    : 1;
+        return step * magnitude;
+    }
+    /**
+     * Turns the adapter's sparse `{ value, count }` groups into the contiguous
+     * ascending bucket list a chart draws.
+     *
+     * Three things the raw groups get wrong for this purpose:
+     *
+     *  - **Nulls.** A row whose column is null groups under `FLOOR(NULL / w)`,
+     *    which is NULL — and `Number(null)` is 0, so passing the groups through
+     *    unfiltered plants a phantom bar at zero holding every null row.
+     *  - **Order.** `GROUP BY` has no defined output order. A histogram is a
+     *    sequence, and bars drawn in the order MySQL happened to hash them are
+     *    not a distribution.
+     *  - **Gaps.** Empty buckets produce no group at all, so a sparse list renders
+     *    as evenly spaced bars that lie about where the data sits. They are
+     *    filled with zero-count entries, which is bounded work: the bucket count
+     *    is `span / width`, and the width came from a clamped desired count.
+     *
+     * Groups are matched to buckets by INDEX rather than by comparing the
+     * returned `value` to a computed edge: for a width like 0.1 the database's
+     * `FLOOR(x / 0.1) * 0.1` and this code's `i * 0.1` differ in the last bits,
+     * and an equality match would silently drop those buckets to zero.
+     */
+    assembleBuckets(min, max, width, rows) {
+        const firstIndex = Math.floor(min / width);
+        const size = Math.floor(max / width) - firstIndex + 1;
+        const counts = new Array(size).fill(0);
+        for (const row of rows) {
+            if (row.value === null || row.value === undefined)
+                continue;
+            const start = Number(row.value);
+            if (!Number.isFinite(start))
+                continue;
+            const index = Math.round(start / width) - firstIndex;
+            // Out of range means the grouping expression and this arithmetic disagree
+            // about the field — dropped rather than widening the axis to fit it.
+            if (index < 0 || index >= size)
+                continue;
+            counts[index] = (counts[index] ?? 0) + Number(row.count);
+        }
+        return counts.map((count, i) => {
+            const bucketStart = this.snapEdge((firstIndex + i) * width, width);
+            return { bucketStart, bucketEnd: this.snapEdge(bucketStart + width, width), count };
+        });
+    }
+    /**
+     * Rounds a bucket edge to the decimal precision its width implies. Every edge
+     * is an exact multiple of a 1/2/5 × 10ⁿ width, so this cannot move one onto a
+     * different bucket — it only sheds the binary-float residue that otherwise
+     * labels an axis `0.30000000000000004`. Skipped entirely for widths outside
+     * `toFixed`'s useful range, where rounding would destroy information rather
+     * than tidy it.
+     */
+    snapEdge(value, width) {
+        const decimals = -Math.floor(Math.log10(width));
+        if (!Number.isFinite(decimals) || decimals < 0 || decimals > 15)
+            return value;
+        return Number(value.toFixed(decimals));
+    }
     /**
      * Runs a dynamic query with **keyset (cursor) pagination** and executes it,
      * returning a stable, non-overlapping page plus opaque forward/backward
@@ -1395,6 +1942,13 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * Requires an adapter implementing `getResult`, `getPrimaryKey`,
      * `applyKeysetPagination` and `applyKeysetOrderAndLimit`. Additive — does not
      * change `apply`/`applyDynamic`/`findAndCount`.
+     *
+     * `opts.trustedPageSize` lifts the module-level `maxPageSize` ceiling off
+     * `first`/`last` for this call — same meaning as on {@link findAndCount},
+     * and it belongs here for the same reason: keyset paging is the pagination a
+     * long server-side walk SHOULD use (it is stable under concurrent writes),
+     * so capping it would leave the recommended export path as the one that
+     * cannot opt out.
      */
     async findPage(entity, input, opts = {}) {
         const adapter = this.resolveAdapter();
@@ -1414,9 +1968,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         const before = after === undefined && typeof paginate.before === 'string' ? paginate.before : undefined;
         const backward = before !== undefined;
         const cursorStr = after ?? before;
-        const maxSize = this.options.maxPageSize ?? 100;
-        const requested = backward ? Number(paginate.last) : Number(paginate.first);
-        const limit = Math.min(Math.max(1, requested || 25), maxSize);
+        const limit = this.resolvePageSize(backward ? paginate.last : paginate.first, opts.trustedPageSize === true);
         // Resolve the effective sort (falling back to defaultSort) and validate it
         // against entity metadata, then append the primary key as a tiebreaker.
         const parsedSorts = this.remapSortAliases(this.parseSorts(structured.sort), filterableMeta);
@@ -1502,40 +2054,117 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * Drops `where` column-filter clauses whose field is not a known scalar
      * column, relation, or dotted relation path on the entity — so a client
      * filter on an absent column (e.g. a base-scope `baseId` on a base-less
-     * table) is silently ignored instead of crashing the ORM. Recurses AND/OR.
-     * No-op (pass-through) when the adapter exposes no metadata.
+     * table) is dropped instead of crashing the ORM. Recurses AND/OR.
+     *
+     * The grammar check (`validateColumnFilters` → `isValidFieldPath`) only
+     * proves the field name is SQL-SAFE, not that it EXISTS: `ghostColumn`
+     * satisfies the pattern, sails through the operator allowlist, and blows up
+     * inside the ORM. That surfaces as a 500 for the consumer, and as a mid-run
+     * failure for a background job — both worse than not applying a constraint
+     * the entity cannot express in the first place.
+     *
+     * **Policy knob: `throwOnInvalid`, not `onUnknownKey`.** Three reasons, in
+     * order of weight: (1) `FilterModuleOptions.throwOnInvalid` is already
+     * DOCUMENTED as covering "unknown `where` columns" — static mode was simply
+     * never wired to it; (2) `applyDynamic` already routes this same function
+     * through `throwOnInvalid`, so choosing the other knob would recreate, in a
+     * new place, the very static-vs-dynamic asymmetry this fix closes; (3)
+     * `throwOnInvalid` is overridable per-`@Filterable`, while `onUnknownKey` is
+     * module-global — and whether a stray `where` column is a client bug or a
+     * tolerated legacy payload is a per-endpoint judgement. `onUnknownKey` keeps
+     * its own scope: keys of the STRUCTURED filter object, which are dispatch
+     * targets (`@FilterFor` / auto-field / relation), not column references.
+     *
+     * Default (`throwOnInvalid: false`) is drop-with-a-warning rather than a
+     * 400: it is the change that stops the crash without turning requests that
+     * work today into errors, and the warning names the field so the drop is
+     * observable rather than silent. Mirrors
+     * {@link pruneBlacklistedColumnFilters}, which made the same call.
+     *
+     * Falls back to accept-all (with a warning) when the adapter exposes no
+     * metadata — the same graceful degradation `resolveAutoFields` uses, so an
+     * adapter that cannot introspect keeps its pre-fix behavior instead of
+     * having every `where` clause dropped.
      */
     pruneUnknownColumnFilters(filters, entity, adapter, throwOnInvalid = false) {
         const fieldNames = new Set((adapter.getEntityFields?.(entity) ?? []).map((f) => f.name));
         const relationNames = new Set((adapter.getEntityRelations?.(entity) ?? []).map((r) => r.name));
-        if (fieldNames.size === 0 && relationNames.size === 0)
+        if (fieldNames.size === 0 && relationNames.size === 0) {
+            this.logger.warn(`where[] column filters on ${entity.name} cannot be validated against entity metadata. The adapter does not implement getEntityFields() or returned null. All where columns will be accepted (legacy behavior). Consider upgrading your adapter.`);
             return filters;
+        }
         // When the adapter can resolve relation paths, validate the full chain
         // (`author.profile.country`) so a bad deep path is dropped instead of
         // reaching the ORM as an unknown column. Both scalar leaves and bare
         // relations (FK / nested constraints) are filterable. Otherwise fall back
-        // to a single-hop check (scalar, bare relation, or `relation.field`).
+        // to a single-hop check on the path's ROOT segment.
+        //
+        // The fallback accepts a dotted path rooted at a scalar column too, not
+        // just at a relation: `metadata.tier` is a JSON sub-path, and an adapter
+        // without `resolveFieldPath` cannot tell a JSON column from any other
+        // scalar. Refusing it would turn "we can't check this" into "this is
+        // wrong" and break JSON filtering on exactly the adapters least able to
+        // defend themselves.
+        //
+        // `[]` is stripped first: it is the JSON-array traversal marker
+        // (`problems.checks[].field`, see `parseFieldPath`), never part of a
+        // column name, so leaving it in would fail every lookup it appears in.
+        const rootOf = (field) => {
+            const dot = field.indexOf('.');
+            const root = dot > 0 ? field.slice(0, dot) : field;
+            return root.endsWith('[]') ? root.slice(0, -2) : root;
+        };
         const isKnown = adapter.resolveFieldPath
-            ? (field) => adapter.resolveFieldPath(entity, field) !== null
+            ? (field) => adapter.resolveFieldPath(entity, field.replaceAll('[]', '')) !== null
             : (field) => {
-                if (fieldNames.has(field) || relationNames.has(field))
-                    return true;
-                const dot = field.indexOf('.');
-                return dot > 0 && relationNames.has(field.slice(0, dot));
+                const root = rootOf(field);
+                return fieldNames.has(root) || relationNames.has(root);
             };
+        const warned = new Set();
         const prune = (clauses) => clauses
-            .filter((clause) => {
-            const known = !clause.field || isKnown(clause.field);
-            if (!known && throwOnInvalid) {
+            .map((clause) => {
+            const AND = clause.AND ? prune(clause.AND) : undefined;
+            const OR = clause.OR ? prune(clause.OR) : undefined;
+            const withGroups = {
+                ...clause,
+                ...(AND ? { AND } : {}),
+                ...(OR ? { OR } : {}),
+            };
+            // A MALFORMED path (`visits.$notafn`, anything outside the SQL-safe
+            // grammar) is deliberately passed through untouched, not dropped:
+            // `validateColumnFilters` downstream rejects it loudly, and that
+            // rejection is a safety guarantee. Quietly swallowing SQL-unsafe
+            // input here would trade a hard error for silence — this prune
+            // answers "does this column exist", never "is this path legal".
+            if (!clause.field || !isValidFieldPath(clause.field) || isKnown(clause.field)) {
+                return withGroups;
+            }
+            if (throwOnInvalid) {
                 throw new BadRequestException(`Unknown filter column: "${clause.field}".`);
             }
-            return known;
+            if (!warned.has(clause.field)) {
+                warned.add(clause.field);
+                this.logger.warn(`Column filter (where) on unknown column "${clause.field}" ignored — it is not a field or relation of ${entity.name}.`);
+            }
+            // The unknown LEAF goes; a group the clause carried stays. Dropping
+            // the clause wholesale would take its children's constraints with
+            // it, WIDENING the query — returning rows the client filtered out is
+            // a worse failure than the 500 this replaces.
+            if (AND?.length || OR?.length) {
+                return {
+                    ...(AND?.length ? { AND } : {}),
+                    ...(OR?.length ? { OR } : {}),
+                };
+            }
+            return null;
         })
-            .map((clause) => ({
-            ...clause,
-            ...(clause.AND && { AND: prune(clause.AND) }),
-            ...(clause.OR && { OR: prune(clause.OR) }),
-        }));
+            .filter((clause) => clause !== null)
+            // Collapse group nodes (no field of their own) emptied by pruning —
+            // an empty `{ OR: [] }` reaching the adapter is a condition with no
+            // operands, which each ORM renders differently and none usefully.
+            .filter((clause) => Boolean(clause.field) ||
+            Boolean(clause.AND && clause.AND.length > 0) ||
+            Boolean(clause.OR && clause.OR.length > 0));
         return prune(filters);
     }
     /**
@@ -1820,6 +2449,32 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         }
         return this.options.defaultSort;
     }
+    /**
+     * Resolves the effective `distinctOrder`: the ROUTE's own
+     * `@ApplyFilter({ distinctOrder })` wins over the filter class's
+     * `@Filterable({ distinctOrder })`, and absent both it is off.
+     *
+     * There is deliberately no module-level knob. Whether a `SELECT DISTINCT`
+     * wants an ORDER BY is a property of the endpoint reading it — one filter
+     * class typically serves a rows route that orders itself and a distinct route
+     * that does not — so an app-wide switch would be answering a question at the
+     * wrong altitude, and silently, for queries whose cost it cannot see.
+     *
+     * Off unless asked for, for the same reason: ordering a projection the caller
+     * never asked to order is a clause this library would be inventing, and on a
+     * large distinct with no index on the projected column that clause is a
+     * filesort nobody signed up for. See {@link FilterableOptions.distinctOrder}.
+     */
+    resolveDistinctOrder(FilterClass, perCall) {
+        if (perCall !== undefined)
+            return perCall;
+        if (FilterClass) {
+            const meta = getFilterableMetadata(FilterClass);
+            if (meta?.distinctOrder !== undefined)
+                return meta.distinctOrder;
+        }
+        return false;
+    }
     handleUnknownKey(key) {
         const policy = this.options.onUnknownKey ?? 'ignore';
         if (policy === 'throw')
@@ -1828,12 +2483,41 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             this.logger.warn(`Unknown filter key: "${key}"`);
         }
     }
+    /**
+     * Narrows an already-structured sort element. The `direction` check is the
+     * strict part: an unrecognised direction is dropped rather than coerced,
+     * because guessing `asc` for a client that asked for something else silently
+     * returns the wrong page of a paginated result.
+     */
+    isSortItem(item) {
+        if (item == null || typeof item !== 'object')
+            return false;
+        if (!('field' in item) || !('direction' in item))
+            return false;
+        return (typeof item.field === 'string' && (item.direction === 'asc' || item.direction === 'desc'));
+    }
+    /**
+     * Parses one `"-field"` / `"field"` token into a {@link SortItem}, or
+     * `undefined` when there is no field left after trimming (`""`, `"  "`,
+     * a bare `"-"`). Shared by both string shapes so a token means the same
+     * thing whether it arrived inside `"a,-b"` or as `["a", "-b"]`.
+     */
+    parseSortToken(token) {
+        const trimmed = token.trim();
+        const desc = trimmed.startsWith('-');
+        const field = desc ? trimmed.substring(1) : trimmed;
+        if (field.length === 0)
+            return undefined;
+        return { field, direction: desc ? 'desc' : 'asc' };
+    }
     /**
      * Parses raw sort input into an array of SortItem objects.
      *
      * Supports:
      * - String: `"-createdAt,name"` → `[{ field: 'createdAt', direction: 'desc' }, { field: 'name', direction: 'asc' }]`
+     * - Array of tokens: `["-createdAt", "name"]` — same token rules as the string form
      * - Array of SortItem objects: passed through as-is
+     * - Arrays mixing the two: each element is read by its own type
      * - Falsy values: returns empty array
      *
      * Minus prefix = desc, no prefix = asc (JSON:API convention).
@@ -1844,21 +2528,22 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         if (typeof raw === 'string') {
             return raw
                 .split(',')
-                .map((s) => s.trim())
-                .filter(Boolean)
-                .map((token) => {
-                if (token.startsWith('-')) {
-                    return { field: token.substring(1), direction: 'desc' };
-                }
-                return { field: token, direction: 'asc' };
-            })
-                .filter((s) => s.field.length > 0);
+                .map((token) => this.parseSortToken(token))
+                .filter((s) => s !== undefined);
         }
         if (Array.isArray(raw)) {
-            return raw.filter((item) => item != null &&
-                typeof item === 'object' &&
-                typeof item.field === 'string' &&
-                (item.direction === 'asc' || item.direction === 'desc'));
+            return raw.flatMap((item) => {
+                // A `string[]` is what a JSON:API-ish array and a legacy
+                // `orderBy: string[]` both look like. It used to fail the
+                // `typeof item === 'object'` test and get filtered out, so the
+                // ORDER BY disappeared with no error, no warning and no 400 — the
+                // grid just silently stopped sorting. Read it as tokens instead.
+                if (typeof item === 'string') {
+                    const parsed = this.parseSortToken(item);
+                    return parsed ? [parsed] : [];
+                }
+                return this.isSortItem(item) ? [item] : [];
+            });
         }
         return [];
     }
@@ -2068,16 +2753,18 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
     /**
      * Applies offset or cursor pagination to the query builder.
      * Cursor pagination logs a warning (not yet implemented).
+     *
+     * `trusted` bypasses the `maxPageSize` ceiling — see
+     * {@link FilterRunner.resolvePageSize}.
      */
-    applyPagination(qb, rawPaginate, adapter) {
+    applyPagination(qb, rawPaginate, adapter, trusted = false) {
         if (!rawPaginate || typeof rawPaginate !== 'object')
             return;
         const p = rawPaginate;
         if ('page' in p && 'size' in p) {
             if (!adapter?.applyOffsetPagination)
                 return;
-            const maxSize = this.options.maxPageSize ?? 100;
-            const size = Math.min(Math.max(1, Number(p.size) || 25), maxSize);
+            const size = this.resolvePageSize(p.size, trusted);
             const page = Math.max(0, Number(p.page) || 0);
             adapter.applyOffsetPagination(qb, page, size);
         }
@@ -2085,6 +2772,33 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             this.logger.warn('Cursor pagination is not yet implemented. Use offset pagination.');
         }
     }
+    /**
+     * Resolves the effective page size from a requested one.
+     *
+     * `maxPageSize` is a MODULE-level ceiling, so one number has to answer two
+     * different questions, and the right answers disagree. For a size that came
+     * off an HTTP request the ceiling is the whole point: it is what stops a
+     * client asking for a million rows. For a size that came from the server's
+     * own code — an export writing a CSV, a scheduled report, a batch job — the
+     * ceiling is not protection, it is a silent wrong answer: the runner is
+     * handed `size: 10_000`, returns 100 rows, and the export loop reads
+     * `100 < 10_000` as "table exhausted" and writes a truncated file with no
+     * error anywhere.
+     *
+     * The runner cannot tell the two apart by looking at the number, so the CALL
+     * SITE says which it is. `trusted` means "this size is server-authored, not
+     * client input" — the one fact the caller knows and the runner never can.
+     *
+     * The minimum of 1 still applies either way: that is not a safety cap but a
+     * correctness one (a `LIMIT 0` or a negative limit is not a page), and
+     * trusting the caller's intent does not make `size: -5` mean anything.
+     */
+    resolvePageSize(rawSize, trusted) {
+        const requested = Math.max(1, Number(rawSize) || 25);
+        if (trusted)
+            return requested;
+        return Math.min(requested, this.options.maxPageSize ?? 100);
+    }
 };
 FilterRunner = FilterRunner_1 = __decorate([
     Injectable(),