nestjs-paginate 13.0.0 → 13.2.0

package/README.md

@@ -558,6 +558,48 @@ Assume `CatEntity` has a one‑to‑many relation `toys: CatToyEntity[]` where `
   GET /cats?filter.toys.name=$any:$not:$eq:Squeaky
   ```
 
+### AND-mode: entity must have ALL of the specified related values
+
+Use the `$and` comparator to require that a parent entity has **all** of the specified related values.
+Each `$and` value produces a separate correlated EXISTS subquery, ANDed on the outer query.
+
+Enable it in `filterableColumns`:
+
+```typescript
+filterableColumns: {
+  'toys.name': [FilterOperator.EQ, FilterComparator.AND],
+}
+```
+
+- Cat must have **both** a toy named "Ball" **and** a toy named "Mouse":
+
+  ```url
+  GET /cats?filter.toys.name=$and:Ball&filter.toys.name=$and:Mouse
+  ```
+
+- Cat must have a toy named "Ball" **and** be friends with a cat named "Garfield" (two independent to-many paths):
+
+  ```url
+  GET /cats?filter.toys.name=$and:Ball&filter.friends.name=$and:Garfield
+  ```
+
+**Restrictions and performance notes**:
+
+- `$and` may only be used on to-many relationship columns (one-to-many or many-to-many).
+- `$and` values may not be mixed with non-`$and` values on the same sub-column.
+- `$and` may not be combined with `$none` or `$all` quantifiers.
+- Each `$and` value adds one correlated EXISTS subquery. For N values and a relation path of depth D, this produces N × D joins. The default cap is 20 values per sub-column; override with `maxAndValues` in `PaginateConfig`.
+
+```typescript
+const config: PaginateConfig<CatEntity> = {
+  sortableColumns: ['id'],
+  filterableColumns: {
+    'toys.name': [FilterOperator.EQ, FilterComparator.AND],
+  },
+  maxAndValues: 10, // optional, default is 20
+}
+```
+
 ## Usage with Eager Loading
 
 Eager loading should work with TypeORM's eager property out of the box:

package/lib/__tests__/cat.entity.d.ts

@@ -19,6 +19,7 @@ export declare class CatEntity {
     createdAt: string;
     deletedAt?: string;
     friends: CatEntity[];
+    friendOf: CatEntity[];
     weightChange: number | null;
     private afterLoad;
 }

package/lib/__tests__/cat.entity.js

@@ -82,10 +82,14 @@ __decorate([
     __metadata("design:type", String)
 ], CatEntity.prototype, "deletedAt", void 0);
 __decorate([
-    (0, typeorm_1.ManyToMany)(() => CatEntity),
+    (0, typeorm_1.ManyToMany)(() => CatEntity, (cat) => cat.friendOf),
     (0, typeorm_1.JoinTable)(),
     __metadata("design:type", Array)
 ], CatEntity.prototype, "friends", void 0);
+__decorate([
+    (0, typeorm_1.ManyToMany)(() => CatEntity, (cat) => cat.friends),
+    __metadata("design:type", Array)
+], CatEntity.prototype, "friendOf", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'decimal', precision: 5, scale: 2, nullable: true }),
     __metadata("design:type", Number)

