ng-qubee 3.2.0 → 3.3.0

package/README.md

@@ -41,7 +41,7 @@ npm  i  ng-qubee
 
 ## Drivers
 
-NgQubee supports four drivers out of the box. A driver **must** be specified in the configuration:
+NgQubee supports five drivers out of the box. A driver **must** be specified in the configuration:
 
 | Driver | Backend | Request Format | Response Format |
 |---|---|---|---|
@@ -49,6 +49,7 @@ NgQubee supports four drivers out of the box. A driver **must** be specified in
 | **Laravel** | Plain Laravel pagination | `limit=N&page=N` (pagination only) | Flat: `{ data, current_page, total, ... }` |
 | **Spatie** | Spatie Query Builder | `filter[field]=value`, `sort=-field` | Flat: `{ data, current_page, total, ... }` |
 | **NestJS** | nestjs-paginate | `filter.field=$operator:value`, `sortBy=field:DESC` | Nested: `{ data, meta: {...}, links: {...} }` |
+| **PostgREST** | PostgREST / Supabase | `col=eq.value`, `order=col.asc`, `limit=N&offset=M` | Bare array body + `Content-Range` header for total |
 
 ## Usage
 
@@ -176,6 +177,120 @@ The NestJS driver generates URIs compatible with [nestjs-paginate](https://githu
 -  **Limit** is composed as `limit=15`
 -  **Page** is composed as `page=1`
 
+### PostgREST / Supabase Driver
+
+The PostgREST driver generates URIs compatible with [PostgREST](https://postgrest.org/) and anything built on top of it (notably [Supabase](https://supabase.com/)):
+
+```typescript
+import { DriverEnum } from 'ng-qubee';
+
+// Standalone approach
+bootstrapApplication(AppComponent, {
+  providers: [provideNgQubee({ driver: DriverEnum.POSTGREST })]
+});
+
+// Module approach
+@NgModule({
+  imports: [
+    NgQubeeModule.forRoot({ driver: DriverEnum.POSTGREST })
+  ]
+})
+export class AppModule {}
+```
+
+The PostgREST driver supports:
+
+-  **Filters** (single value) are composed as `col=eq.value`
+-  **Filters** (multi-value) are composed as `col=in.(v1,v2,v3)` — PostgREST's native IN-list syntax
+-  **Operator filters** cover the full `FilterOperatorEnum` (eq, gt, gte, lt, lte, ilike, in, not, null, btw, sw, contains) plus PostgREST-native full-text search (`fts`, `plfts`, `phfts`, `wfts`) — see the Operator filters section below
+-  **Sorts** are composed as `order=col1.asc,col2.desc`
+-  **Select** is composed as `select=col1,col2`
+-  **Pagination** defaults to `limit=N&offset=M` on the URL and can optionally move to `Range-Unit` + `Range` HTTP headers — see the RANGE-header pagination section below
+
+#### Reading totals from the `Content-Range` header
+
+PostgREST returns a bare array body and reports the total row count in the `Content-Range` HTTP response header (e.g. `0-9/50`). Opt in by sending `Prefer: count=exact` on the request, then pass the headers to `paginate()`:
+
+```typescript
+this._http.get<User[]>(uri, {
+  observe: 'response',
+  headers: { 'Prefer': 'count=exact' }
+}).subscribe(response => {
+  const collection = this._paginationService.paginate(response.body, response.headers);
+  // collection.total, collection.page, collection.lastPage are populated
+});
+```
+
+The second argument to `paginate()` accepts Angular's `HttpHeaders`, the native `Headers` class, or a plain `Record<string, string>` — whatever shape your HTTP client emits. If you omit the header (or the server returns `Content-Range: 0-9/*`), the collection still populates `data` and `page` but leaves `total` / `lastPage` undefined — the pagination helpers' conservative defaults then kick in (`hasNextPage()` returns `true`, `isLastPage()` returns `false`).
+
+#### Operator filters
+
+Every `FilterOperatorEnum` value maps to a PostgREST prefix operator. Call `addFilterOperator(column, operator, ...values)` and the strategy emits the correct wire format:
+
+```typescript
+qb.addFilterOperator('age', FilterOperatorEnum.GTE, 18);             // age=gte.18
+qb.addFilterOperator('id', FilterOperatorEnum.IN, 1, 2, 3);           // id=in.(1,2,3)
+qb.addFilterOperator('status', FilterOperatorEnum.NOT, 'deleted');    // status=not.eq.deleted
+qb.addFilterOperator('id', FilterOperatorEnum.NOT, 1, 2);             // id=not.in.(1,2)
+qb.addFilterOperator('deletedAt', FilterOperatorEnum.NULL, true);     // deletedAt=is.null
+qb.addFilterOperator('deletedAt', FilterOperatorEnum.NULL, false);    // deletedAt=is.not.null
+qb.addFilterOperator('price', FilterOperatorEnum.BTW, 10, 100);       // price=gte.10&price=lte.100
+qb.addFilterOperator('email', FilterOperatorEnum.SW, 'admin');        // email=like.admin*
+qb.addFilterOperator('name', FilterOperatorEnum.CONTAINS, 'john');    // name=ilike.%john%
+qb.addFilterOperator('description', FilterOperatorEnum.FTS, 'rat');   // description=fts.rat
+qb.addFilterOperator('description', FilterOperatorEnum.PLFTS, 'a b'); // description=plfts.a b
+qb.addFilterOperator('description', FilterOperatorEnum.PHFTS, 'a b'); // description=phfts.a b
+qb.addFilterOperator('description', FilterOperatorEnum.WFTS, 'a -b'); // description=wfts.a -b
+```
+
+Value shape rules enforced at call time (throw `InvalidFilterOperatorValueError`):
+- `BTW` — exactly 2 values (`[min, max]`).
+- `NULL` — exactly 1 boolean value (`true` → `IS NULL`, `false` → `IS NOT NULL`).
+
+All other operators let PostgREST validate server-side.
+
+The four `*FTS` operators are PostgREST's full-text search variants (`to_tsquery`, `plainto_tsquery`, `phraseto_tsquery`, `websearch_to_tsquery`). They're column-scoped — pick the column to search, pass the term. Language modifiers (`fts(english).term`) are not supported in this release.
+
+#### RANGE-header pagination (alternative to limit/offset)
+
+PostgREST also accepts pagination via the `Range` HTTP request header instead of URL query params. Opt in via `IConfig.pagination`:
+
+```typescript
+import { DriverEnum, PaginationModeEnum } from 'ng-qubee';
+
+provideNgQubee({
+  driver: DriverEnum.POSTGREST,
+  pagination: PaginationModeEnum.RANGE
+});
+```
+
+When `RANGE` is active, `generateUri()` omits `limit` and `offset` from the URL and `NgQubeeService.paginationHeaders()` returns the headers the consumer applies to the HTTP request:
+
+```typescript
+const uri = await firstValueFrom(qb.generateUri());
+const extraHeaders = qb.paginationHeaders();  // { 'Range-Unit': 'items', 'Range': '0-9' }
+
+this._http.get<User[]>(uri, {
+  observe: 'response',
+  headers: { 'Prefer': 'count=exact', ...extraHeaders }
+}).subscribe(resp => this._pagination.paginate(resp.body, resp.headers));
+```
+
+`paginationHeaders()` returns `null` for any driver that doesn't use header-based pagination — safe to spread into a headers map unconditionally with the nullish-coalescing pattern above.
+
+#### Feature matrix
+
+| Method | Supported? | Notes |
+|---|---|---|
+| `addFilter` / `deleteFilters` | ✓ | Implicit `eq`; multi-value becomes `in.(...)` |
+| `addFilterOperator` / `deleteOperatorFilters` | ✓ | All 16 operators including `FTS`/`PLFTS`/`PHFTS`/`WFTS` |
+| `addSort` / `deleteSorts` | ✓ | Emits `order=col.asc,col.desc` |
+| `addSelect` / `deleteSelect` | ✓ | Flat column selection |
+| `setLimit` / `setPage` | ✓ | `offset` derived from `page` (QUERY mode) or emitted via `Range` header (RANGE mode) |
+| `addFields` / `deleteFields` / `deleteFieldsByModel` | ✗ | Throws `UnsupportedFieldSelectionError`. Per-type field selection is a JSON:API/Spatie concept; use `addSelect` for PostgREST's column pruning. |
+| `addIncludes` / `deleteIncludes` | ✗ | Throws `UnsupportedIncludesError`. PostgREST uses embedded resources via `select=col,rel(*)` — tracked as #66. |
+| `setSearch` / `deleteSearch` | ✗ | Throws `UnsupportedSearchError`. PostgREST's FTS operators are per-column — use `addFilterOperator(col, FilterOperatorEnum.FTS, term)` instead. |
+
 ### Per-component instances
 
 By default, `provideNgQubee()` / `NgQubeeModule.forRoot()` register `NgQubeeService` at the environment injector, so every component that injects it shares the same query-builder state. If you need a dedicated instance — e.g. a feature component whose filters and pagination must not bleed into the app-wide one — spread `provideNgQubeeInstance()` into the component's `providers`: