nestjs-paginate 12.10.1 → 13.0.0

package/README.md

@@ -516,6 +516,48 @@ const config: PaginateConfig<CatEntity> = {
 const result = await paginate<CatEntity>(query, catRepo, config)
 ```
 
+## Usage with to-many relationships
+
+You can filter parents by conditions on their to-many relations (one-to-many or many-to-many) using quantifiers.
+Quantifiers define how many related rows must satisfy the condition:
+
+- `$any` (default): at least one related row matches the condition
+- `$all`: all related rows match the condition
+- `$none`: no related rows match the condition
+
+### Examples
+Assume `CatEntity` has a one‑to‑many relation `toys: CatToyEntity[]` where `CatToyEntity` has a string column `name`.
+
+- At least one toy named exactly "Ball":
+
+  ```url
+  GET /cats?filter.toys.name=$any:$eq:Ball
+  ```
+
+- At least one toy whose name contains "red" (case-insensitive):
+
+  ```url
+  GET /cats?filter.toys.name=$any:$ilike:red
+  ```
+
+- All toys must have names that start with "Chew":
+
+  ```url
+  GET /cats?filter.toys.name=$all:$sw:Chew
+  ```
+
+- No toys named "Squeaky", including cats without any toys:
+
+  ```url
+  GET /cats?filter.toys.name=$none:$eq:Squeaky
+  ```
+
+- One or more toys not named "Squeaky":
+
+  ```url
+  GET /cats?filter.toys.name=$any:$not:$eq:Squeaky
+  ```
+
 ## Usage with Eager Loading
 
 Eager loading should work with TypeORM's eager property out of the box:
@@ -589,18 +631,27 @@ const config: PaginateConfig<CatEntity> = {
 
 `?filter.roles=$contains:moderator,admin` where column `roles` is an array and contains the values `moderator` and `admin`
 
-## JSONB Filters
+## JSONB Support
 
-You can filter on JSONB columns using dot notation to access nested fields.
+You can sort, search, and filter on JSONB columns using dot notation to access nested fields.
 
-### Supported operators
+### Database support matrix
+
+| Feature | PostgreSQL / CockroachDB | MySQL / MariaDB | SQLite |
+|---------|---|---|---|
+| **Sorting** (`sortableColumns`) | Yes (`#>>`) | Yes (`JSON_UNQUOTE(JSON_EXTRACT(...))`) | Yes (`json_extract`) |
+| **Searching** (`searchableColumns`) | Yes | Yes | Yes |
+| **Filtering** (`$eq`, `$in`, `$contains`) | Yes (`@>` containment) | No | No |
+
+> **Note:** Sorting and searching on JSONB paths is supported across all database engines — the library automatically uses the correct JSON extraction function for your DB. Filtering via `$eq`, `$in`, and `$contains` uses PostgreSQL's `@>` containment operator (via TypeORM's `JsonContains`) and is only supported on **PostgreSQL** and **CockroachDB**.
+
+### Filtering operators (PostgreSQL / CockroachDB only)
 
 | Operator | Description |
 |----------|-------------|
-| `$eq` | Exact match (`column @> '{"key":"value"}'`) |
-| `$in` | Match any of a comma-separated list of values |
-
-> **Note:** JSONB filtering is implemented using PostgreSQL's `@>` (containment) operator and is only supported by **PostgreSQL**.
+| `$eq`       | Exact match via containment (`col @> '{"key":"value"}'`) |
+| `$in`       | Match any of a comma-separated list of values |
+| `$contains` | Match if a JSON array contains the value |
 
 ### Direct JSONB column
 

package/lib/__tests__/cat-home-pillow.entity.d.ts

@@ -6,4 +6,5 @@ export declare class CatHomePillowEntity {
     color: string;
     brand: CatHomePillowBrandEntity;
     createdAt: string;
+    deletedAt: string;
 }

package/lib/__tests__/cat-home-pillow.entity.js

@@ -37,6 +37,10 @@ __decorate([
     (0, typeorm_1.CreateDateColumn)(column_option_1.DateColumnNotNull),
     __metadata("design:type", String)
 ], CatHomePillowEntity.prototype, "createdAt", void 0);
+__decorate([
+    (0, typeorm_1.DeleteDateColumn)(column_option_1.DateColumnNotNull),
+    __metadata("design:type", String)
+], CatHomePillowEntity.prototype, "deletedAt", void 0);
 exports.CatHomePillowEntity = CatHomePillowEntity = __decorate([
     (0, typeorm_1.Entity)()
 ], CatHomePillowEntity);

