@dudousxd/nestjs-filter 1.7.1 → 1.8.0

package/dist/runner.js

@@ -11,9 +11,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 var FilterRunner_1;
-import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { BadRequestException, Inject, Injectable, Logger, Optional, } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import { runWithFilterState } from './als-store.js';
+import { allowedFieldNames, normalizeAllowed, } from './decorator/allowed.js';
 import { getFilterForMap } from './decorator/filter-for.decorator.js';
 import { getFilterableMetadata } from './decorator/filterable.decorator.js';
 import { resolveRelation } from './decorator/relations.decorator.js';
@@ -21,8 +22,10 @@ import { getTenantScopedField } from './decorator/tenant-scoped.decorator.js';
 import { FilterMethodException, FilterNotRegisteredException, UnknownFilterKeyException, } from './errors/exceptions.js';
 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 { validateColumnFilters } from './operators/validate-column-filter.js';
+import { 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 };
 let FilterRunner = FilterRunner_1 = class FilterRunner {
@@ -131,16 +134,19 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         this.descriptionCache.set(entity, description);
         return description;
     }
-    async apply(FilterClass, input, qb, context = {}) {
+    async apply(FilterClass, input, qb, context = {}, internal = {}) {
         const filter = await this.resolveFilter(FilterClass);
         const adapter = this.resolveAdapter();
         // Extract structured input: { filter, include, search, sort, paginate }
-        const rawInput = this.extractStructuredInput(input);
+        const rawInput = this.extractStructuredInput(input, {
+            ...(internal.native !== undefined && { native: internal.native }),
+        });
         const filterInput = rawInput.filter;
         const rawInclude = rawInput.include;
         const rawSearch = rawInput.search;
         const rawSort = rawInput.sort;
         const rawDistinct = rawInput.distinct;
+        const rawSelect = rawInput.select;
         const rawPaginate = rawInput.paginate;
         // Extract column filters from the filter portion before normalization
         const { columnFilters, remainingInput } = this.extractColumnFilters(filterInput);
@@ -168,10 +174,16 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             // Opt-in tenant auto-scope (@TenantScoped). Only applies when an accessor
             // is bound AND resolves a tenant id; otherwise a no-op.
             this.applyTenantScope(FilterClass, qb, adapter, contextAccessor);
+            // Resolve the (possibly operator-restricting) allowlist once for this run.
+            const normalizedAllowed = normalizeAllowed(getFilterableMetadata(FilterClass)?.allowed);
+            const throwOnInvalidPolicy = this.resolveThrowOnInvalid(FilterClass);
             // Apply column filters via adapter before @FilterFor dispatch
             if (columnFilters.length > 0 && adapter?.applyColumnFilters) {
-                validateColumnFilters(columnFilters);
-                adapter.applyColumnFilters(qb, columnFilters);
+                const opAllowed = this.enforceOperatorAllowlist(columnFilters, normalizedAllowed, throwOnInvalidPolicy);
+                if (opAllowed.length > 0) {
+                    validateColumnFilters(opAllowed);
+                    adapter.applyColumnFilters(qb, opAllowed, getFilterableMetadata(FilterClass)?.entity);
+                }
             }
             else if (columnFilters.length > 0 && !adapter?.applyColumnFilters) {
                 this.logger.warn('Column filters (where) provided but adapter does not support applyColumnFilters. Skipping.');
@@ -179,6 +191,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             // Resolve auto-fields configuration
             const autoFieldSet = this.resolveAutoFields(FilterClass);
             const filterableMeta = getFilterableMetadata(FilterClass);
+            const computed = filterableMeta?.computed;
             // Collect relation-bound keys for batched processing
             const relationBatches = new Map();
             for (const [key, value] of Object.entries(finalInput)) {
@@ -209,10 +222,26 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                     relationBatches.get(relationName).entries.push([key, value]);
                     continue;
                 }
+                // Check if this key is a computed/virtual field (dev-declared SQL).
+                if (computed && Object.hasOwn(computed, key)) {
+                    if (adapter?.applyComputedField) {
+                        const filtered = this.enforceAutoFieldOperators(key, value, normalizedAllowed, throwOnInvalidPolicy);
+                        if (filtered !== undefined) {
+                            adapter.applyComputedField(qb, computed[key], filtered);
+                        }
+                    }
+                    else {
+                        this.logger.warn(`Computed field "${key}" provided but adapter does not support applyComputedField. Skipping.`);
+                    }
+                    continue;
+                }
                 // Check if this key is an auto-field
                 if (autoFieldSet?.has(key)) {
                     if (adapter?.applyAutoField) {
-                        adapter.applyAutoField(qb, key, value);
+                        const filtered = this.enforceAutoFieldOperators(key, value, normalizedAllowed, throwOnInvalidPolicy);
+                        if (filtered !== undefined) {
+                            adapter.applyAutoField(qb, key, filtered);
+                        }
                     }
                     else {
                         this.logger.warn(`Auto-field "${key}" provided but adapter does not support applyAutoField. Skipping.`);
@@ -291,7 +320,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             if (distinctFields.length > 0 && adapter?.applyDistinct && filterableMeta) {
                 const allowedDistinct = FilterClass
                     .distinct;
-                const validDistinct = this.validateDistinct(distinctFields, allowedDistinct, adapter, filterableMeta.entity);
+                const validDistinct = this.validateDistinct(distinctFields, allowedDistinct, adapter, filterableMeta.entity, this.resolveThrowOnInvalid(FilterClass));
                 if (validDistinct.length > 0) {
                     adapter.applyDistinct(qb, validDistinct, filterableMeta.entity);
                 }
@@ -299,14 +328,27 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             else if (distinctFields.length > 0 && !adapter?.applyDistinct) {
                 this.logger.warn('Distinct requested but adapter does not support applyDistinct. Skipping.');
             }
-            // Apply sort
-            const sorts = this.parseSorts(rawSort);
+            // Apply sparse fieldsets (SELECT narrowing) — validated against the
+            // allowlist / entity metadata, mirroring distinct/sort safety.
+            const selectFields = this.parseDistinct(rawSelect);
+            if (selectFields.length > 0 && adapter?.applySelect && filterableMeta) {
+                const allowedSelect = FilterClass.select;
+                const validSelect = this.validateDistinct(selectFields, allowedSelect, adapter, filterableMeta.entity, throwOnInvalidPolicy);
+                if (validSelect.length > 0) {
+                    adapter.applySelect(qb, validSelect, filterableMeta.entity);
+                }
+            }
+            else if (selectFields.length > 0 && !adapter?.applySelect) {
+                this.logger.warn('Sparse fieldsets (select) requested but adapter does not support applySelect. Skipping.');
+            }
+            // Apply sort — falling back to defaultSort when the client gave none.
+            const parsedSorts = this.parseSorts(rawSort);
+            const sorts = parsedSorts.length > 0
+                ? parsedSorts
+                : this.parseSorts(this.resolveDefaultSort(FilterClass));
             if (sorts.length > 0 && adapter?.applySort) {
                 const allowedSorts = FilterClass.sort;
-                const validSorts = this.validateSorts(sorts, allowedSorts, adapter, filterableMeta?.entity);
-                if (validSorts.length > 0) {
-                    adapter.applySort(qb, validSorts);
-                }
+                this.applySortsWithComputed(qb, sorts, allowedSorts, adapter, filterableMeta?.entity, this.resolveThrowOnInvalid(FilterClass), computed);
             }
             // Apply pagination
             this.applyPagination(qb, rawPaginate, adapter);
@@ -364,7 +406,9 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             inputObj[key] = value;
         }
         await this.adapter.applyRelationConstraint(qb, relationName, async (relationQb) => {
-            await this.apply(RelatedFilterClass, { filter: inputObj }, relationQb, context);
+            await this.apply(RelatedFilterClass, { filter: inputObj }, relationQb, context, {
+                native: true,
+            });
         });
     }
     /**
@@ -374,36 +418,56 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * - `{ filter: {...}, include: [...], search: '...', sort: '...', paginate: {...} }` (structured format)
      * - Any other shape is treated as the filter portion directly (backward compat for internal calls)
      */
-    extractStructuredInput(input) {
-        if (input == null || typeof input !== 'object') {
+    extractStructuredInput(input, internal = {}) {
+        // Opt-in spatie / JSON:API input format. Internal re-dispatch calls
+        // (relation constraints, findPage/findAndCount forwards) pass already-native
+        // structured input and set `internal.native` to bypass re-parsing.
+        const source = !internal.native && this.options.inputFormat === 'spatie' ? parseSpatieInput(input) : input;
+        if (source == null || typeof source !== 'object') {
             return {
-                filter: input,
+                filter: source,
                 include: undefined,
                 search: undefined,
                 sort: undefined,
                 distinct: undefined,
+                select: undefined,
                 paginate: undefined,
             };
         }
-        const inputObj = input;
-        // Detect structured format: must have a 'filter' key (even if undefined/null)
-        if ('filter' in inputObj) {
+        const inputObj = source;
+        // Detect structured format: presence of any reserved structured key
+        // (`filter`, `include`, `search`, `sort`, `distinct`, `select`, `paginate`).
+        // The original detection keyed only on `filter`; broadening it lets callers
+        // pass e.g. `{ sort, paginate }` (no filter) — as `findPage` does — while
+        // remaining backward-compatible (these keys were always reserved).
+        const STRUCTURED_KEYS = [
+            'filter',
+            'include',
+            'search',
+            'sort',
+            'distinct',
+            'select',
+            'paginate',
+        ];
+        if (STRUCTURED_KEYS.some((k) => k in inputObj)) {
             return {
                 filter: inputObj.filter ?? undefined,
                 include: inputObj.include ?? undefined,
                 search: inputObj.search ?? undefined,
                 sort: inputObj.sort ?? undefined,
                 distinct: inputObj.distinct ?? undefined,
+                select: inputObj.select ?? undefined,
                 paginate: inputObj.paginate ?? undefined,
             };
         }
         // Not structured — treat entire input as the filter portion
         return {
-            filter: input,
+            filter: source,
             include: undefined,
             search: undefined,
             sort: undefined,
             distinct: undefined,
+            select: undefined,
             paginate: undefined,
         };
     }
@@ -459,11 +523,12 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             return null;
         if (autoFieldsConfig === true) {
             // When autoFields is true with an allowed list, only allowed keys are auto-applicable
-            if (meta.allowed) {
+            const allowedFields = allowedFieldNames(meta.allowed);
+            if (allowedFields) {
                 // Remove keys that already have @FilterFor mappings
                 const filterForMap = getFilterForMap(FilterClass);
                 const set = new Set();
-                for (const key of meta.allowed) {
+                for (const key of allowedFields) {
                     if (!filterForMap.has(key))
                         set.add(key);
                 }
@@ -545,7 +610,9 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         if (searchConfig && typeof searchConfig === 'object' && 'vector' in searchConfig) {
             // tsvector search
             if (adapter.applyVectorSearch) {
-                adapter.applyVectorSearch(qb, searchTerm, searchConfig.vector);
+                adapter.applyVectorSearch(qb, searchTerm, searchConfig.vector, {
+                    ...(searchConfig.rank !== undefined && { rank: searchConfig.rank }),
+                });
             }
             return;
         }
@@ -579,15 +646,18 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * @param context - Optional filter context.
      * @returns The query builder with filters applied.
      */
-    async applyDynamic(entity, input, qb, context = {}) {
+    async applyDynamic(entity, input, qb, context = {}, internal = {}) {
         const adapter = this.resolveAdapter();
-        // Extract structured input: { filter, include, search, sort, distinct, paginate }
-        const rawInput = this.extractStructuredInput(input);
+        // Extract structured input: { filter, include, search, sort, distinct, select, paginate }
+        const rawInput = this.extractStructuredInput(input, {
+            ...(internal.native !== undefined && { native: internal.native }),
+        });
         const filterInput = rawInput.filter;
         const rawInclude = rawInput.include;
         const rawSearch = rawInput.search;
         const rawSort = rawInput.sort;
         const rawDistinct = rawInput.distinct;
+        const rawSelect = rawInput.select;
         const rawPaginate = rawInput.paginate;
         // Extract column filters before normalization
         const { columnFilters, remainingInput } = this.extractColumnFilters(filterInput);
@@ -599,11 +669,12 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         // Apply column filters via adapter — dynamic mode validates the filter
         // fields against entity metadata (like sort/auto-fields), dropping
         // unknown columns so a bad client `where` can't crash the ORM.
+        const throwOnInvalid = this.resolveThrowOnInvalid();
         if (columnFilters.length > 0 && adapter?.applyColumnFilters) {
-            const knownFilters = this.pruneUnknownColumnFilters(columnFilters, entity, adapter);
+            const knownFilters = this.pruneUnknownColumnFilters(columnFilters, entity, adapter, throwOnInvalid);
             if (knownFilters.length > 0) {
                 validateColumnFilters(knownFilters);
-                adapter.applyColumnFilters(qb, knownFilters);
+                adapter.applyColumnFilters(qb, knownFilters, entity);
             }
         }
         else if (columnFilters.length > 0 && !adapter?.applyColumnFilters) {
@@ -654,21 +725,35 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         // Distinct projection (SELECT DISTINCT) — validate against entity metadata
         const distinctFields = this.parseDistinct(rawDistinct);
         if (distinctFields.length > 0 && adapter?.applyDistinct) {
-            const validDistinct = this.validateDistinct(distinctFields, undefined, adapter, entity);
+            const validDistinct = this.validateDistinct(distinctFields, undefined, adapter, entity, throwOnInvalid);
             if (validDistinct.length > 0) {
                 adapter.applyDistinct(qb, validDistinct, entity);
             }
         }
-        // Sort — validate against entity metadata only (no filter class)
-        const sorts = this.parseSorts(rawSort);
-        if (sorts.length > 0 && adapter?.applySort) {
-            const validSorts = this.validateSorts(sorts, undefined, adapter, entity);
-            if (validSorts.length > 0) {
-                adapter.applySort(qb, validSorts);
+        // Sparse fieldsets (SELECT narrowing) — validate against entity metadata.
+        const selectFields = this.parseDistinct(rawSelect);
+        if (selectFields.length > 0 && adapter?.applySelect) {
+            const validSelect = this.validateDistinct(selectFields, undefined, adapter, entity, throwOnInvalid);
+            if (validSelect.length > 0) {
+                adapter.applySelect(qb, validSelect, entity);
+            }
+        }
+        // Sort and pagination are skipped when the caller (e.g. findPage with
+        // cursor pagination) owns ordering and slicing itself.
+        if (!internal.skipSortAndPagination) {
+            // Sort — validate against entity metadata only (no filter class).
+            // Fall back to defaultSort when the client gave none.
+            const parsedSorts = this.parseSorts(rawSort);
+            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);
+                if (validSorts.length > 0) {
+                    adapter.applySort(qb, validSorts);
+                }
             }
+            // Pagination
+            this.applyPagination(qb, rawPaginate, adapter);
         }
-        // Pagination
-        this.applyPagination(qb, rawPaginate, adapter);
         return qb;
     }
     /**
@@ -696,9 +781,10 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             search: structured.search,
             sort: structured.sort,
             distinct: structured.distinct,
+            select: structured.select,
             paginate: structured.paginate,
             include: joinIncludes,
-        }, qb, opts.context);
+        }, qb, opts.context, { native: true });
         if (!adapter?.getResultAndCount) {
             throw new Error('findAndCount requires an adapter that implements getResultAndCount().');
         }
@@ -714,6 +800,103 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         }
         return { rows: rows, total };
     }
+    /**
+     * Runs a dynamic query with **keyset (cursor) pagination** and executes it,
+     * returning a stable, non-overlapping page plus opaque forward/backward
+     * cursors. Unlike offset pagination (which drifts and re-scans as rows are
+     * inserted), keyset pagination seeks past a boundary row using a
+     * `WHERE (sortcols, pk) > (...)` predicate, so it is O(1) per page and stable
+     * under concurrent writes.
+     *
+     * The keyset is the request's effective sort (or `defaultSort`) plus the
+     * entity's primary key as a stable tiebreaker. Multi-column sort composes
+     * naturally. Direction is honored per column (asc → seek forward with `>`,
+     * desc → with `<`); for backward paging (`before`) the comparison and order
+     * are reversed internally and the result re-reversed so `items` is always in
+     * the requested order.
+     *
+     * Requires an adapter implementing `getResult`, `getPrimaryKey`,
+     * `applyKeysetPagination` and `applyKeysetOrderAndLimit`. Additive — does not
+     * change `apply`/`applyDynamic`/`findAndCount`.
+     */
+    async findPage(entity, input, opts = {}) {
+        const adapter = this.resolveAdapter();
+        if (!adapter?.getResult ||
+            !adapter.getPrimaryKey ||
+            !adapter.applyKeysetPagination ||
+            !adapter.applyKeysetOrderAndLimit) {
+            throw new Error('findPage requires an adapter implementing getResult, getPrimaryKey, applyKeysetPagination and applyKeysetOrderAndLimit.');
+        }
+        const qb = opts.qb ?? adapter.createQueryBuilder(entity);
+        const structured = this.extractStructuredInput(input);
+        const paginate = (structured.paginate ?? {});
+        const after = typeof paginate.after === 'string' ? paginate.after : undefined;
+        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);
+        // 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.parseSorts(structured.sort);
+        const rawSorts = parsedSorts.length > 0 ? parsedSorts : this.parseSorts(this.resolveDefaultSort());
+        const validSorts = adapter.applySort
+            ? this.validateSorts(rawSorts, undefined, adapter, entity, this.resolveThrowOnInvalid())
+            : rawSorts;
+        const pk = adapter.getPrimaryKey(entity);
+        if (!pk) {
+            throw new Error(`findPage: could not resolve a primary key for ${entity.name}.`);
+        }
+        const baseKeyset = buildKeyset(validSorts, pk);
+        // Build filters/search/includes only — findPage owns ordering and slicing.
+        await this.applyDynamic(entity, {
+            filter: structured.filter,
+            search: structured.search,
+            include: structured.include,
+            select: structured.select,
+        }, qb, opts.context, { skipSortAndPagination: true, native: true });
+        // For backward paging, reverse keyset directions so the boundary seek and
+        // ordering walk the other way; we re-reverse rows below.
+        const queryKeyset = backward ? this.reverseKeyset(baseKeyset) : baseKeyset;
+        // Decode and apply the cursor boundary predicate (ignored if malformed).
+        if (cursorStr) {
+            const values = decodeCursor(cursorStr);
+            if (values && values.length === queryKeyset.length) {
+                adapter.applyKeysetPagination(qb, queryKeyset, values);
+            }
+        }
+        // Fetch one extra row to detect whether a further page exists.
+        adapter.applyKeysetOrderAndLimit(qb, queryKeyset, limit + 1);
+        const fetched = (await adapter.getResult(qb));
+        const hasExtra = fetched.length > limit;
+        let pageRows = hasExtra ? fetched.slice(0, limit) : fetched;
+        if (backward)
+            pageRows = pageRows.slice().reverse();
+        // Compute boundary cursors. With a cursor present, the opposite-direction
+        // page is known to exist; the same-direction page exists iff we saw an
+        // extra row.
+        const firstRow = pageRows[0];
+        const lastRow = pageRows[pageRows.length - 1];
+        const startCursor = firstRow ? encodeCursor(extractCursorValues(firstRow, baseKeyset)) : null;
+        const endCursor = lastRow ? encodeCursor(extractCursorValues(lastRow, baseKeyset)) : null;
+        const hasNext = backward ? cursorStr !== undefined : hasExtra;
+        const hasPrev = backward ? hasExtra : cursorStr !== undefined;
+        return {
+            items: pageRows,
+            nextCursor: hasNext ? endCursor : null,
+            prevCursor: hasPrev ? startCursor : null,
+            hasNext,
+            hasPrev,
+        };
+    }
+    /** Flips every keyset column's direction (for backward cursor paging). */
+    reverseKeyset(keyset) {
+        return keyset.map((s) => ({
+            field: s.field,
+            direction: s.direction === 'asc' ? 'desc' : 'asc',
+        }));
+    }
     /**
      * Splits include paths into join-safe (to-one) and deferred (to-many) sets,
      * by the cardinality of each path's first relation segment.
@@ -742,7 +925,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * table) is silently ignored instead of crashing the ORM. Recurses AND/OR.
      * No-op (pass-through) when the adapter exposes no metadata.
      */
-    pruneUnknownColumnFilters(filters, entity, adapter) {
+    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)
@@ -761,7 +944,50 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                 return dot > 0 && relationNames.has(field.slice(0, dot));
             };
         const prune = (clauses) => clauses
-            .filter((clause) => !clause.field || isKnown(clause.field))
+            .filter((clause) => {
+            const known = !clause.field || isKnown(clause.field);
+            if (!known && throwOnInvalid) {
+                throw new BadRequestException(`Unknown filter column: "${clause.field}".`);
+            }
+            return known;
+        })
+            .map((clause) => ({
+            ...clause,
+            ...(clause.AND && { AND: prune(clause.AND) }),
+            ...(clause.OR && { OR: prune(clause.OR) }),
+        }));
+        return prune(filters);
+    }
+    /**
+     * Enforces per-field operator allowlists on a `where` ColumnFilter tree.
+     *
+     * For each clause whose `field` carries an operator restriction (declared as
+     * `{ field, operators }` in `@Filterable.allowed`), the clause's operator
+     * (after alias normalization) must be in the permitted set. A disallowed
+     * operator is dropped (default) or raises a `BadRequestException` when
+     * `throwOnInvalid` is set. Fields without a restriction (plain-string allowed
+     * entries, or no allowlist at all) pass through unchanged. Recurses AND/OR.
+     */
+    enforceOperatorAllowlist(filters, allowed, throwOnInvalid) {
+        if (!allowed || allowed.operatorsByField.size === 0)
+            return filters;
+        const prune = (clauses) => clauses
+            .filter((clause) => {
+            // Group nodes (no field of their own) are not operator-checked here;
+            // their children are pruned via the recursion below.
+            if (!clause.field)
+                return true;
+            const permitted = allowed.operatorsByField.get(clause.field);
+            if (!permitted)
+                return true; // field allows all operators
+            const op = normalizeOperator(clause.operator);
+            if (permitted.has(op))
+                return true;
+            if (throwOnInvalid) {
+                throw new BadRequestException(`Operator "${op}" is not allowed on field "${clause.field}".`);
+            }
+            return false;
+        })
             .map((clause) => ({
             ...clause,
             ...(clause.AND && { AND: prune(clause.AND) }),
@@ -769,6 +995,49 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         }));
         return prune(filters);
     }
+    /**
+     * Enforces a per-field operator allowlist on an auto-field value, mirroring
+     * the adapter's value-shape interpretation:
+     *
+     * - scalar → `equals`
+     * - array → `in`
+     * - operator object (`{ gte, lte }`) → each key is an operator
+     *
+     * Returns the value to apply, or `undefined` when the whole auto-field should
+     * be skipped (e.g. a scalar whose implied `equals` is not permitted, or an
+     * operator object reduced to no permitted keys). For operator objects, only
+     * the disallowed keys are stripped. When `throwOnInvalid` is set, a
+     * disallowed operator raises instead of being dropped.
+     */
+    enforceAutoFieldOperators(field, value, allowed, throwOnInvalid) {
+        const permitted = allowed?.operatorsByField.get(field);
+        if (!permitted)
+            return value; // no restriction for this field
+        const reject = (op) => {
+            if (throwOnInvalid) {
+                throw new BadRequestException(`Operator "${op}" is not allowed on field "${field}".`);
+            }
+            return undefined;
+        };
+        if (Array.isArray(value)) {
+            return permitted.has('in') ? value : reject('in');
+        }
+        if (value != null && typeof value === 'object') {
+            const entries = Object.entries(value);
+            const kept = {};
+            for (const [op, opVal] of entries) {
+                const canonical = normalizeOperator(op);
+                if (permitted.has(canonical)) {
+                    kept[op] = opVal;
+                }
+                else if (throwOnInvalid) {
+                    reject(canonical);
+                }
+            }
+            return Object.keys(kept).length > 0 ? kept : undefined;
+        }
+        return permitted.has('equals') ? value : reject('equals');
+    }
     /**
      * Applies global search for dynamic mode: auto-detects all string columns
      * from entity metadata (no filter class with static search config).
@@ -785,6 +1054,30 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             adapter.applySearch(qb, searchTerm, columns, entity);
         }
     }
+    /**
+     * Resolves the effective `throwOnInvalid` policy: per-@Filterable wins over
+     * the module option, which defaults to `false` (silent-drop, legacy behavior).
+     */
+    resolveThrowOnInvalid(FilterClass) {
+        if (FilterClass) {
+            const meta = getFilterableMetadata(FilterClass);
+            if (meta?.throwOnInvalid !== undefined)
+                return meta.throwOnInvalid;
+        }
+        return this.options.throwOnInvalid ?? false;
+    }
+    /**
+     * Resolves the effective `defaultSort`: per-@Filterable wins over the module
+     * option. Returns undefined when neither is set.
+     */
+    resolveDefaultSort(FilterClass) {
+        if (FilterClass) {
+            const meta = getFilterableMetadata(FilterClass);
+            if (meta?.defaultSort !== undefined)
+                return meta.defaultSort;
+        }
+        return this.options.defaultSort;
+    }
     handleUnknownKey(key) {
         const policy = this.options.onUnknownKey ?? 'ignore';
         if (policy === 'throw')
@@ -831,9 +1124,20 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * Validates sort fields against the allowlist (if defined) or entity metadata.
      * Silently skips invalid fields.
      */
-    validateSorts(sorts, allowlist, adapter, entity) {
+    validateSorts(sorts, allowlist, adapter, entity, throwOnInvalid = false) {
+        const accept = (predicate) => {
+            if (throwOnInvalid) {
+                for (const s of sorts) {
+                    if (!predicate(s)) {
+                        throw new BadRequestException(`Invalid sort field: "${s.field}".`);
+                    }
+                }
+                return sorts;
+            }
+            return sorts.filter(predicate);
+        };
         if (allowlist) {
-            return sorts.filter((s) => allowlist.includes(s.field));
+            return accept((s) => allowlist.includes(s.field));
         }
         // No allowlist — validate against entity columns
         if (entity && adapter.getEntityFields) {
@@ -844,16 +1148,54 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                 // like `author.profile.country`. A bare relation (`author`) is rejected
                 // for sorting (you can't order by a relation object).
                 if (adapter.resolveFieldPath) {
-                    return sorts.filter((s) => adapter.resolveFieldPath(entity, s.field) === 'field');
+                    return accept((s) => adapter.resolveFieldPath(entity, s.field) === 'field');
                 }
                 // Fallback: scalar columns only.
                 const fieldNames = new Set(fields.map((f) => f.name));
-                return sorts.filter((s) => fieldNames.has(s.field));
+                return accept((s) => fieldNames.has(s.field));
             }
         }
         // No metadata available — pass through
         return sorts;
     }
+    /**
+     * Applies a list of sorts, routing computed/virtual aliases to
+     * `applyComputedSort` (their dev-provided SQL expression) and regular columns
+     * to `applySort`. Order is preserved across the mix so the resulting
+     * `ORDER BY` matches the requested column order. Regular columns are still
+     * validated against the allowlist / entity metadata; computed aliases bypass
+     * that check because they are dev-declared, not real columns.
+     */
+    applySortsWithComputed(qb, sorts, allowlist, adapter, entity, throwOnInvalid, computed) {
+        const hasComputedSort = !!computed && sorts.some((s) => Object.hasOwn(computed, s.field));
+        // Fast path / backward-compatible behavior: no computed sorts → validate
+        // all sorts and apply them in a single batched `applySort` call (preserving
+        // the prior contract relied upon by existing tests and adapters).
+        if (!hasComputedSort) {
+            const validSorts = this.validateSorts(sorts, allowlist, adapter, entity, throwOnInvalid);
+            if (validSorts.length > 0 && adapter.applySort) {
+                adapter.applySort(qb, validSorts);
+            }
+            return;
+        }
+        // Mixed path: route computed aliases to applyComputedSort and real columns
+        // to applySort, per item, so the resulting ORDER BY honors request order.
+        for (const sort of sorts) {
+            if (computed && Object.hasOwn(computed, sort.field)) {
+                if (adapter.applyComputedSort) {
+                    adapter.applyComputedSort(qb, computed[sort.field], sort.direction);
+                }
+                else {
+                    this.logger.warn(`Computed sort "${sort.field}" requested but adapter does not support applyComputedSort. Skipping.`);
+                }
+                continue;
+            }
+            const valid = this.validateSorts([sort], allowlist, adapter, entity, throwOnInvalid);
+            if (valid.length > 0 && adapter.applySort) {
+                adapter.applySort(qb, valid);
+            }
+        }
+    }
     /**
      * Parses raw distinct input into an array of field names.
      *
@@ -883,15 +1225,26 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * Validates distinct fields against the allowlist (if defined) or entity
      * metadata. Silently skips invalid fields to prevent arbitrary-column probing.
      */
-    validateDistinct(fields, allowlist, adapter, entity) {
+    validateDistinct(fields, allowlist, adapter, entity, throwOnInvalid = false) {
+        const accept = (predicate) => {
+            if (throwOnInvalid) {
+                for (const f of fields) {
+                    if (!predicate(f)) {
+                        throw new BadRequestException(`Invalid distinct field: "${f}".`);
+                    }
+                }
+                return fields;
+            }
+            return fields.filter(predicate);
+        };
         if (allowlist) {
-            return fields.filter((f) => allowlist.includes(f));
+            return accept((f) => allowlist.includes(f));
         }
         if (entity && adapter.getEntityFields) {
             const entityFields = adapter.getEntityFields(entity);
             if (entityFields) {
                 const fieldNames = new Set(entityFields.map((f) => f.name));
-                return fields.filter((f) => fieldNames.has(f));
+                return accept((f) => fieldNames.has(f));
             }
         }
         // No metadata available — pass through