ng-qubee 3.1.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,141 @@ 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`:
+
+```typescript
+import { Component } from '@angular/core';
+import { NgQubeeService, provideNgQubeeInstance } from 'ng-qubee';
+
+@Component({
+  selector: 'app-product-list',
+  standalone: true,
+  providers: [...provideNgQubeeInstance()],
+  template: '...'
+})
+export class ProductListComponent {
+  constructor(private _qb: NgQubeeService) {}
+}
+```
+
+The component gets its own `NgQubeeService`, `NestService`, and `PaginationService`. The driver, strategies, and options are inherited from the environment injector configured by `provideNgQubee()` — you still configure the library once at bootstrap.
+
 ## Query Builder API
 
 For composing queries, the first step is to inject the proper NgQubeeService:
@@ -337,6 +473,94 @@ Limit validation is driver-scoped — each request strategy enforces its own acc
 
 Non-integer values, zero, negative numbers (other than `-1` for NestJS), `NaN`, and `Infinity` are all rejected.
 
+#### Auto-reset of page on result-set-changing mutations
+
+Any mutation that changes *which records* the server would return also resets `state.page` to `1` automatically. Staying on page 5 of an old result set after changing filters is almost always a bug, so the library makes the reset explicit:
+
+| Resets page to 1 | Does NOT reset page |
+|---|---|
+| `setLimit()` | `setBaseUrl()` |
+| `setResource()` | `setPage()` |
+| `setSearch()` / `deleteSearch()` | `addFields()` / `deleteFields()` / `deleteFieldsByModel()` |
+| `addFilter()` / `deleteFilters()` | `addIncludes()` / `deleteIncludes()` |
+| `addFilterOperator()` / `deleteOperatorFilters()` | `addSelect()` / `deleteSelect()` |
+| `addSort()` / `deleteSorts()` | |
+
+Rule of thumb: if a mutation changes the record *set* (filters, sort, search, limit, resource), page resets. If it only changes the record *shape* (fields, includes, select), page stays. If you intentionally want to keep the previous page number, call `setPage(n)` again after the mutation.
+
+### Pagination navigation
+
+The service exposes a fluent navigation surface so you can wire a standard paginator UI (Prev / N of M / Next) with no manual bookkeeping. All navigation methods return `this` and can be chained.
+
+```typescript
+this._ngQubeeService.nextPage().generateUri().subscribe(uri => /* fire the request */);
+this._ngQubeeService.previousPage();
+this._ngQubeeService.firstPage();
+this._ngQubeeService.lastPage();
+this._ngQubeeService.goToPage(3);
+```
+
+#### Auto-sync from `PaginationService.paginate()`
+
+When you hand a paginated response to `PaginationService.paginate()`, the library automatically copies the response's `page` and `lastPage` back into the query-builder state. That means `lastPage()`, `goToPage(n)` bounds checks, and the predicates below become accurate immediately — you don't thread the collection's `lastPage` back in yourself.
+
+```typescript
+this._paginationService.paginate(response); // auto-writes page + lastPage
+this._ngQubeeService.lastPage();            // now safe; jumps to the last page
+```
+
+The auto-sync only flips `isLastPageKnown` to `true` when the response carries a **positive integer** `lastPage`. Server-emitted `0` (empty collection) and absent fields leave the flag `false` — the helpers fall back to their conservative defaults.
+
+#### Predicates and accessors
+
+Template-safe methods for driving button disable-states and labels:
+
+```typescript
+qb.isFirstPage();     // true on page 1
+qb.isLastPage();      // true only when bounds known and page === lastPage
+qb.hasNextPage();     // true when bounds unknown, or page < lastPage
+qb.hasPreviousPage(); // true when page > 1
+qb.currentPage();     // state.page (always safe)
+qb.totalPages();      // state.lastPage (throws if never synced)
+```
+
+Angular template wiring:
+
+```html
+<button [disabled]="qb.isFirstPage()" (click)="qb.previousPage()">Prev</button>
+<span>Page {{ qb.currentPage() }} of {{ qb.totalPages() }}</span>
+<button [disabled]="qb.isLastPage()" (click)="qb.nextPage()">Next</button>
+```
+
+For the `qb.totalPages()` template usage above, either call `paginate()` at least once before the template renders, or guard the display with `*ngIf="qb.hasNextPage() || !qb.isFirstPage()"` / by reading `qb.nest().isLastPageKnown` directly.
+
+#### Error behavior
+
+| Helper | Throws | When |
+|---|---|---|
+| `nextPage()` | — | Never throws. No-op when already at `lastPage` (bounds known). |
+| `previousPage()` | — | Never throws. No-op at page 1. |
+| `firstPage()` | — | Never throws. |
+| `lastPage()` | `PaginationNotSyncedError` | `paginate()` has never run (`state.isLastPageKnown` is `false`). |
+| `goToPage(n)` | `InvalidPageNumberError` | `n` is not a positive integer, or exceeds `lastPage` when bounds are known. |
+| `isFirstPage()` / `isLastPage()` / `hasNextPage()` / `hasPreviousPage()` | — | Template-safe. Conservative defaults when bounds unknown. |
+| `currentPage()` | — | Always safe. |
+| `totalPages()` | `PaginationNotSyncedError` | `paginate()` has never run. Guard with `nest().isLastPageKnown` for a non-throwing check. |
+
+#### Guarding the imperative "jump to last" button
+
+`lastPage()` and `totalPages()` need a synced response. A safe pattern:
+
+```html
+<button
+  [disabled]="!qb.nest().isLastPageKnown || qb.isLastPage()"
+  (click)="qb.lastPage()">
+  Last
+</button>
+```
+
+The `isLastPageKnown` read short-circuits before `qb.lastPage()` could throw.
+
 ### Retrieving data
 URI is generated invoking the _generateUri_ method of the NgQubeeService. An observable is returned and the URI will be emitted: