ng-qubee 3.0.0 → 3.2.0

package/README.md

@@ -15,7 +15,7 @@ NgQubee is a Query Builder for Angular. Easily compose your API requests without
 - Pagination ready
 - Reactive, as the results are emitted with a RxJS Observable
 - Developed with a test-driven approach
-- **Multi-driver support**: Laravel (pagination-only), Spatie Query Builder, and NestJS (nestjs-paginate)
+- **Multi-driver support**: JSON:API, Laravel (pagination-only), Spatie Query Builder, and NestJS (nestjs-paginate)
 
 ## We love it, we use it ❤️
 NgQubee uses some open source projects to work properly:
@@ -41,16 +41,46 @@ npm  i  ng-qubee
 
 ## Drivers
 
-NgQubee supports three drivers out of the box. A driver **must** be specified in the configuration:
+NgQubee supports four drivers out of the box. A driver **must** be specified in the configuration:
 
 | Driver | Backend | Request Format | Response Format |
 |---|---|---|---|
+| **JSON:API** | Any JSON:API-compliant backend | `filter[field]=value`, `sort=-field`, `page[number]=N&page[size]=N` | Nested: `{ data, meta: {...}, links: {...} }` |
 | **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: {...} }` |
 
 ## Usage
 
+### JSON:API Driver
+
+The JSON:API driver generates URIs compatible with any [JSON:API](https://jsonapi.org/format/)-compliant backend (Rails, Django, .NET, Java, Elixir, etc.):
+
+```typescript
+import { DriverEnum } from 'ng-qubee';
+
+// Standalone approach
+bootstrapApplication(AppComponent, {
+  providers: [provideNgQubee({ driver: DriverEnum.JSON_API })]
+});
+
+// Module approach
+@NgModule({
+  imports: [
+    NgQubeeModule.forRoot({ driver: DriverEnum.JSON_API })
+  ]
+})
+export class AppModule {}
+```
+
+The JSON:API driver supports:
+
+-  **Filters** are composed as `filter[field]=value`
+-  **Fields** are composed as `fields[type]=col1,col2`
+-  **Includes** are composed as `include=author,comments.author`
+-  **Sort** is composed as `sort=-created_at,name` (`-` prefix = DESC)
+-  **Pagination** uses bracket notation: `page[number]=1&page[size]=15`
+
 ### Laravel Driver (pagination-only)
 
 The Laravel driver provides basic pagination — limit and page parameters only. No filters, sorts, fields, or includes are supported.
@@ -146,6 +176,27 @@ The NestJS driver generates URIs compatible with [nestjs-paginate](https://githu
 -  **Limit** is composed as `limit=15`
 -  **Page** is composed as `page=1`
 
+### 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:
@@ -166,7 +217,7 @@ this._ngQubeeService.setResource('users');
 This is necessary to build the prefix of the URI (/users)
 
 
-### Fields (Spatie only)
+### Fields (JSON:API + Spatie)
 Fields can be selected as following:
 
 ```typescript
@@ -184,7 +235,7 @@ this._ngQubeeService.addSelect('id', 'name', 'email');
 
 Will output _/users?select=id,name,email_
 
-### Filters (Spatie + NestJS)
+### Filters (JSON:API + Spatie + NestJS)
 Filters are applied as following:
 
 ```typescript
@@ -234,7 +285,7 @@ this._ngQubeeService.addFilterOperator('name', FilterOperatorEnum.ILIKE, 'john')
 
 **Available operators:** `$eq`, `$not`, `$null`, `$in`, `$gt`, `$gte`, `$lt`, `$lte`, `$btw`, `$ilike`, `$sw`, `$contains`
 
-### Includes (Spatie only)
+### Includes (JSON:API + Spatie)
 Ask to include related models with:
 
 ```typescript
@@ -252,7 +303,7 @@ this._ngQubeeService.setSearch('john doe');
 
 Will output _/users?search=john doe_
 
-### Sort (Spatie + NestJS)
+### Sort (JSON:API + Spatie + NestJS)
 Sort elements as following:
 
 ```typescript
@@ -285,6 +336,116 @@ Default values are automatically added to the query:
 
 Always expect your query to include _limit=15&page=1_
 
+#### Fetch all (NestJS only)
+
+When the active driver is NestJS, `setLimit(-1)` is accepted as a "fetch all items" sentinel, following the [nestjs-paginate](https://github.com/ppetzold/nestjs-paginate) convention (the server must opt in via `maxLimit: -1`):
+
+```typescript
+// NestJS driver only
+this._ngQubeeService.setLimit(-1);
+```
+
+JSON:API, Laravel, and Spatie drivers reject `-1` and throw `InvalidLimitError`.
+
+#### Limit validation
+
+Limit validation is driver-scoped — each request strategy enforces its own accepted range and invalid values throw `InvalidLimitError` immediately when passed to `setLimit()`:
+
+| Driver | Accepted limit values |
+|---|---|
+| NestJS | integer `-1` (fetch all) or `>= 1` |
+| JSON:API / Laravel / Spatie | integer `>= 1` |
+
+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:
 
@@ -297,11 +458,11 @@ this._ngQubeeService.generateUri().subscribe(uri  => console.log(uri));
 All query features have corresponding delete methods:
 
 ```typescript
