@zola_do/collection-query 0.1.9 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# @zola_do/collection-query
|
|
2
|
+
|
|
3
|
+
TypeORM query builder for filter, sort, and paginate operations on collections.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Install individually
|
|
9
|
+
npm install @zola_do/collection-query
|
|
10
|
+
|
|
11
|
+
# Or via meta package
|
|
12
|
+
npm install @zola_do/nestjs-shared
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
### Decoding Query Strings
|
|
18
|
+
|
|
19
|
+
Parse a `q` query parameter from list endpoints into a `CollectionQuery` object:
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import { decodeCollectionQuery } from '@zola_do/collection-query';
|
|
23
|
+
|
|
24
|
+
@Get()
|
|
25
|
+
async findAll(@Query('q') q?: string) {
|
|
26
|
+
const query = decodeCollectionQuery(q);
|
|
27
|
+
return await this.service.findAll(query);
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Query Format
|
|
32
|
+
|
|
33
|
+
The `q` parameter supports:
|
|
34
|
+
|
|
35
|
+
- `s` — Select fields (comma-separated)
|
|
36
|
+
- `w` — Where conditions (filter operators)
|
|
37
|
+
- `t` — Take (limit)
|
|
38
|
+
- `sk` — Skip (offset)
|
|
39
|
+
- `o` — Order by
|
|
40
|
+
- `i` — Includes (relations)
|
|
41
|
+
- `c` — Count only
|
|
42
|
+
|
|
43
|
+
Example: `q=w=column$eq$value&t=10&sk=0&o=createdAt$desc`
|
|
44
|
+
|
|
45
|
+
### Building Queries
|
|
46
|
+
|
|
47
|
+
Use `QueryConstructor` to build TypeORM queries from a `CollectionQuery`:
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
import { QueryConstructor, CollectionQuery } from '@zola_do/collection-query';
|
|
51
|
+
|
|
52
|
+
const dataQuery = QueryConstructor.constructQuery<T>(repository, query);
|
|
53
|
+
const [result, total] = await dataQuery.getManyAndCount();
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Filter Operators
|
|
57
|
+
|
|
58
|
+
Use `FilterOperators` for where conditions:
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { FilterOperators } from '@zola_do/collection-query';
|
|
62
|
+
|
|
63
|
+
query.where.push([
|
|
64
|
+
{ column: 'status', value: 'active', operator: FilterOperators.Equals },
|
|
65
|
+
{ column: 'createdAt', value: '2024-01-01', operator: FilterOperators.Gte },
|
|
66
|
+
]);
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Encoding Queries
|
|
70
|
+
|
|
71
|
+
Encode a `CollectionQuery` back to a URL string:
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
import { encodeCollectionQuery } from '@zola_do/collection-query';
|
|
75
|
+
|
|
76
|
+
const queryString = encodeCollectionQuery(query);
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Exports
|
|
80
|
+
|
|
81
|
+
- `decodeCollectionQuery` — Parse query string to CollectionQuery
|
|
82
|
+
- `encodeCollectionQuery` — Serialize CollectionQuery to string
|
|
83
|
+
- `QueryConstructor` — Build TypeORM queries from CollectionQuery
|
|
84
|
+
- `FilterOperators` — Filter operator constants
|
|
85
|
+
- `FilterSeparators` — Separator constants for query strings
|
|
86
|
+
|
|
87
|
+
## Related Packages
|
|
88
|
+
|
|
89
|
+
- [@zola_do/core](../core) — Shared entities and types
|
|
90
|
+
- [@zola_do/crud](../crud) — Uses collection-query for list endpoints
|
|
91
|
+
- [@zola_do/interceptors](../interceptors) — TenantInterceptor extends query with tenant filters
|