package/lib/__tests__/cat-home-pillow.entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"cat-home-pillow.entity.js","sourceRoot":"","sources":["../../src/__tests__/cat-home-pillow.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAA6F;AAC7F,iFAAyE;AACzE,uDAAiD;AACjD,mDAAmD;AAG5C,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;CAe/B,CAAA;AAfY,kDAAmB;AAE5B;IADC,IAAA,gCAAsB,GAAE;;+CACf;AAGV;IADC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,+BAAa,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC;8BACjD,+BAAa;iDAAA;AAGnB;IADC,IAAA,gBAAM,GAAE;;kDACI;AAGb;IADC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,uDAAwB,CAAC;8BACnC,uDAAwB;kDAAA;AAG/B;IADC,IAAA,0BAAgB,EAAC,iCAAiB,CAAC;;sDACnB;8BAdR,mBAAmB;IAD/B,IAAA,gBAAM,GAAE;GACI,mBAAmB,CAe/B"}
+{"version":3,"file":"cat-home-pillow.entity.js","sourceRoot":"","sources":["../../src/__tests__/cat-home-pillow.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAA+G;AAC/G,iFAAyE;AACzE,uDAAiD;AACjD,mDAAmD;AAG5C,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;CAkB/B,CAAA;AAlBY,kDAAmB;AAE5B;IADC,IAAA,gCAAsB,GAAE;;+CACf;AAGV;IADC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,+BAAa,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC;8BACjD,+BAAa;iDAAA;AAGnB;IADC,IAAA,gBAAM,GAAE;;kDACI;AAGb;IADC,IAAA,mBAAS,EAAC,GAAG,EAAE,CAAC,uDAAwB,CAAC;8BACnC,uDAAwB;kDAAA;AAG/B;IADC,IAAA,0BAAgB,EAAC,iCAAiB,CAAC;;sDACnB;AAGjB;IADC,IAAA,0BAAgB,EAAC,iCAAiB,CAAC;;sDACnB;8BAjBR,mBAAmB;IAD/B,IAAA,gBAAM,GAAE;GACI,mBAAmB,CAkB/B"}

package/lib/filter.d.ts

@@ -1,7 +1,9 @@
-import { FindOperator, SelectQueryBuilder } from 'typeorm';
+import { EntityMetadata, FindOperator, SelectQueryBuilder } from 'typeorm';
 import { WherePredicateOperator } from 'typeorm/query-builder/WhereClause';
 import { PaginateQuery } from './decorator';
 import { JoinMethod } from './helper';
+import { EmbeddedMetadata } from 'typeorm/metadata/EmbeddedMetadata';
+import { RelationMetadata } from 'typeorm/metadata/RelationMetadata';
 export declare enum FilterOperator {
     EQ = "$eq",
     GT = "$gt",
@@ -20,6 +22,12 @@ export declare enum FilterSuffix {
     NOT = "$not"
 }
 export declare function isSuffix(value: unknown): value is FilterSuffix;
+export declare enum FilterQuantifier {
+    ALL = "$all",
+    ANY = "$any",
+    NONE = "$none"
+}
+export declare function isQuantifier(value: unknown): value is FilterQuantifier;
 export declare enum FilterComparator {
     AND = "$and",
     OR = "$or"
@@ -27,6 +35,7 @@ export declare enum FilterComparator {
 export declare function isComparator(value: unknown): value is FilterComparator;
 export declare const OperatorSymbolToFunction: Map<FilterOperator | FilterSuffix, (...args: any[]) => FindOperator<string>>;
 type Filter = {
+    quantifier: FilterQuantifier;
     comparator: FilterComparator;
     findOperator: FindOperator<string>;
 };
@@ -37,6 +46,7 @@ type ColumnJoinMethods = {
     [columnName: string]: JoinMethod;
 };
 export interface FilterToken {
+    quantifier: FilterQuantifier;
     comparator: FilterComparator;
     suffix?: FilterSuffix;
     operator: FilterOperator;
@@ -51,9 +61,35 @@ 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)[] | true;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
 }, qb?: SelectQueryBuilder<T>): ColumnFilters;
+/**
+ * Retrieves the relation path for a given column name within the provided metadata.
+ *
+ * This method analyzes the column name's segments to identify corresponding relations or embedded entities
+ * within the hierarchy described by the given metadata and returns a structured path.
+ *
+ * @param {string} columnName - The dot-delimited name of the column whose relation path is to be determined.
+ * @param {EntityMetadata | EmbeddedMetadata} metadata - The metadata of the entity or embedded component
+ * which holds the relations or embedded items.
+ * @return {[string, RelationMetadata | EmbeddedMetadata][]} The ordered array describing the path,
+ * where each element contains a field name and its corresponding relation or embedded metadata.
+ * 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 declare function addFilter<T>(qb: SelectQueryBuilder<T>, query: PaginateQuery, filterableColumns?: {
-    [column: string]: (FilterOperator | FilterSuffix)[] | true;
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
 }): ColumnJoinMethods;
+export declare function addDirectFilters<T>(qb: SelectQueryBuilder<T>, filter: ColumnFilters): void;
+export declare function addToManySubFilters<T>(qb: SelectQueryBuilder<T>, filter: ColumnFilters, query: PaginateQuery, filterableColumns?: {
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
+}): void;
+export declare function createSubFilter(query: PaginateQuery, filterableColumns: {
+    [column: string]: (FilterOperator | FilterSuffix | FilterQuantifier)[] | true;
+}, column: string): {
+    subQuery: PaginateQuery;
+    subFilterableColumns: {
+        [column: string]: true | (FilterOperator | FilterSuffix | FilterQuantifier)[];
+    };
+};
 export {};