-// Spatie + NestJS
+// JSON:API + Spatie + NestJS
 this._ngQubeeService.deleteFilters('status', 'role');
 this._ngQubeeService.deleteSorts('created_at');
 
-// Spatie only
+// JSON:API + Spatie only
 this._ngQubeeService.deleteFields({ users: ['email'] });
 this._ngQubeeService.deleteFieldsByModel('users', 'email');
 this._ngQubeeService.deleteIncludes('profile');
@@ -323,15 +484,15 @@ this._ngQubeeService.reset();
 
 Calling a method that is not supported by the active driver throws a descriptive error immediately:
 
-| Method | Laravel | Spatie | NestJS |
-|---|---|---|---|
-| `addFilter()` / `deleteFilters()` | throws `UnsupportedFilterError` | supported | supported |
-| `addSort()` / `deleteSorts()` | throws `UnsupportedSortError` | supported | supported |
-| `addFields()` / `deleteFields()` / `deleteFieldsByModel()` | throws `UnsupportedFieldSelectionError` | supported | throws `UnsupportedFieldSelectionError` |
-| `addIncludes()` / `deleteIncludes()` | throws `UnsupportedIncludesError` | supported | throws `UnsupportedIncludesError` |
-| `addFilterOperator()` / `deleteOperatorFilters()` | throws `UnsupportedFilterOperatorError` | throws `UnsupportedFilterOperatorError` | supported |
-| `addSelect()` / `deleteSelect()` | throws `UnsupportedSelectError` | throws `UnsupportedSelectError` | supported |
-| `setSearch()` / `deleteSearch()` | throws `UnsupportedSearchError` | throws `UnsupportedSearchError` | supported |
+| Method | JSON:API | Laravel | Spatie | NestJS |
+|---|---|---|---|---|
+| `addFilter()` / `deleteFilters()` | supported | throws `UnsupportedFilterError` | supported | supported |
+| `addSort()` / `deleteSorts()` | supported | throws `UnsupportedSortError` | supported | supported |
+| `addFields()` / `deleteFields()` / `deleteFieldsByModel()` | supported | throws `UnsupportedFieldSelectionError` | supported | throws `UnsupportedFieldSelectionError` |
+| `addIncludes()` / `deleteIncludes()` | supported | throws `UnsupportedIncludesError` | supported | throws `UnsupportedIncludesError` |
+| `addFilterOperator()` / `deleteOperatorFilters()` | throws `UnsupportedFilterOperatorError` | throws `UnsupportedFilterOperatorError` | throws `UnsupportedFilterOperatorError` | supported |
+| `addSelect()` / `deleteSelect()` | throws `UnsupportedSelectError` | throws `UnsupportedSelectError` | throws `UnsupportedSelectError` | supported |
+| `setSearch()` / `deleteSearch()` | throws `UnsupportedSearchError` | throws `UnsupportedSearchError` | throws `UnsupportedSearchError` | supported |
 
 ## Pagination
 If you are working with an API that supports pagination, we have got you covered 😉 NgQubee provides:
@@ -368,6 +529,30 @@ When using the Laravel or Spatie driver, the paginated collection will check for
 - first_page_url - URL to the first page
 - last_page_url - URL to the last page
 
+### JSON:API Response Format
+
+When using the JSON:API driver, the PaginationService automatically parses nested responses:
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "current-page": 1,
+    "per-page": 10,
+    "total": 100,
+    "page-count": 10
+  },
+  "links": {
+    "first": "http://api.com/articles?page[number]=1&page[size]=10",
+    "prev": null,
+    "next": "http://api.com/articles?page[number]=2&page[size]=10",
+    "last": "http://api.com/articles?page[number]=10&page[size]=10"
+  }
+}
+```
+
+The `from` and `to` values are computed automatically from `current-page` and `per-page` when not present in the response. JSON:API meta key names vary by implementation; defaults can be fully customised via response configuration.
+
 ### NestJS Response Format
 
 When using the NestJS driver, the PaginationService automatically parses nested responses:
@@ -426,6 +611,7 @@ NgQubee is fully typed and exports all public interfaces, enums, and types for T
 import { DriverEnum, FilterOperatorEnum, SortEnum } from 'ng-qubee';
 
 // Driver options
+DriverEnum.JSON_API // 'json-api'
 DriverEnum.LARAVEL  // 'laravel' (pagination only)
 DriverEnum.SPATIE   // 'spatie'
 DriverEnum.NESTJS   // 'nestjs'