ng-qubee 3.0.0 → 3.2.0

package/fesm2022/ng-qubee.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { signal, computed, Injectable, Inject, Optional, NgModule, makeEnvironmentProviders } from '@angular/core';
+import { signal, computed, Injectable, InjectionToken, Inject, makeEnvironmentProviders, NgModule } from '@angular/core';
 import { BehaviorSubject, filter, throwError } from 'rxjs';
 import * as qs from 'qs';
 
@@ -74,11 +74,43 @@ class PaginatedCollection {
  */
 var DriverEnum;
 (function (DriverEnum) {
+    DriverEnum["JSON_API"] = "json-api";
     DriverEnum["LARAVEL"] = "laravel";
     DriverEnum["NESTJS"] = "nestjs";
     DriverEnum["SPATIE"] = "spatie";
 })(DriverEnum || (DriverEnum = {}));
 
+/**
+ * Resolved query parameter key names with defaults applied
+ *
+ * Maps logical query concepts to the actual query parameter names
+ * used in the generated URI. Unset values fall back to defaults.
+ */
+class QueryBuilderOptions {
+    appends;
+    fields;
+    filters;
+    includes;
+    limit;
+    page;
+    search;
+    select;
+    sort;
+    sortBy;
+    constructor(options) {
+        this.appends = options.appends || 'append';
+        this.fields = options.fields || 'fields';
+        this.filters = options.filters || 'filter';
+        this.includes = options.includes || 'include';
+        this.limit = options.limit || 'limit';
+        this.page = options.page || 'page';
+        this.search = options.search || 'search';
+        this.select = options.select || 'select';
+        this.sort = options.sort || 'sort';
+        this.sortBy = options.sortBy || 'sortBy';
+    }
+}
+
 /**
  * Resolved response field key names with defaults applied
  *
@@ -121,6 +153,31 @@ class ResponseOptions {
         this.total = options.total || 'total';
     }
 }
+/**
+ * Pre-configured ResponseOptions for the JSON:API driver
+ *
+ * Uses dot-notation paths to access nested values in the JSON:API response format.
+ * JSON:API meta key names vary by implementation; these defaults cover the most
+ * common conventions and can be fully customised via `IPaginationConfig`.
+ */
+class JsonApiResponseOptions extends ResponseOptions {
+    constructor(options) {
+        super({
+            currentPage: options.currentPage || 'meta.current-page',
+            data: options.data || 'data',
+            firstPageUrl: options.firstPageUrl || 'links.first',
+            from: options.from || 'meta.from',
+            lastPage: options.lastPage || 'meta.page-count',
+            lastPageUrl: options.lastPageUrl || 'links.last',
+            nextPageUrl: options.nextPageUrl || 'links.next',
+            path: options.path || 'path',
+            perPage: options.perPage || 'meta.per-page',
+            prevPageUrl: options.prevPageUrl || 'links.prev',
+            to: options.to || 'meta.to',
+            total: options.total || 'meta.total'
+        });
+    }
+}
 /**
  * Pre-configured ResponseOptions for the NestJS driver
  *
@@ -145,131 +202,6 @@ class NestjsResponseOptions extends ResponseOptions {
     }
 }
 
-/**
- * Error thrown when per-model field selection is attempted with a driver that does not support it
- *
- * Per-model field selection is only supported by the Spatie driver.
- * Use `addSelect()` for NestJS flat field selection.
- */
-class UnsupportedFieldSelectionError extends Error {
-    constructor() {
-        super('Per-model field selection is only supported by the Spatie driver. Use addSelect() for NestJS.');
-        this.name = 'UnsupportedFieldSelectionError';
-    }
-}
-
-/**
- * Error thrown when filters are attempted with a driver that does not support them
- *
- * Filters are only supported by the Spatie and NestJS drivers.
- */
-class UnsupportedFilterError extends Error {
-    constructor() {
-        super('Filters are only supported by the Spatie and NestJS drivers.');
-        this.name = 'UnsupportedFilterError';
-    }
-}
-
-/**
- * Error thrown when filter operators are attempted with a driver that does not support them
- *
- * Filter operators are only supported by the NestJS driver.
- * Use `addFilter()` for Spatie implicit equality filters.
- */
-class UnsupportedFilterOperatorError extends Error {
-    constructor() {
-        super('Filter operators are only supported by the NestJS driver. Use addFilter() for Spatie.');
-        this.name = 'UnsupportedFilterOperatorError';
-    }
-}
-
-/**
- * Error thrown when includes are attempted with a driver that does not support them
- *
- * Includes are only supported by the Spatie driver.
- */
-class UnsupportedIncludesError extends Error {
-    constructor() {
-        super('Includes are only supported by the Spatie driver.');
-        this.name = 'UnsupportedIncludesError';
-    }
-}
-
-/**
- * Error thrown when search is attempted with a driver that does not support it
- *
- * Search is only supported by the NestJS driver.
- */
-class UnsupportedSearchError extends Error {
-    constructor() {
-        super('Search is only supported by the NestJS driver.');
-        this.name = 'UnsupportedSearchError';
-    }
-}
-
-/**
- * Error thrown when flat field selection is attempted with a driver that does not support it
- *
- * Flat field selection is only supported by the NestJS driver.
- * Use `addFields()` for Spatie per-model field selection.
- */
-class UnsupportedSelectError extends Error {
-    constructor() {
-        super('Flat field selection is only supported by the NestJS driver. Use addFields() for Spatie.');
-        this.name = 'UnsupportedSelectError';
-    }
-}
-
-/**
- * Error thrown when sorts are attempted with a driver that does not support them
- *
- * Sorts are only supported by the Spatie and NestJS drivers.
- */
-class UnsupportedSortError extends Error {
-    constructor() {
-        super('Sorts are only supported by the Spatie and NestJS drivers.');
-        this.name = 'UnsupportedSortError';
-    }
-}
-
-/**
- * Resolved query parameter key names with defaults applied
- *
- * Maps logical query concepts to the actual query parameter names
- * used in the generated URI. Unset values fall back to defaults.
- */
-class QueryBuilderOptions {
-    appends;
-    fields;
-    filters;
-    includes;
-    limit;
-    page;
-    search;
-    select;
-    sort;
-    sortBy;
-    constructor(options) {
-        this.appends = options.appends || 'append';
-        this.fields = options.fields || 'fields';
-        this.filters = options.filters || 'filter';
-        this.includes = options.includes || 'include';
-        this.limit = options.limit || 'limit';
-        this.page = options.page || 'page';
-        this.search = options.search || 'search';
-        this.select = options.select || 'select';
-        this.sort = options.sort || 'sort';
-        this.sortBy = options.sortBy || 'sortBy';
-    }
-}
-
-class InvalidLimitError extends Error {
-    constructor(limit) {
-        super(`Invalid limit value: Limit must be a positive integer greater than 0. Received: ${limit}`);
-        this.name = 'InvalidLimitError';
-    }
-}
-
 /**
  * Error thrown when an invalid resource name is provided
  *
@@ -294,6 +226,8 @@ const INITIAL_STATE = {
     fields: {},
     filters: {},
     includes: [],
+    isLastPageKnown: false,
+    lastPage: 1,
     limit: 15,
     operatorFilters: [],
     page: 1,
@@ -333,15 +267,17 @@ class NestService {
     }
     /**
      * Set the limit for paginated results
-     * Must be a positive integer greater than 0
+     *
+     * This setter performs a raw state write. Validation of the value is the
+     * responsibility of the active request strategy and is enforced upstream
+     * by `NgQubeeService.setLimit()`, because the accepted range depends on
+     * the driver (e.g. nestjs-paginate accepts `-1` for "fetch all").
      *
      * @param {number} limit - The number of items per page
-     * @throws {InvalidLimitError} If limit is not a positive integer
      * @example
      * service.limit = 25;
      */
     set limit(limit) {
-        this._validateLimit(limit);
         this._nest.update(nest => ({
             ...nest,
             limit
@@ -382,18 +318,6 @@ class NestService {
     _clone(obj) {
         return JSON.parse(JSON.stringify(obj));
     }
-    /**
-     * Validates that the limit is a positive integer
-     *
-     * @param {number} limit - The limit value to validate
-     * @throws {InvalidLimitError} If limit is not a positive integer
-     * @private
-     */
-    _validateLimit(limit) {
-        if (!Number.isInteger(limit) || limit < 1) {
-            throw new InvalidLimitError(limit);
-        }
-    }
     /**
      * Validates that the page number is a positive integer
      *
@@ -693,6 +617,25 @@ class NestService {
             search
         }));
     }
+    /**
+     * Atomically record the `lastPage` value from a paginated response and
+     * flip `isLastPageKnown` to `true`
+     *
+     * Called exclusively by `PaginationService.paginate()` as part of the
+     * auto-sync contract; not intended to be invoked by consumers directly.
+     * Keeping the two fields under a single write guarantees they cannot
+     * drift out of sync.
+     *
+     * @param {number} lastPage - The last page number parsed from the most recent paginated response
+     * @return {void}
+     */
+    syncLastPage(lastPage) {
+        this._nest.update(nest => ({
+            ...nest,
+            isLastPageKnown: true,
+            lastPage
+        }));
+    }
     /**
      * Reset the query builder state to initial values
      * Clears all fields, filters, includes, sorts, and resets pagination
@@ -711,80 +654,228 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
             type: Injectable
         }], ctorParameters: () => [] });
 
-class NgQubeeService {
-    _nestService;
-    /**
-     * The active pagination driver
-     */
-    _driver;
-    /**
-     * Resolved query parameter key name options
-     */
-    _options;
-    /**
-     * The request strategy that builds URIs for the active driver
-     */
-    _requestStrategy;
-    /**
-     * Internal BehaviorSubject that holds the latest generated URI
-     */
-    _uri$ = new BehaviorSubject('');
-    /**
-     * Observable that emits non-empty generated URIs
-     */
-    uri$ = this._uri$.asObservable().pipe(filter(uri => !!uri));
-    constructor(_nestService, requestStrategy, driver, options = {}) {
-        this._nestService = _nestService;
-        this._driver = driver;
-        this._options = new QueryBuilderOptions(options);
-        this._requestStrategy = requestStrategy;
-    }
+/**
+ * Thrown when a pagination helper that needs `state.lastPage` is called
+ * before `PaginationService.paginate()` has ever synced a value.
+ *
+ * Examples: `NgQubeeService.lastPage()`, `NgQubeeService.totalPages()`.
+ *
+ * Safe-for-templates predicates (`isLastPage`, `hasNextPage`, etc.) do not
+ * throw and return conservative defaults instead.
+ */
+class PaginationNotSyncedError extends Error {
     /**
-     * Assert that the active driver is one of the allowed drivers
-     *
-     * @param allowed - The allowed drivers
-     * @param error - The error to throw if the driver is not allowed
-     * @throws The provided error if the active driver is not in the allowed list
+     * @param action - Short imperative describing what the caller was trying
+     * to do (e.g. "navigate to last page", "read totalPages"). Surfaced in
+     * the error message so the cause is obvious at the call site.
      */
-    _assertDriver(allowed, error) {
-        if (!allowed.includes(this._driver)) {
-            throw error;
-        }
+    constructor(action) {
+        super(`Cannot ${action}: no paginated response has been synced yet. Call PaginationService.paginate() at least once first.`);
+        this.name = 'PaginationNotSyncedError';
     }
-    /**
-     * Add fields to the select statement for the given model (Spatie only)
-     *
-     * @param model - Model that holds the fields
-     * @param fields - Fields to select
-     * @returns {this}
-     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
-     */
-    addFields(model, fields) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        if (!fields.length) {
-            return this;
-        }
-        this._nestService.addFields({ [model]: fields });
-        return this;
+}
+
+/**
+ * Error thrown when per-model field selection is attempted with a driver that does not support it
+ *
+ * Per-model field selection is only supported by the Spatie driver.
+ * Use `addSelect()` for NestJS flat field selection.
+ */
+class UnsupportedFieldSelectionError extends Error {
+    constructor() {
+        super('Per-model field selection is only supported by the Spatie driver. Use addSelect() for NestJS.');
+        this.name = 'UnsupportedFieldSelectionError';
     }
-    /**
-     * Add a filter with the given value(s) (Spatie and NestJS only)
-     *
-     * Produces: `filter[field]=value` (Spatie) or `filter.field=value` (NestJS)
-     *
-     * @param {string} field - Name of the field to filter
-     * @param {(string | number | boolean)[]} values - The needle(s)
-     * @returns {this}
+}
+
+/**
+ * Error thrown when filters are attempted with a driver that does not support them
+ *
+ * Filters are only supported by the Spatie and NestJS drivers.
+ */
+class UnsupportedFilterError extends Error {
+    constructor() {
+        super('Filters are only supported by the Spatie and NestJS drivers.');
+        this.name = 'UnsupportedFilterError';
+    }
+}
+
+/**
+ * Error thrown when filter operators are attempted with a driver that does not support them
+ *
+ * Filter operators are only supported by the NestJS driver.
+ * Use `addFilter()` for Spatie implicit equality filters.
+ */
+class UnsupportedFilterOperatorError extends Error {
+    constructor() {
+        super('Filter operators are only supported by the NestJS driver. Use addFilter() for Spatie.');
+        this.name = 'UnsupportedFilterOperatorError';
+    }
+}
+
+/**
+ * Error thrown when includes are attempted with a driver that does not support them
+ *
+ * Includes are only supported by the Spatie driver.
+ */
+class UnsupportedIncludesError extends Error {
+    constructor() {
+        super('Includes are only supported by the Spatie driver.');
+        this.name = 'UnsupportedIncludesError';
+    }
+}
+
+/**
+ * Error thrown when search is attempted with a driver that does not support it
+ *
+ * Search is only supported by the NestJS driver.
+ */
+class UnsupportedSearchError extends Error {
+    constructor() {
+        super('Search is only supported by the NestJS driver.');
+        this.name = 'UnsupportedSearchError';
+    }
+}
+
+/**
+ * Error thrown when flat field selection is attempted with a driver that does not support it
+ *
+ * Flat field selection is only supported by the NestJS driver.
+ * Use `addFields()` for Spatie per-model field selection.
+ */
+class UnsupportedSelectError extends Error {
+    constructor() {
+        super('Flat field selection is only supported by the NestJS driver. Use addFields() for Spatie.');
+        this.name = 'UnsupportedSelectError';
+    }
+}
+
+/**
+ * Error thrown when sorts are attempted with a driver that does not support them
+ *
+ * Sorts are only supported by the Spatie and NestJS drivers.
+ */
+class UnsupportedSortError extends Error {
+    constructor() {
+        super('Sorts are only supported by the Spatie and NestJS drivers.');
+        this.name = 'UnsupportedSortError';
+    }
+}
+
+/**
+ * Injection token for the active pagination driver
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` from the
+ * user-supplied `IConfig.driver`. Services read it to gate driver-specific
+ * behavior (e.g. `NgQubeeService._assertDriver`).
+ */
+const NG_QUBEE_DRIVER = new InjectionToken('NG_QUBEE_DRIVER');
+/**
+ * Injection token for the resolved request URI strategy
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` based on the
+ * active driver. Used by `NgQubeeService` to build request URIs.
+ */
+const NG_QUBEE_REQUEST_STRATEGY = new InjectionToken('NG_QUBEE_REQUEST_STRATEGY');
+/**
+ * Injection token for the resolved request query-parameter key options
+ *
+ * Provided as a fully-built `QueryBuilderOptions` instance. `provideNgQubee()`
+ * constructs it from `IConfig.request`; consumers don't interact with this
+ * token directly.
+ */
+const NG_QUBEE_REQUEST_OPTIONS = new InjectionToken('NG_QUBEE_REQUEST_OPTIONS');
+/**
+ * Injection token for the resolved response parsing strategy
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` based on the
+ * active driver. Used by `PaginationService` to parse paginated responses.
+ */
+const NG_QUBEE_RESPONSE_STRATEGY = new InjectionToken('NG_QUBEE_RESPONSE_STRATEGY');
+/**
+ * Injection token for the resolved response field-key options
+ *
+ * Provided as a fully-built `ResponseOptions` instance (or a driver-specific
+ * subclass like `JsonApiResponseOptions` / `NestjsResponseOptions`).
+ * `provideNgQubee()` constructs the correct variant from `IConfig.response`.
+ */
+const NG_QUBEE_RESPONSE_OPTIONS = new InjectionToken('NG_QUBEE_RESPONSE_OPTIONS');
+
+class NgQubeeService {
+    _nestService;
+    /**
+     * The active pagination driver
+     */
+    _driver;
+    /**
+     * Resolved query parameter key name options
+     */
+    _options;
+    /**
+     * The request strategy that builds URIs for the active driver
+     */
+    _requestStrategy;
+    /**
+     * Internal BehaviorSubject that holds the latest generated URI
+     */
+    _uri$ = new BehaviorSubject('');
+    /**
+     * Observable that emits non-empty generated URIs
+     */
+    uri$ = this._uri$.asObservable().pipe(filter(uri => !!uri));
+    constructor(_nestService, requestStrategy, driver, options = new QueryBuilderOptions({})) {
+        this._nestService = _nestService;
+        this._driver = driver;
+        this._options = options;
+        this._requestStrategy = requestStrategy;
+    }
+    /**
+     * Assert that the active driver is one of the allowed drivers
+     *
+     * @param allowed - The allowed drivers
+     * @param error - The error to throw if the driver is not allowed
+     * @throws The provided error if the active driver is not in the allowed list
+     */
+    _assertDriver(allowed, error) {
+        if (!allowed.includes(this._driver)) {
+            throw error;
+        }
+    }
+    /**
+     * Add fields to the select statement for the given model (JSON:API and Spatie only)
+     *
+     * @param model - Model that holds the fields
+     * @param fields - Fields to select
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    addFields(model, fields) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.addFields({ [model]: fields });
+        return this;
+    }
+    /**
+     * Add a filter with the given value(s) (JSON:API, NestJS, and Spatie)
+     *
+     * Produces: `filter[field]=value` (JSON:API / Spatie) or `filter.field=value` (NestJS)
+     *
+     * @param {string} field - Name of the field to filter
+     * @param {(string | number | boolean)[]} values - The needle(s)
+     * @returns {this}
      * @throws {UnsupportedFilterError} If the active driver does not support filters
      */
     addFilter(field, ...values) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedFilterError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
         if (!values.length) {
             return this;
         }
         this._nestService.addFilters({
             [field]: values
         });
+        this._nestService.page = 1;
         return this;
     }
     /**
@@ -804,17 +895,18 @@ class NgQubeeService {
             return this;
         }
         this._nestService.addOperatorFilters([{ field, operator, values }]);
+        this._nestService.page = 1;
         return this;
     }
     /**
-     * Add related entities to include in the request (Spatie only)
+     * Add related entities to include in the request (JSON:API and Spatie only)
      *
      * @param {string[]} models - Models to include
      * @returns {this}
      * @throws {UnsupportedIncludesError} If the active driver does not support includes
      */
     addIncludes(...models) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedIncludesError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
         if (!models.length) {
             return this;
         }
@@ -839,7 +931,7 @@ class NgQubeeService {
         return this;
     }
     /**
-     * Add a field with a sort criteria (Spatie and NestJS only)
+     * Add a field with a sort criteria (JSON:API, NestJS, and Spatie)
      *
      * @param field - Field to use for sorting
      * @param {SortEnum} order - A value from the SortEnum enumeration
@@ -847,15 +939,25 @@ class NgQubeeService {
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     addSort(field, order) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedSortError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedSortError());
         this._nestService.addSort({
             field,
             order
         });
+        this._nestService.page = 1;
         return this;
     }
     /**
-     * Delete selected fields for the given models in the current query builder state (Spatie only)
+     * Get the current page number
+     *
+     * @remarks Always safe to call. Thin accessor over the internal state's `page` field.
+     * @returns The current page number
+     */
+    currentPage() {
+        return this._nestService.nest().page;
+    }
+    /**
+     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
      * ```
      * ngQubeeService.deleteFields({
@@ -869,12 +971,12 @@ class NgQubeeService {
      * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
      */
     deleteFields(fields) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
         this._nestService.deleteFields(fields);
         return this;
     }
     /**
-     * Delete selected fields for the given model in the current query builder state (Spatie only)
+     * Delete selected fields for the given model in the current query builder state (JSON:API and Spatie only)
      *
      * ```
      * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
@@ -886,7 +988,7 @@ class NgQubeeService {
      * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
      */
     deleteFieldsByModel(model, ...fields) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
         if (!fields.length) {
             return this;
         }
@@ -896,29 +998,30 @@ class NgQubeeService {
         return this;
     }
     /**
-     * Remove given filters from the query builder state (Spatie and NestJS only)
+     * Remove given filters from the query builder state (JSON:API, NestJS, and Spatie)
      *
      * @param {string[]} filters - Filters to remove
      * @returns {this}
      * @throws {UnsupportedFilterError} If the active driver does not support filters
      */
     deleteFilters(...filters) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedFilterError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
         if (!filters.length) {
             return this;
         }
         this._nestService.deleteFilters(...filters);
+        this._nestService.page = 1;
         return this;
     }
     /**
-     * Remove selected related models from the query builder state (Spatie only)
+     * Remove selected related models from the query builder state (JSON:API and Spatie only)
      *
      * @param {string[]} includes - Models to remove
      * @returns {this}
      * @throws {UnsupportedIncludesError} If the active driver does not support includes
      */
     deleteIncludes(...includes) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedIncludesError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
         if (!includes.length) {
             return this;
         }
@@ -938,6 +1041,7 @@ class NgQubeeService {
             return this;
         }
         this._nestService.deleteOperatorFilters(...fields);
+        this._nestService.page = 1;
         return this;
     }
     /**
@@ -949,6 +1053,7 @@ class NgQubeeService {
     deleteSearch() {
         this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
         this._nestService.deleteSearch();
+        this._nestService.page = 1;
         return this;
     }
     /**
@@ -967,15 +1072,26 @@ class NgQubeeService {
         return this;
     }
     /**
-     * Remove sort rules from the query builder state (Spatie and NestJS only)
+     * Remove sort rules from the query builder state (JSON:API, NestJS, and Spatie)
      *
      * @param sorts - Fields used for sorting to remove
      * @returns {this}
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     deleteSorts(...sorts) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedSortError());
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedSortError());
         this._nestService.deleteSorts(...sorts);
+        this._nestService.page = 1;
+        return this;
+    }
+    /**
+     * Navigate to the first page (page 1)
+     *
+     * @remarks Never throws. Idempotent when already on page 1.
+     * @returns {this}
+     */
+    firstPage() {
+        this._nestService.page = 1;
         return this;
     }
     /**
@@ -992,6 +1108,106 @@ class NgQubeeService {
             return throwError(() => error);
         }
     }
+    /**
+     * Navigate directly to the specified page
+     *
+     * Validates integer/positive via the existing `setPage` path, and
+     * additionally rejects values that exceed `state.lastPage` when
+     * pagination bounds are known.
+     *
+     * @param n - Target page number
+     * @returns {this}
+     * @throws {InvalidPageNumberError} If `n` is not a positive integer, or if `n > state.lastPage` when `state.isLastPageKnown` is true
+     */
+    goToPage(n) {
+        const state = this._nestService.nest();
+        if (state.isLastPageKnown && n > state.lastPage) {
+            throw new InvalidPageNumberError(n);
+        }
+        this._nestService.page = n;
+        return this;
+    }
+    /**
+     * Check whether a next page exists
+     *
+     * @remarks Template-safe. Returns `true` when pagination bounds are unknown (conservative default — keeps a "Next" button enabled before the first `paginate()` call).
+     * @returns `true` if `state.page < state.lastPage` when bounds are known, or `true` when bounds are unknown
+     */
+    hasNextPage() {
+        const state = this._nestService.nest();
+        return !state.isLastPageKnown || state.page < state.lastPage;
+    }
+    /**
+     * Check whether a previous page exists
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page > 1`
+     */
+    hasPreviousPage() {
+        return this._nestService.nest().page > 1;
+    }
+    /**
+     * Check whether the current page is the first page
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page === 1`
+     */
+    isFirstPage() {
+        return this._nestService.nest().page === 1;
+    }
+    /**
+     * Check whether the current page is the last page
+     *
+     * @remarks Template-safe. Returns `false` when pagination bounds are unknown (no paginated response has been synced yet) — keeps "Next" navigation unblocked until the first `paginate()` call syncs.
+     * @returns `true` only when `state.isLastPageKnown` and `state.page === state.lastPage`
+     */
+    isLastPage() {
+        const state = this._nestService.nest();
+        return state.isLastPageKnown && state.page === state.lastPage;
+    }
+    /**
+     * Navigate to the last page known from the most recent paginated response
+     *
+     * @remarks Requires at least one `PaginationService.paginate()` call to have synced `state.lastPage`. Before that, the bound is unknown and this method throws.
+     * @returns {this}
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    lastPage() {
+        const state = this._nestService.nest();
+        if (!state.isLastPageKnown) {
+            throw new PaginationNotSyncedError('navigate to last page');
+        }
+        this._nestService.page = state.lastPage;
+        return this;
+    }
+    /**
+     * Navigate to the next page
+     *
+     * @remarks Never throws. Idempotent at the known last page (no-op). Pair with `hasNextPage()` for a disable-state binding.
+     * @returns {this}
+     */
+    nextPage() {
+        const state = this._nestService.nest();
+        if (state.isLastPageKnown && state.page >= state.lastPage) {
+            return this;
+        }
+        this._nestService.page = state.page + 1;
+        return this;
+    }
+    /**
+     * Navigate to the previous page
+     *
+     * @remarks Never throws. Idempotent at page 1 (floored). Pair with `hasPreviousPage()` for a disable-state binding.
+     * @returns {this}
+     */
+    previousPage() {
+        const state = this._nestService.nest();
+        if (state.page <= 1) {
+            return this;
+        }
+        this._nestService.page = state.page - 1;
+        return this;
+    }
     /**
      * Clear the current state and reset the Query Builder to a fresh, clean condition
      *
@@ -1012,106 +1228,482 @@ class NgQubeeService {
         return this;
     }
     /**
-     * Set the items per page number
+     * Set the items per page number
+     *
+     * Validation is delegated to the active request strategy because the
+     * accepted range is driver-specific: nestjs-paginate additionally accepts
+     * `-1` as a "fetch all" sentinel, while Laravel, Spatie, and JSON:API
+     * require a positive integer.
+     *
+     * @param limit - Number of items per page (or `-1` to fetch all, NestJS only)
+     * @returns {this}
+     * @throws {import('../errors/invalid-limit.error').InvalidLimitError} If the value is not accepted by the active driver
+     */
+    setLimit(limit) {
+        this._requestStrategy.validateLimit(limit);
+        this._nestService.limit = limit;
+        this._nestService.page = 1;
+        return this;
+    }
+    /**
+     * Set the page that the backend will use to paginate the result set
+     *
+     * @param page - Page number
+     * @returns {this}
+     */
+    setPage(page) {
+        this._nestService.page = page;
+        return this;
+    }
+    /**
+     * Set the API resource to run the query against
+     *
+     * @param {string} resource - Resource name (e.g. 'users' produces /users)
+     * @returns {this}
+     */
+    setResource(resource) {
+        this._nestService.resource = resource;
+        this._nestService.page = 1;
+        return this;
+    }
+    /**
+     * Set the search term for full-text search (NestJS only)
+     *
+     * Produces: `search=term`
+     *
+     * @param {string} search - The search term
+     * @returns {this}
+     * @throws {UnsupportedSearchError} If the active driver does not support search
+     */
+    setSearch(search) {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
+        this._nestService.setSearch(search);
+        this._nestService.page = 1;
+        return this;
+    }
+    /**
+     * Get the total number of pages reported by the most recent paginated response
+     *
+     * @remarks Throws when called before any `paginate()` has synced a value. For a non-throwing read in a template, read `nest().isLastPageKnown` first as a guard.
+     * @returns The last page number
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    totalPages() {
+        const state = this._nestService.nest();
+        if (!state.isLastPageKnown) {
+            throw new PaginationNotSyncedError('read totalPages');
+        }
+        return state.lastPage;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService, deps: [{ token: NestService }, { token: NG_QUBEE_REQUEST_STRATEGY }, { token: NG_QUBEE_DRIVER }, { token: NG_QUBEE_REQUEST_OPTIONS }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: NestService }, { type: undefined, decorators: [{
+                    type: Inject,
+                    args: [NG_QUBEE_REQUEST_STRATEGY]
+                }] }, { type: DriverEnum, decorators: [{
+                    type: Inject,
+                    args: [NG_QUBEE_DRIVER]
+                }] }, { type: QueryBuilderOptions, decorators: [{
+                    type: Inject,
+                    args: [NG_QUBEE_REQUEST_OPTIONS]
+                }] }] });
+
+class PaginationService {
+    /**
+     * The NestService instance that owns the query-builder state for this
+     * PaginationService's scope (environment-level by default, or
+     * component-level when used via `provideNgQubeeInstance()`)
+     */
+    _nestService;
+    /**
+     * Resolved response key name options
+     */
+    _options;
+    /**
+     * The response strategy that parses responses for the active driver
+     */
+    _responseStrategy;
+    constructor(nestService, responseStrategy, options = new ResponseOptions({})) {
+        this._nestService = nestService;
+        this._options = options;
+        this._responseStrategy = responseStrategy;
+    }
+    /**
+     * Transform a raw API response into a typed PaginatedCollection
+     *
+     * Delegates to the active driver's response strategy for parsing, then
+     * auto-syncs the parsed `page` and `lastPage` back into `NestService`
+     * so pagination navigation helpers on `NgQubeeService` can operate
+     * against the live server-reported bounds without consumer bookkeeping.
+     *
+     * @remarks
+     * `lastPage` is only synced when the response yields a positive integer.
+     * Server-emitted `0` (empty collection edge case) and absent fields are
+     * treated as "no useful info" and leave `isLastPageKnown: false`.
+     *
+     * @param response - The raw API response object
+     * @returns A typed PaginatedCollection instance
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response) {
+        const collection = this._responseStrategy.paginate(response, this._options);
+        this._nestService.page = collection.page;
+        if (typeof collection.lastPage === 'number' && Number.isInteger(collection.lastPage) && collection.lastPage > 0) {
+            this._nestService.syncLastPage(collection.lastPage);
+        }
+        return collection;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService, deps: [{ token: NestService }, { token: NG_QUBEE_RESPONSE_STRATEGY }, { token: NG_QUBEE_RESPONSE_OPTIONS }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: NestService }, { type: undefined, decorators: [{
+                    type: Inject,
+                    args: [NG_QUBEE_RESPONSE_STRATEGY]
+                }] }, { type: ResponseOptions, decorators: [{
+                    type: Inject,
+                    args: [NG_QUBEE_RESPONSE_OPTIONS]
+                }] }] });
+
+var SortEnum;
+(function (SortEnum) {
+    SortEnum["ASC"] = "asc";
+    SortEnum["DESC"] = "desc";
+})(SortEnum || (SortEnum = {}));
+
+/**
+ * Thrown when a limit value does not satisfy the active driver's constraints
+ *
+ * Validation is driver-scoped: most drivers require an integer `>= 1`, while
+ * the NestJS driver additionally accepts `-1` as a "fetch all items" sentinel
+ * (as documented by nestjs-paginate). The message is tailored accordingly so
+ * the caller understands which values are permitted.
+ */
+class InvalidLimitError extends Error {
+    /**
+     * @param limit - The rejected limit value
+     * @param allowFetchAll - Whether the active driver accepts `-1` (fetch all)
+     */
+    constructor(limit, allowFetchAll = false) {
+        const allowed = allowFetchAll
+            ? 'a positive integer greater than 0, or -1 to fetch all items'
+            : 'a positive integer greater than 0';
+        super(`Invalid limit value: Limit must be ${allowed}. Received: ${limit}`);
+        this.name = 'InvalidLimitError';
+    }
+}
+
+class UnselectableModelError extends Error {
+    constructor(model) {
+        super(`Unselectable Model: the selected model (${model}) is not present neither in the "model" property, nor in the includes object.`);
+    }
+}
+
+/**
+ * Request strategy for the JSON:API driver
+ *
+ * Generates URIs in the JSON:API format:
+ * - Fields: `fields[articles]=title,body&fields[people]=name`
+ * - Filters: `filter[status]=active`
+ * - Includes: `include=author,comments.author`
+ * - Pagination: `page[number]=1&page[size]=15`
+ * - Sort: `sort=-created_at,name` (- prefix = DESC)
+ *
+ * @see https://jsonapi.org/format/
+ */
+class JsonApiRequestStrategy {
+    /**
+     * Accumulator for composing the URI string
+     */
+    _uri = '';
+    /**
+     * Build a URI string from the given state using the JSON:API format
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The composed URI string
+     * @throws Error if resource is not set
+     */
+    buildUri(state, options) {
+        if (!state.resource) {
+            throw new Error('Set the resource property BEFORE adding filters or calling the url() / get() methods');
+        }
+        this._uri = '';
+        this._parseIncludes(state, options);
+        this._parseFields(state, options);
+        this._parseFilters(state, options);
+        this._parsePagination(state, options);
+        this._parseSort(state, options);
+        return this._uri;
+    }
+    /**
+     * Validate that the given limit is accepted by the JSON:API driver
+     *
+     * The JSON:API specification leaves pagination semantics to the server and
+     * does not define a "fetch all" sentinel, so only positive integers are
+     * accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && limit >= 1) {
+            return;
+        }
+        throw new InvalidLimitError(limit);
+    }
+    /**
+     * Parse and append field selection parameters
+     *
+     * Validates that each field model exists either as the main resource
+     * or in the includes list. Fields are grouped by type in bracket notation.
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated field selection parameter string
+     * @throws Error if resource is required but not set
+     * @throws UnselectableModelError if a field model is not in resource or includes
+     */
+    _parseFields(state, options) {
+        if (!Object.keys(state.fields).length) {
+            return this._uri;
+        }
+        if (!state.resource) {
+            throw new Error('While selecting fields, the -> resource <- is required');
+        }
+        if (!(state.resource in state.fields)) {
+            throw new Error(`Key ${state.resource} is missing in the fields object`);
+        }
+        const f = {};
+        for (const k in state.fields) {
+            if (state.fields.hasOwnProperty(k)) {
+                if (k !== state.resource && !state.includes.includes(k)) {
+                    throw new UnselectableModelError(k);
+                }
+                Object.assign(f, { [`${options.fields}[${k}]`]: state.fields[k].join(',') });
+            }
+        }
+        const param = `${this._prepend(state)}${qs.stringify(f, { encode: false })}`;
+        this._uri += param;
+        return param;
+    }
+    /**
+     * Parse and append filter parameters
+     *
+     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated filter parameter string
+     */
+    _parseFilters(state, options) {
+        const keys = Object.keys(state.filters);
+        if (!keys.length) {
+            return this._uri;
+        }
+        const f = {
+            [`${options.filters}`]: keys.reduce((acc, key) => {
+                return Object.assign(acc, { [key]: state.filters[key].join(',') });
+            }, {})
+        };
+        const param = `${this._prepend(state)}${qs.stringify(f, { encode: false })}`;
+        this._uri += param;
+        return param;
+    }
+    /**
+     * Parse and append include parameters
+     *
+     * Generates: `include=author,comments.author`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated include parameter string
+     */
+    _parseIncludes(state, options) {
+        if (!state.includes.length) {
+            return this._uri;
+        }
+        const param = `${this._prepend(state)}${options.includes}=${state.includes}`;
+        this._uri += param;
+        return param;
+    }
+    /**
+     * Parse and append pagination parameters in JSON:API bracket notation
+     *
+     * Generates: `page[number]=1&page[size]=15`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated pagination parameter string
+     */
+    _parsePagination(state, options) {
+        const pagination = qs.stringify({ [options.page]: { number: state.page, size: state.limit } }, { encode: false });
+        const param = `${this._prepend(state)}${pagination}`;
+        this._uri += param;
+        return param;
+    }
+    /**
+     * Parse and append sort parameters
+     *
+     * Generates: `sort=-field1,field2` where `-` prefix indicates DESC order
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated sort parameter string
+     */
+    _parseSort(state, options) {
+        let param = '';
+        if (!state.sorts.length) {
+            return param;
+        }
+        param = `${this._prepend(state)}${options.sort}=`;
+        state.sorts.forEach((sort, idx) => {
+            param += `${sort.order === SortEnum.DESC ? '-' : ''}${sort.field}`;
+            if (idx < state.sorts.length - 1) {
+                param += ',';
+            }
+        });
+        this._uri += param;
+        return param;
+    }
+    /**
+     * Determine the appropriate URI prefix based on the current accumulator state
+     *
+     * Returns the full base path with `?` for the first parameter,
+     * or `&` for subsequent parameters.
+     *
+     * @param state - The current query builder state
+     * @returns The prefix string to prepend to the next parameter
+     */
+    _prepend(state) {
+        if (this._uri) {
+            return '&';
+        }
+        return state.baseUrl ? `${state.baseUrl}/${state.resource}?` : `/${state.resource}?`;
+    }
+}
+
+/**
+ * Response strategy for the JSON:API driver
+ *
+ * Parses JSON:API pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "meta": {
+ *     "current-page": 1,
+ *     "per-page": 10,
+ *     "total": 100,
+ *     "page-count": 10,
+ *     "from": 1,
+ *     "to": 10
+ *   },
+ *   "links": {
+ *     "first": "url",
+ *     "prev": "url",
+ *     "next": "url",
+ *     "last": "url"
+ *   }
+ * }
+ * ```
+ *
+ * @see https://jsonapi.org/format/
+ */
+class JsonApiResponseStrategy {
+    /**
+     * Parse a JSON:API pagination response into a PaginatedCollection
      *
-     * @param limit - Number of items per page
-     * @returns {this}
-     */
-    setLimit(limit) {
-        this._nestService.limit = limit;
-        return this;
-    }
-    /**
-     * Set the page that the backend will use to paginate the result set
+     * Supports dot-notation key paths for accessing nested values.
+     * Computes `from` and `to` from `currentPage` and `perPage` when
+     * they are not directly available in the response.
      *
-     * @param page - Page number
-     * @returns {this}
+     * @param response - The raw API response object
+     * @param options - The response key name configuration
+     * @returns A typed PaginatedCollection instance
      */
-    setPage(page) {
-        this._nestService.page = page;
-        return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response, options) {
+        const data = this._resolve(response, options.data);
+        const currentPage = this._resolve(response, options.currentPage);
+        const total = this._resolve(response, options.total);
+        const perPage = this._resolve(response, options.perPage);
+        const lastPage = this._resolve(response, options.lastPage);
+        // Compute from/to if not directly available
+        const from = this._resolveFrom(response, options, currentPage, perPage);
+        const to = this._resolveTo(response, options, currentPage, perPage, total);
+        const prevPageUrl = this._resolve(response, options.prevPageUrl);
+        const nextPageUrl = this._resolve(response, options.nextPageUrl);
+        const firstPageUrl = this._resolve(response, options.firstPageUrl);
+        const lastPageUrl = this._resolve(response, options.lastPageUrl);
+        return new PaginatedCollection(data, currentPage, from, to, total, perPage, prevPageUrl, nextPageUrl, lastPage, firstPageUrl, lastPageUrl);
     }
     /**
-     * Set the API resource to run the query against
+     * Resolve a value from a response object using a dot-notation path
      *
-     * @param {string} resource - Resource name (e.g. 'users' produces /users)
-     * @returns {this}
+     * Supports both flat keys ('data') and nested paths ('meta.current-page').
+     *
+     * @param response - The raw response object
+     * @param path - The dot-notation path to resolve
+     * @returns The resolved value, or undefined if not found
      */
-    setResource(resource) {
-        this._nestService.resource = resource;
-        return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _resolve(response, path) {
+        return path.split('.').reduce((obj, key) => obj?.[key], response);
     }
     /**
-     * Set the search term for full-text search (NestJS only)
+     * Resolve the "from" index value
      *
-     * Produces: `search=term`
+     * If the path resolves to a value in the response, use it.
+     * Otherwise, compute it from currentPage and perPage:
+     * `(currentPage - 1) * perPage + 1`
      *
-     * @param {string} search - The search term
-     * @returns {this}
-     * @throws {UnsupportedSearchError} If the active driver does not support search
-     */
-    setSearch(search) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
-        this._nestService.setSearch(search);
-        return this;
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService, deps: [{ token: NestService }, { token: 'REQUEST_STRATEGY' }, { token: 'DRIVER' }, { token: 'QUERY_PARAMS_CONFIG', optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeService, decorators: [{
-            type: Injectable
-        }], ctorParameters: () => [{ type: NestService }, { type: undefined, decorators: [{
-                    type: Inject,
-                    args: ['REQUEST_STRATEGY']
-                }] }, { type: DriverEnum, decorators: [{
-                    type: Inject,
-                    args: ['DRIVER']
-                }] }, { type: undefined, decorators: [{
-                    type: Inject,
-                    args: ['QUERY_PARAMS_CONFIG']
-                }, {
-                    type: Optional
-                }] }] });
-
-class PaginationService {
-    /**
-     * Resolved response key name options
-     */
-    _options;
-    /**
-     * The response strategy that parses responses for the active driver
+     * @param response - The raw response object
+     * @param options - The response key name configuration
+     * @param currentPage - The current page number
+     * @param perPage - The number of items per page
+     * @returns The computed "from" index
      */
-    _responseStrategy;
-    constructor(responseStrategy, options = {}) {
-        this._options = new ResponseOptions(options);
-        this._responseStrategy = responseStrategy;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _resolveFrom(response, options, currentPage, perPage) {
+        const direct = this._resolve(response, options.from);
+        if (direct !== undefined) {
+            return direct;
+        }
+        if (currentPage && perPage) {
+            return (currentPage - 1) * perPage + 1;
+        }
+        return undefined;
     }
     /**
-     * Transform a raw API response into a typed PaginatedCollection
+     * Resolve the "to" index value
      *
-     * Delegates to the active driver's response strategy for parsing.
+     * If the path resolves to a value in the response, use it.
+     * Otherwise, compute it from currentPage, perPage, and total:
+     * `Math.min(currentPage * perPage, total)`
      *
-     * @param response - The raw API response object
-     * @returns A typed PaginatedCollection instance
+     * @param response - The raw response object
+     * @param options - The response key name configuration
+     * @param currentPage - The current page number
+     * @param perPage - The number of items per page
+     * @param total - The total number of items
+     * @returns The computed "to" index
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    paginate(response) {
-        return this._responseStrategy.paginate(response, this._options);
+    _resolveTo(response, options, currentPage, perPage, total) {
+        const direct = this._resolve(response, options.to);
+        if (direct !== undefined) {
+            return direct;
+        }
+        if (currentPage && perPage && total) {
+            return Math.min(currentPage * perPage, total);
+        }
+        return undefined;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService, deps: [{ token: 'RESPONSE_STRATEGY' }, { token: 'RESPONSE_OPTIONS', optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: PaginationService, decorators: [{
-            type: Injectable
-        }], ctorParameters: () => [{ type: undefined, decorators: [{
-                    type: Inject,
-                    args: ['RESPONSE_STRATEGY']
-                }] }, { type: undefined, decorators: [{
-                    type: Inject,
-                    args: ['RESPONSE_OPTIONS']
-                }, {
-                    type: Optional
-                }] }] });
 
 /**
  * Request strategy for the Laravel (pagination-only) driver
@@ -1137,6 +1729,21 @@ class LaravelRequestStrategy {
         const base = state.baseUrl ? `${state.baseUrl}/${state.resource}` : `/${state.resource}`;
         return `${base}?${options.limit}=${state.limit}&${options.page}=${state.page}`;
     }
+    /**
+     * Validate that the given limit is accepted by the Laravel driver
+     *
+     * Laravel pagination does not recognize `-1` as a "fetch all" sentinel,
+     * so only positive integers are accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && limit >= 1) {
+            return;
+        }
+        throw new InvalidLimitError(limit);
+    }
 }
 
 /**
@@ -1169,12 +1776,6 @@ class LaravelResponseStrategy {
     }
 }
 
-var SortEnum;
-(function (SortEnum) {
-    SortEnum["ASC"] = "asc";
-    SortEnum["DESC"] = "desc";
-})(SortEnum || (SortEnum = {}));
-
 /**
  * Request strategy for the NestJS (nestjs-paginate) driver
  *
@@ -1215,6 +1816,21 @@ class NestjsRequestStrategy {
         this._parsePage(state, options);
         return this._uri;
     }
+    /**
+     * Validate that the given limit is accepted by nestjs-paginate
+     *
+     * Accepts any integer `>= 1` as a page size, plus `-1` which nestjs-paginate
+     * interprets as "fetch all items" (server must opt-in via `maxLimit: -1`).
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not an integer, or is 0, or is a negative number other than -1
+     */
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && (limit === -1 || limit >= 1)) {
+            return;
+        }
+        throw new InvalidLimitError(limit, true);
+    }
     /**
      * Parse and append simple filter parameters
      *
@@ -1454,12 +2070,6 @@ class NestjsResponseStrategy {
     }
 }
 
-class UnselectableModelError extends Error {
-    constructor(model) {
-        super(`Unselectable Model: the selected model (${model}) is not present neither in the "model" property, nor in the includes object.`);
-    }
-}
-
 /**
  * Request strategy for the Spatie Query Builder driver
  *
@@ -1498,6 +2108,21 @@ class SpatieRequestStrategy {
         this._parseSort(state, options);
         return this._uri;
     }
+    /**
+     * Validate that the given limit is accepted by the Spatie driver
+     *
+     * Spatie query-builder does not recognize `-1` as a "fetch all" sentinel,
+     * so only positive integers are accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && limit >= 1) {
+            return;
+        }
+        throw new InvalidLimitError(limit);
+    }
     /**
      * Parse and append field selection parameters
      *
@@ -1676,8 +2301,10 @@ class SpatieResponseStrategy {
  * @param driver - The pagination driver
  * @returns The corresponding request strategy
  */
-function resolveRequestStrategy$1(driver) {
+function resolveRequestStrategy(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiRequestStrategy();
         case DriverEnum.NESTJS:
             return new NestjsRequestStrategy();
         case DriverEnum.SPATIE:
@@ -1692,8 +2319,10 @@ function resolveRequestStrategy$1(driver) {
  * @param driver - The pagination driver
  * @returns The corresponding response strategy
  */
-function resolveResponseStrategy$1(driver) {
+function resolveResponseStrategy(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiResponseStrategy();
         case DriverEnum.NESTJS:
             return new NestjsResponseStrategy();
         case DriverEnum.SPATIE:
@@ -1702,79 +2331,47 @@ function resolveResponseStrategy$1(driver) {
             return new LaravelResponseStrategy();
     }
 }
-// @dynamic
-class NgQubeeModule {
-    /**
-     * Configure NgQubee for the root module
-     *
-     * @param config - Configuration object with driver, and optional request and response settings
-     * @returns Module with providers configured for the specified driver
-     */
-    static forRoot(config) {
-        const driver = config.driver;
-        const requestStrategy = resolveRequestStrategy$1(driver);
-        const responseStrategy = resolveResponseStrategy$1(driver);
-        return {
-            ngModule: NgQubeeModule,
-            providers: [
-                NestService,
-                {
-                    deps: [NestService],
-                    provide: NgQubeeService,
-                    useFactory: (nestService) => new NgQubeeService(nestService, requestStrategy, driver, Object.assign({}, config.request))
-                },
-                {
-                    provide: PaginationService,
-                    useFactory: () => {
-                        const responseConfig = Object.assign({}, config.response);
-                        return driver === DriverEnum.NESTJS
-                            ? new PaginationService(responseStrategy, new NestjsResponseOptions(responseConfig))
-                            : new PaginationService(responseStrategy, responseConfig);
-                    }
-                }
-            ]
-        };
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule, decorators: [{
-            type: NgModule,
-            args: [{}]
-        }] });
-
 /**
- * Resolve the request strategy instance for the given driver
+ * Resolve the driver-specific `ResponseOptions` instance
  *
  * @param driver - The pagination driver
- * @returns The corresponding request strategy
+ * @param responseConfig - User-supplied response key overrides
+ * @returns A pre-built ResponseOptions (or driver-specific subclass)
  */
-function resolveRequestStrategy(driver) {
-    switch (driver) {
-        case DriverEnum.NESTJS:
-            return new NestjsRequestStrategy();
-        case DriverEnum.SPATIE:
-            return new SpatieRequestStrategy();
-        case DriverEnum.LARAVEL:
-            return new LaravelRequestStrategy();
+function resolveResponseOptions(driver, responseConfig) {
+    if (driver === DriverEnum.JSON_API) {
+        return new JsonApiResponseOptions(responseConfig);
+    }
+    if (driver === DriverEnum.NESTJS) {
+        return new NestjsResponseOptions(responseConfig);
     }
+    return new ResponseOptions(responseConfig);
 }
 /**
- * Resolve the response strategy instance for the given driver
+ * Build the core provider list shared by `provideNgQubee()` and
+ * `NgQubeeModule.forRoot()`
  *
- * @param driver - The pagination driver
- * @returns The corresponding response strategy
+ * Exposes the driver, strategies, and options via injection tokens so that
+ * consumers can request a component-scoped instance of the services through
+ * `provideNgQubeeInstance()`.
+ *
+ * @param config - Configuration object compliant to the IConfig interface
+ * @returns An array of Providers for the environment injector
  */
-function resolveResponseStrategy(driver) {
-    switch (driver) {
-        case DriverEnum.NESTJS:
-            return new NestjsResponseStrategy();
-        case DriverEnum.SPATIE:
-            return new SpatieResponseStrategy();
-        case DriverEnum.LARAVEL:
-            return new LaravelResponseStrategy();
-    }
+function buildNgQubeeProviders(config) {
+    const driver = config.driver;
+    const requestOptions = new QueryBuilderOptions(Object.assign({}, config.request));
+    const responseOptions = resolveResponseOptions(driver, Object.assign({}, config.response));
+    return [
+        { provide: NG_QUBEE_DRIVER, useValue: driver },
+        { provide: NG_QUBEE_REQUEST_STRATEGY, useValue: resolveRequestStrategy(driver) },
+        { provide: NG_QUBEE_REQUEST_OPTIONS, useValue: requestOptions },
+        { provide: NG_QUBEE_RESPONSE_STRATEGY, useValue: resolveResponseStrategy(driver) },
+        { provide: NG_QUBEE_RESPONSE_OPTIONS, useValue: responseOptions },
+        NestService,
+        NgQubeeService,
+        PaginationService
+    ];
 }
 /**
  * Sets up providers necessary to enable `NgQubee` functionality for the application.
@@ -1797,6 +2394,15 @@ function resolveResponseStrategy(driver) {
  * });
  * ```
  *
+ * JSON:API driver example:
+ * ```
+ * import { DriverEnum } from 'ng-qubee';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideNgQubee({ driver: DriverEnum.JSON_API })]
+ * });
+ * ```
+ *
  * NestJS driver example:
  * ```
  * import { DriverEnum } from 'ng-qubee';
@@ -1811,30 +2417,61 @@ function resolveResponseStrategy(driver) {
  * @returns A set of providers to setup NgQubee
  */
 function provideNgQubee(config) {
-    const driver = config.driver;
-    const requestStrategy = resolveRequestStrategy(driver);
-    const responseStrategy = resolveResponseStrategy(driver);
-    return makeEnvironmentProviders([
-        {
-            provide: NestService,
-            useClass: NestService
-        },
-        {
-            deps: [NestService],
-            provide: NgQubeeService,
-            useFactory: (nestService) => new NgQubeeService(nestService, requestStrategy, driver, Object.assign({}, config.request))
-        },
-        {
-            provide: PaginationService,
-            useFactory: () => {
-                const responseConfig = Object.assign({}, config.response);
-                return driver === DriverEnum.NESTJS
-                    ? new PaginationService(responseStrategy, new NestjsResponseOptions(responseConfig))
-                    : new PaginationService(responseStrategy, responseConfig);
-            }
-        }
-    ]);
+    return makeEnvironmentProviders(buildNgQubeeProviders(config));
+}
+/**
+ * Providers for a component-scoped NgQubee instance
+ *
+ * Use this inside a standalone component's `providers: [...]` to get a
+ * dedicated `NgQubeeService` (and its `NestService` / `PaginationService`
+ * collaborators) whose query-builder and pagination state does not bleed
+ * with the app-wide shared instance provided by `provideNgQubee()`.
+ *
+ * @usageNotes
+ *
+ * ```
+ * @Component({
+ *   standalone: true,
+ *   providers: [...provideNgQubeeInstance()]
+ * })
+ * export class MyFeatureComponent {
+ *   constructor(private _qb: NgQubeeService) {}
+ * }
+ * ```
+ *
+ * The driver, strategies, and options are inherited from the environment
+ * injector (`provideNgQubee()` at root), so only the service instances are
+ * re-created at the component level.
+ *
+ * @publicApi
+ * @returns A provider array to spread into a component's `providers`
+ */
+function provideNgQubeeInstance() {
+    return [NestService, NgQubeeService, PaginationService];
+}
+
+// @dynamic
+class NgQubeeModule {
+    /**
+     * Configure NgQubee for the root module
+     *
+     * @param config - Configuration object with driver, and optional request and response settings
+     * @returns Module with providers configured for the specified driver
+     */
+    static forRoot(config) {
+        return {
+            ngModule: NgQubeeModule,
+            providers: buildNgQubeeProviders(config)
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule });
 }
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NgQubeeModule, decorators: [{
+            type: NgModule,
+            args: [{}]
+        }] });
 
 /**
  * Enum representing the available filter operators for the NestJS driver
@@ -1868,5 +2505,5 @@ var FilterOperatorEnum;
  * Generated bundle index. Do not edit.
  */
 
-export { DriverEnum, FilterOperatorEnum, InvalidLimitError, InvalidPageNumberError, InvalidResourceNameError, KeyNotFoundError, LaravelRequestStrategy, LaravelResponseStrategy, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, provideNgQubee };
+export { DriverEnum, FilterOperatorEnum, InvalidLimitError, InvalidPageNumberError, InvalidResourceNameError, JsonApiRequestStrategy, JsonApiResponseStrategy, KeyNotFoundError, LaravelRequestStrategy, LaravelResponseStrategy, NG_QUBEE_DRIVER, NG_QUBEE_REQUEST_OPTIONS, NG_QUBEE_REQUEST_STRATEGY, NG_QUBEE_RESPONSE_OPTIONS, NG_QUBEE_RESPONSE_STRATEGY, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationNotSyncedError, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, buildNgQubeeProviders, provideNgQubee, provideNgQubeeInstance };
 //# sourceMappingURL=ng-qubee.mjs.map