package/lib/__tests__/cat.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"cat.entity.js","sourceRoot":"","sources":["../../src/__tests__/cat.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAYgB;AAChB,uDAAiD;AACjD,qDAA+C;AAC/C,mDAAuE;AACvE,6CAAwC;AAExC,IAAY,aAIX;AAJD,WAAY,aAAa;IACrB,4BAAW,CAAA;IACX,kCAAiB,CAAA;IACjB,8BAAa,CAAA;AACjB,CAAC,EAJW,aAAa,6BAAb,aAAa,QAIxB;AAGM,IAAM,SAAS,GAAf,MAAM,SAAS;IA+CV,SAAS;;QACb,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAA,MAAA,IAAI,CAAC,IAAI,0CAAE,EAAE,CAAA,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QACpB,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA,CAAC,gDAAgD;QAClG,CAAC;IACL,CAAC;CACJ,CAAA;AAxDY,8BAAS;AAElB;IADC,IAAA,gCAAsB,GAAE;;qCACf;AAGV;IADC,IAAA,gBAAM,GAAE;;uCACG;AAGZ;IADC,IAAA,gBAAM,GAAE;;wCACI;AAGb;IADC,IAAA,gBAAM,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;sCACT;AAGlB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,yFAAyF;;;gDACvF;AAG5B;IADC,IAAA,gBAAM,EAAC,kCAAkB,CAAC;8BACb,IAAI;+CAAO;AAGzB;IADC,IAAA,gBAAM,EAAC,GAAG,EAAE,CAAC,sBAAS,CAAC;8BAClB,sBAAS;uCAAA;AAKf;IAHC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,6BAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE;QACnD,KAAK,EAAE,IAAI;KACd,CAAC;;uCACkB;AAIpB;IAFC,IAAA,kBAAQ,EAAC,GAAG,EAAE,CAAC,+BAAa,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3E,IAAA,oBAAU,GAAE;8BACP,+BAAa;uCAAA;AAGnB;IADC,IAAA,0BAAgB,EAAC,iCAAiB,CAAC;;4CACnB;AAGjB;IADC,IAAA,0BAAgB,EAAC,kCAAkB,CAAC;;4CACnB;AAIlB;IAFC,IAAA,oBAAU,EAAC,GAAG,EAAE,CAAC,SAAS,CAAC;IAC3B,IAAA,mBAAS,GAAE;;0CACQ;AAGpB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;+CACzC;AAKnB;IAHP,IAAA,mBAAS,GAAE;IACZ,yDAAyD;IACzD,mGAAmG;;;;;0CASlG;oBAvDQ,SAAS;IADrB,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;GACX,SAAS,CAwDrB"}
+{"version":3,"file":"cat.entity.js","sourceRoot":"","sources":["../../src/__tests__/cat.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAYgB;AAChB,uDAAiD;AACjD,qDAA+C;AAC/C,mDAAuE;AACvE,6CAAwC;AAExC,IAAY,aAIX;AAJD,WAAY,aAAa;IACrB,4BAAW,CAAA;IACX,kCAAiB,CAAA;IACjB,8BAAa,CAAA;AACjB,CAAC,EAJW,aAAa,6BAAb,aAAa,QAIxB;AAGM,IAAM,SAAS,GAAf,MAAM,SAAS;IAkDV,SAAS;;QACb,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAA,MAAA,IAAI,CAAC,IAAI,0CAAE,EAAE,CAAA,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QACpB,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA,CAAC,gDAAgD;QAClG,CAAC;IACL,CAAC;CACJ,CAAA;AA3DY,8BAAS;AAElB;IADC,IAAA,gCAAsB,GAAE;;qCACf;AAGV;IADC,IAAA,gBAAM,GAAE;;uCACG;AAGZ;IADC,IAAA,gBAAM,GAAE;;wCACI;AAGb;IADC,IAAA,gBAAM,EAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;sCACT;AAGlB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,yFAAyF;;;gDACvF;AAG5B;IADC,IAAA,gBAAM,EAAC,kCAAkB,CAAC;8BACb,IAAI;+CAAO;AAGzB;IADC,IAAA,gBAAM,EAAC,GAAG,EAAE,CAAC,sBAAS,CAAC;8BAClB,sBAAS;uCAAA;AAKf;IAHC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,6BAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE;QACnD,KAAK,EAAE,IAAI;KACd,CAAC;;uCACkB;AAIpB;IAFC,IAAA,kBAAQ,EAAC,GAAG,EAAE,CAAC,+BAAa,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3E,IAAA,oBAAU,GAAE;8BACP,+BAAa;uCAAA;AAGnB;IADC,IAAA,0BAAgB,EAAC,iCAAiB,CAAC;;4CACnB;AAGjB;IADC,IAAA,0BAAgB,EAAC,kCAAkB,CAAC;;4CACnB;AAIlB;IAFC,IAAA,oBAAU,EAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClD,IAAA,mBAAS,GAAE;;0CACQ;AAGpB;IADC,IAAA,oBAAU,EAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;;2CAC7B;AAGrB;IADC,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;+CACzC;AAKnB;IAHP,IAAA,mBAAS,GAAE;IACZ,yDAAyD;IACzD,mGAAmG;;;;;0CASlG;oBA1DQ,SAAS;IADrB,IAAA,gBAAM,EAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;GACX,SAAS,CA2DrB"}

package/lib/filter.d.ts

@@ -33,6 +33,17 @@ export declare enum FilterComparator {
     OR = "$or"
 }
 export declare function isComparator(value: unknown): value is FilterComparator;
+/**
+ * Returns true when the raw filter string explicitly carries the `$and` comparator token.
+ *
+ * This is distinct from the default AND comparator that every token carries implicitly —
+ * we only want to enter AND-mode when the user deliberately wrote `$and:` in the filter value.
+ * Using `parseFilterToken` (rather than a naive substring split) ensures that `$and` embedded
+ * inside a user value (e.g. `$eq:$and`) is not misidentified as the comparator.
+ *
+ * Must be called after `parseFilterToken` is defined (hoisting applies to function declarations).
+ */
+export declare function hasExplicitAndComparator(raw: string): boolean;
 export declare const OperatorSymbolToFunction: Map<FilterOperator | FilterSuffix, (...args: any[]) => FindOperator<string>>;
 type Filter = {
     quantifier: FilterQuantifier;
@@ -45,6 +56,27 @@ type ColumnFilters = {
 type ColumnJoinMethods = {
     [columnName: string]: JoinMethod;
 };
+/**
+ * Matches TypeORM named parameters (`:name` and `:...name` spread form) while skipping
+ * PostgreSQL cast syntax (`::type`).
+ *
+ * TypeORM parameter names may contain letters, digits, underscores, and dots (the latter
+ * for embedded-property paths, e.g. `size.height0`). The pattern captures the full name
+ * including any embedded-path dots.
+ *
+ * Capture groups:
+ *   1 — optional `...` spread prefix (present for IN parameters)
+ *   2 — parameter name (may contain dots for embedded paths)
+ *
+ * Examples:
+ *   `:name`          → matches, spread=undefined, name='name'
+ *   `:...vals`       → matches, spread='...', name='vals'
+ *   `:size.height0`  → matches, spread=undefined, name='size.height0'
+ *   `col::text`      → no match (lookbehind rejects `::`)
+ *   `:param::int`    → matches `:param`, skips `::int`
+ */
+/** @internal Exported for testing only. */
+export declare const TYPEORM_PARAM_REGEX: RegExp;
 export interface FilterToken {
     quantifier: FilterQuantifier;
     comparator: FilterComparator;
@@ -61,7 +93,7 @@ export declare function generatePredicateCondition(qb: SelectQueryBuilder<unknow
 export declare function addWhereCondition<T>(qb: SelectQueryBuilder<T>, column: string, filter: ColumnFilters): void;
 export declare function parseFilterToken(raw?: string): FilterToken | null;
 export declare function parseFilter<T>(query: PaginateQuery, filterableColumns?: {
-    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier | FilterComparator)[] | true;
 }, qb?: SelectQueryBuilder<T>): ColumnFilters;
 /**
  * Retrieves the relation path for a given column name within the provided metadata.
@@ -77,19 +109,54 @@ export declare function parseFilter<T>(query: PaginateQuery, filterableColumns?:
  * Throws an error if no matching relation or embedded metadata is found.
  */
 export declare function getRelationPath(columnName: string, metadata: EntityMetadata | EmbeddedMetadata): [string, RelationMetadata | EmbeddedMetadata][];
+export interface AddFilterOptions {
+    /**
+     * Maximum number of `$and` values allowed per sub-column in a single to-many filter.
+     * Each value produces a separate correlated EXISTS subquery, so large values have a
+     * linear performance cost. Defaults to 20.
+     */
+    maxAndValues?: number;
+    /**
+     * When false, skips the validation that rejects `$and` on non-to-many columns.
+     * Set to false when calling `addFilter` recursively for EXISTS sub-queries, where the
+     * entity metadata is the leaf entity and the to-many check would incorrectly throw.
+     * @internal
+     */
+    validateAndComparator?: boolean;
+}
 export declare function addFilter<T>(qb: SelectQueryBuilder<T>, query: PaginateQuery, filterableColumns?: {
-    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
-}): ColumnJoinMethods;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier | FilterComparator)[] | true;
+}, opts?: AddFilterOptions): ColumnJoinMethods;
 export declare function addDirectFilters<T>(qb: SelectQueryBuilder<T>, filter: ColumnFilters): void;
+/**
+ * Adds correlated EXISTS subqueries to `qb` for all to-many relationship filters in `filter`.
+ *
+ * **AND-mode (`$and` comparator)**
+ *
+ * When a sub-column filter uses the `$and` comparator (e.g. `filter[toys.name]=$and:Ball`),
+ * each distinct `$and` value produces a separate correlated EXISTS subquery, ANDed on the
+ * outer query. This is the only correct way to express "entity has ALL of these related values"
+ * — a single EXISTS with AND conditions on the same column is always false on a single row.
+ *
+ * **Performance note**: each `$and` value adds one correlated EXISTS with the full join chain
+ * for that relation path. For a relation path of depth D and N `$and` values, this produces
+ * N × D joins. The `maxAndValues` option (default 20) caps N to limit query complexity.
+ *
+ * **Restrictions**:
+ * - `$and` may only be used on to-many relationship columns.
+ * - `$and` values may not be mixed with non-`$and` values on the same sub-column.
+ * - `$and` may not be combined with `$none` or `$all` quantifiers.
+ * - `$and` may only be applied to a single sub-column per relation path at a time.
+ */
 export declare function addToManySubFilters<T>(qb: SelectQueryBuilder<T>, filter: ColumnFilters, query: PaginateQuery, filterableColumns?: {
-    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
-}): void;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier | FilterComparator)[] | true;
+}, { maxAndValues, validateAndComparator }?: AddFilterOptions): void;
 export declare function createSubFilter(query: PaginateQuery, filterableColumns: {
-    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier | FilterComparator)[] | true;
 }, column: string): {
     subQuery: PaginateQuery;
     subFilterableColumns: {
-        [column: string]: true | (FilterOperator | FilterSuffix | FilterQuantifier)[];
+        [column: string]: true | (FilterOperator | FilterSuffix | FilterQuantifier | FilterComparator)[];
     };
 };
 export {};