@dudousxd/nestjs-filter 1.31.0 → 1.32.1

package/dist/runner.js

@@ -24,6 +24,7 @@ import { getFilterableMetadata } from './decorator/filterable.decorator.js';
 import { resolveRelation } from './decorator/relations.decorator.js';
 import { getTenantScopedField } from './decorator/tenant-scoped.decorator.js';
 import { FilterMethodException, FilterNotRegisteredException, UnknownFilterKeyException, } from './errors/exceptions.js';
+import { expandBracketKeys } from './input/bracket-keys.js';
 import { resolveDispatchTarget } from './input/dispatcher.js';
 import { normalizeInput } from './input/normalizer.js';
 import { parseSpatieInput } from './input/spatie-parser.js';
@@ -93,14 +94,19 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
     options;
     contextAccessor;
     logger = new Logger(FilterRunner_1.name);
-    adapter;
+    /** The application-wide adapter (`FilterModule.forRoot`'s), used by every filter that does not
+     *  name its own — see {@link FilterableOptions.adapter}. */
+    defaultAdapter;
+    /** Adapters resolved from a filter-declared token, memoized per token: they are application-scoped
+     *  providers, so re-resolving them per request is pure overhead. */
+    scopedAdapters = new Map();
     /** Per-entity metadata cache for `describe()`. Metadata is static at runtime. */
     descriptionCache = new WeakMap();
     constructor(moduleRef, options, injectedAdapter, contextAccessor) {
         this.moduleRef = moduleRef;
         this.options = options;
         this.contextAccessor = contextAccessor;
-        this.adapter = injectedAdapter;
+        this.defaultAdapter = injectedAdapter;
     }
     /**
      * Soft-detects the current-request context accessor owned by
@@ -147,15 +153,47 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         }
         adapter.applyAutoField(qb, field, tenantId);
     }
-    resolveAdapter() {
-        if (this.adapter)
-            return this.adapter;
+    /**
+     * The adapter that answers for a request, given the classes it is made against.
+     *
+     * The FIRST source declaring `@Filterable({ adapter })` wins (a filter class before the entity it
+     * targets, since the class is the more specific declaration), and everything else falls through to
+     * the application-wide adapter. Sources are passed as they are known at the call site; `undefined`
+     * entries are skipped, so a dynamic call with no filter class behaves exactly as before.
+     *
+     * A declared token that does not resolve THROWS rather than falling back: a filter naming the
+     * adapter it needs, then quietly running on a different backend's, would answer with rows from the
+     * wrong data source — a failure that looks like a successful query.
+     */
+    resolveAdapter(...sources) {
+        for (const source of sources) {
+            const token = source ? getFilterableMetadata(source)?.adapter : undefined;
+            if (token === undefined)
+                continue;
+            const cached = this.scopedAdapters.get(token);
+            if (cached)
+                return cached;
+            let resolved = null;
+            try {
+                resolved = this.moduleRef.get(token, { strict: false });
+            }
+            catch {
+                resolved = null;
+            }
+            if (!resolved) {
+                throw new Error(`@Filterable on ${source?.name} names an adapter token that is not registered. Provide it in a module reachable from this one.`);
+            }
+            this.scopedAdapters.set(token, resolved);
+            return resolved;
+        }
+        if (this.defaultAdapter)
+            return this.defaultAdapter;
         try {
             const resolved = this.moduleRef.get(FILTER_ADAPTER, { strict: false });
             if (resolved) {
-                this.adapter = resolved;
+                this.defaultAdapter = resolved;
             }
-            return this.adapter;
+            return this.defaultAdapter;
         }
         catch {
             return null;
@@ -239,7 +277,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         const cached = this.descriptionCache.get(entity);
         if (cached)
             return cached;
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(entity);
         const fields = {};
         const relations = {};
         for (const field of adapter?.getEntityFields?.(entity) ?? []) {
@@ -413,11 +451,11 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
     }
     async apply(FilterClass, input, qb, context = {}, internal = {}) {
         const filter = await this.resolveFilter(FilterClass);
-        const adapter = this.resolveAdapter();
         // Resolved once and reused for every alias choke point below (column
         // filters, structured filter keys, sort, distinct, select) as well as
         // the computed-field/entity lookups further down.
         const filterableMeta = getFilterableMetadata(FilterClass);
+        const adapter = this.resolveAdapter(FilterClass, filterableMeta?.entity);
         // Merges the inline `computed` map and `@Computed` methods into one
         // alias → source registry, resolved once per apply() call.
         const computedRegistry = buildComputedRegistry(FilterClass, filter);
@@ -862,7 +900,10 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * via the adapter's applyRelationConstraint.
      */
     async applyRelation(RelatedFilterClass, qb, relationName, entries, context) {
-        if (!this.adapter?.applyRelationConstraint) {
+        // The RELATED filter's adapter, not the outer one: a relation is constrained through the class
+        // that declares it, and that class may name its own backend.
+        const adapter = this.resolveAdapter(RelatedFilterClass);
+        if (!adapter?.applyRelationConstraint) {
             this.warnUnsupported(`Relation "${relationName}" provided`, 'applyRelationConstraint');
             return;
         }
@@ -870,7 +911,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         for (const [key, value] of entries) {
             inputObj[key] = value;
         }
-        await this.adapter.applyRelationConstraint(qb, relationName, async (relationQb) => {
+        await adapter.applyRelationConstraint(qb, relationName, async (relationQb) => {
             await this.apply(RelatedFilterClass, { filter: inputObj }, relationQb, context, {
                 native: true,
             });
@@ -884,10 +925,19 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * - Any other shape is treated as the filter portion directly (backward compat for internal calls)
      */
     extractStructuredInput(input, internal = {}) {
+        // Bracket-encoded flat keys first (`filter[where][0][field]`), which is what a GET carries on a
+        // host whose query parser did not expand them — Express 5's default. A no-op for everything
+        // else, and it has to run before the structured-key detection below: unexpanded, `filter` is not
+        // a key at all, the whole bag reads as a bare filter, and every predicate is silently dropped.
+        const expanded = input && typeof input === 'object' && !Array.isArray(input)
+            ? expandBracketKeys(input)
+            : input;
         // 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;
+        const source = !internal.native && this.options.inputFormat === 'spatie'
+            ? parseSpatieInput(expanded)
+            : expanded;
         if (source == null || typeof source !== 'object') {
             return {
                 filter: source,
@@ -1012,7 +1062,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
                 return set;
             }
             // Introspect entity metadata to restrict auto-fields to real columns
-            const adapter = this.resolveAdapter();
+            const adapter = this.resolveAdapter(FilterClass, meta.entity);
             if (adapter?.getEntityFields) {
                 const entityFields = adapter.getEntityFields(meta.entity);
                 if (entityFields) {
@@ -1181,7 +1231,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * @returns The query builder with filters applied.
      */
     async applyDynamic(entity, input, qb, context = {}, internal = {}) {
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(internal.filterClass, entity);
         // Dynamic mode has no FilterClass — an entity class can still carry
         // `@Filterable` metadata (declared directly on the entity, decorating
         // itself) purely to supply `aliases` for endpoints that query it
@@ -1337,7 +1387,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * else this method does.
      */
     async findAndCount(entity, input, opts = {}) {
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(entity);
         const qb = opts.qb ?? adapter?.createQueryBuilder(entity);
         const structured = this.extractStructuredInput(input);
         const includes = this.parseIncludes(structured.include);
@@ -1435,7 +1485,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      *   count }[]` with `bucketEnd = bucketStart + bucket`.
      */
     async groupByCount(entity, input, opts = {}) {
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(opts.filterClass, entity);
         const structured = this.extractStructuredInput(input);
         const spec = this.parseGroupByCount(structured.groupByCount);
         if (!spec) {
@@ -1478,9 +1528,11 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         // Apply WHERE + search only (no sort/pagination/distinct/select — this mode
         // replaces entity rows). `skipSortAndPagination` also keeps applyDynamic
         // from ordering/slicing the pre-aggregation query.
-        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, opts.context, { skipSortAndPagination: true, native: true });
+        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, opts.context, { skipSortAndPagination: true, native: true, filterClass: opts.filterClass });
         const bucket = spec.bucket;
-        const rows = await adapter.groupByCount(qb, groupField, entity, bucket ? { bucket } : undefined);
+        const limit = spec.limit;
+        const aggregateOpts = bucket || limit ? { ...(bucket && { bucket }), ...(limit && { limit }) } : undefined;
+        const rows = await adapter.groupByCount(qb, groupField, entity, aggregateOpts);
         if (bucket) {
             return rows.map((r) => {
                 const bucketStart = Number(r.value);
@@ -1491,10 +1543,18 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
     }
     /**
      * Parses and validates the raw `groupByCount` structured-input block into a
-     * canonical `{ field, bucket? }`. Returns `null` when no usable `field` is
-     * present. `bucket` is kept only when it is a finite positive number — a
-     * zero/negative/NaN/non-number bucket degrades to the plain (non-bucketed)
-     * group-by-count rather than emitting a divide-by-zero or nonsensical width.
+     * canonical `{ field, bucket?, limit? }`. Returns `null` when no usable
+     * `field` is present. `bucket` is kept only when it is a finite positive
+     * number — a zero/negative/NaN/non-number bucket degrades to the plain
+     * (non-bucketed) group-by-count rather than emitting a divide-by-zero or
+     * nonsensical width. `limit` is kept on the same terms and must additionally
+     * be an integer; anything else degrades to the unbounded form, since a
+     * fractional or negative row count is not a narrower question, just a
+     * malformed one.
+     *
+     * Both arrive over the wire as strings on a GET route (`?groupByCount[limit]=20`),
+     * so numeric strings are coerced before those checks — otherwise the bound a
+     * caller asked for would be silently dropped by the shape test alone.
      */
     parseGroupByCount(raw) {
         if (!raw || typeof raw !== 'object')
@@ -1502,10 +1562,18 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         const obj = raw;
         if (typeof obj.field !== 'string' || obj.field.length === 0)
             return null;
-        const bucket = typeof obj.bucket === 'number' && Number.isFinite(obj.bucket) && obj.bucket > 0
-            ? obj.bucket
-            : undefined;
-        return { field: obj.field, ...(bucket !== undefined && { bucket }) };
+        const numeric = (value) => {
+            const n = typeof value === 'string' ? Number(value) : value;
+            return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+        };
+        const bucket = numeric(obj.bucket);
+        const limitValue = numeric(obj.limit);
+        const limit = limitValue !== undefined && Number.isInteger(limitValue) ? limitValue : undefined;
+        return {
+            field: obj.field,
+            ...(bucket !== undefined && { bucket }),
+            ...(limit !== undefined && { limit }),
+        };
     }
     /**
      * **Field extent**: the `MIN`/`MAX` of the requested field(s) over the rows
@@ -1571,7 +1639,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         // alongside its rows read and get nothing back when nobody asked.
         if (requested.length === 0)
             return {};
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(opts.filterClass, entity);
         if (!adapter?.fieldExtent) {
             throw new Error('extent is not supported by the active adapter (it does not implement fieldExtent()).');
         }
@@ -1608,7 +1676,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         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 });
+        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, opts.context, { skipSortAndPagination: true, native: true, filterClass: opts.filterClass });
         return adapter.fieldExtent(qb, targets, entity);
     }
     /**
@@ -1643,9 +1711,9 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * set, and an ORDER BY on a column an aggregate SELECT no longer projects is
      * MySQL error 3065.
      */
-    async buildFilteredQb(entity, structured, adapter, context) {
+    async buildFilteredQb(entity, structured, adapter, context, filterClass) {
         const qb = adapter.createQueryBuilder(entity);
-        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, context, { skipSortAndPagination: true, native: true });
+        await this.applyDynamic(entity, { filter: structured.filter, search: structured.search }, qb, context, { skipSortAndPagination: true, native: true, filterClass });
         return qb;
     }
     /**
@@ -1727,7 +1795,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         if (!spec) {
             throw new BadRequestException('histogram requires a `{ field }` specification (with an optional positive `buckets` count).');
         }
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(opts.filterClass, entity);
         // 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.
@@ -1755,7 +1823,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
         }
         this.assertBucketable(target, entity, adapter);
         // ── pass 1: where do the endpoints sit ───────────────────────────────────
-        const extentQb = await this.buildFilteredQb(entity, structured, adapter, opts.context);
+        const extentQb = await this.buildFilteredQb(entity, structured, adapter, opts.context, opts.filterClass);
         const measured = await adapter.fieldExtent(extentQb, [target], entity);
         const key = typeof target === 'string' ? target : target.alias;
         const bounds = measured[key];
@@ -1776,7 +1844,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
             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);
+        const countQb = await this.buildFilteredQb(entity, structured, adapter, opts.context, opts.filterClass);
         // 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
@@ -2001,7 +2069,7 @@ let FilterRunner = FilterRunner_1 = class FilterRunner {
      * cannot opt out.
      */
     async findPage(entity, input, opts = {}) {
-        const adapter = this.resolveAdapter();
+        const adapter = this.resolveAdapter(entity);
         if (!adapter?.getResult ||
             !adapter.getPrimaryKey ||
             !adapter.applyKeysetPagination ||