ng-qubee 3.0.0 → 3.1.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, NgModule, makeEnvironmentProviders } from '@angular/core';
 import { BehaviorSubject, filter, throwError } from 'rxjs';
 import * as qs from 'qs';
 
@@ -74,6 +74,7 @@ class PaginatedCollection {
  */
 var DriverEnum;
 (function (DriverEnum) {
+    DriverEnum["JSON_API"] = "json-api";
     DriverEnum["LARAVEL"] = "laravel";
     DriverEnum["NESTJS"] = "nestjs";
     DriverEnum["SPATIE"] = "spatie";
@@ -121,6 +122,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
  *
@@ -263,203 +289,539 @@ class QueryBuilderOptions {
     }
 }
 
-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
- *
- * Resource name must be a non-empty string.
- */
-class InvalidResourceNameError extends Error {
-    constructor(resource) {
-        super(`Invalid resource name: Resource name must be a non-empty string. Received: ${JSON.stringify(resource)}`);
-        this.name = 'InvalidResourceNameError';
-    }
-}
-
-class InvalidPageNumberError extends Error {
-    constructor(page) {
-        super(`Invalid page number: Page must be a positive integer greater than 0. Received: ${page}`);
-        this.name = 'InvalidPageNumberError';
-    }
-}
-
-const INITIAL_STATE = {
-    baseUrl: '',
-    fields: {},
-    filters: {},
-    includes: [],
-    limit: 15,
-    operatorFilters: [],
-    page: 1,
-    resource: '',
-    search: '',
-    select: [],
-    sorts: []
-};
-class NestService {
+class NgQubeeService {
+    _nestService;
     /**
-     * Private writable signal that holds the Query Builder state
-     *
-     * @type {IQueryBuilderState}
+     * The active pagination driver
      */
-    _nest = signal(this._clone(INITIAL_STATE), ...(ngDevMode ? [{ debugName: "_nest" }] : []));
+    _driver;
     /**
-     * A computed signal that makes readonly the writable signal _nest
-     *
-     * @type {Signal<IQueryBuilderState>}
+     * Resolved query parameter key name options
      */
-    nest = computed(() => this._clone(this._nest()), ...(ngDevMode ? [{ debugName: "nest" }] : []));
-    constructor() {
-        // Nothing to see here
-    }
+    _options;
     /**
-     * Set the base URL for the API
-     *
-     * @param {string} baseUrl - The base URL to prepend to generated URIs
-     * @example
-     * service.baseUrl = 'https://api.example.com';
+     * The request strategy that builds URIs for the active driver
      */
-    set baseUrl(baseUrl) {
-        this._nest.update(nest => ({
-            ...nest,
-            baseUrl
-        }));
+    _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;
     }
     /**
-     * Set the limit for paginated results
-     * Must be a positive integer greater than 0
+     * Assert that the active driver is one of the allowed drivers
      *
-     * @param {number} limit - The number of items per page
-     * @throws {InvalidLimitError} If limit is not a positive integer
-     * @example
-     * service.limit = 25;
+     * @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
      */
-    set limit(limit) {
-        this._validateLimit(limit);
-        this._nest.update(nest => ({
-            ...nest,
-            limit
-        }));
+    _assertDriver(allowed, error) {
+        if (!allowed.includes(this._driver)) {
+            throw error;
+        }
     }
     /**
-     * Set the page number for pagination
-     * Must be a positive integer greater than 0
+     * Add fields to the select statement for the given model (JSON:API and Spatie only)
      *
-     * @param {number} page - The page number to fetch
-     * @throws {InvalidPageNumberError} If page is not a positive integer
-     * @example
-     * service.page = 2;
+     * @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
      */
-    set page(page) {
-        this._validatePageNumber(page);
-        this._nest.update(nest => ({
-            ...nest,
-            page
-        }));
+    addFields(model, fields) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.addFields({ [model]: fields });
+        return this;
     }
     /**
-     * Set the resource name for the query
-     * Must be a non-empty string
+     * Add a filter with the given value(s) (JSON:API, NestJS, and Spatie)
      *
-     * @param {string} resource - The API resource name (e.g., 'users', 'posts')
-     * @throws {InvalidResourceNameError} If resource is not a non-empty string
-     * @example
-     * service.resource = 'users';
+     * 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
      */
-    set resource(resource) {
-        this._validateResourceName(resource);
-        this._nest.update(nest => ({
-            ...nest,
-            resource
-        }));
-    }
-    _clone(obj) {
-        return JSON.parse(JSON.stringify(obj));
+    addFilter(field, ...values) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
+        if (!values.length) {
+            return this;
+        }
+        this._nestService.addFilters({
+            [field]: values
+        });
+        return this;
     }
     /**
-     * Validates that the limit is a positive integer
+     * Add a filter with an explicit operator (NestJS only)
      *
-     * @param {number} limit - The limit value to validate
-     * @throws {InvalidLimitError} If limit is not a positive integer
-     * @private
+     * Produces: `filter.field=$operator:value`
+     *
+     * @param {string} field - Name of the field to filter
+     * @param {FilterOperatorEnum} operator - The filter operator to apply
+     * @param {(string | number | boolean)[]} values - The value(s) for the filter
+     * @returns {this}
+     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
      */
-    _validateLimit(limit) {
-        if (!Number.isInteger(limit) || limit < 1) {
-            throw new InvalidLimitError(limit);
+    addFilterOperator(field, operator, ...values) {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
+        if (!values.length) {
+            return this;
         }
+        this._nestService.addOperatorFilters([{ field, operator, values }]);
+        return this;
     }
     /**
-     * Validates that the page number is a positive integer
+     * Add related entities to include in the request (JSON:API and Spatie only)
      *
-     * @param {number} page - The page number to validate
-     * @throws {InvalidPageNumberError} If page is not a positive integer
-     * @private
+     * @param {string[]} models - Models to include
+     * @returns {this}
+     * @throws {UnsupportedIncludesError} If the active driver does not support includes
      */
-    _validatePageNumber(page) {
-        if (!Number.isInteger(page) || page < 1) {
-            throw new InvalidPageNumberError(page);
+    addIncludes(...models) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
+        if (!models.length) {
+            return this;
         }
+        this._nestService.addIncludes(models);
+        return this;
     }
     /**
-     * Validates that the resource name is a non-empty string
+     * Add flat field selection (NestJS only)
      *
-     * @param {string} resource - The resource name to validate
-     * @throws {InvalidResourceNameError} If resource is not a non-empty string
-     * @private
+     * Produces: `select=col1,col2`
+     *
+     * @param {string[]} fields - Fields to select
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
      */
-    _validateResourceName(resource) {
-        if (!resource || typeof resource !== 'string' || resource.trim().length === 0) {
-            throw new InvalidResourceNameError(resource);
+    addSelect(...fields) {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
+        if (!fields.length) {
+            return this;
         }
+        this._nestService.addSelect(fields);
+        return this;
     }
     /**
-     * Add selectable fields for the given model to the request
-     * Automatically prevents duplicate fields for each model
+     * Add a field with a sort criteria (JSON:API, NestJS, and Spatie)
      *
-     * @param {IFields} fields - Object mapping model names to arrays of field names
-     * @return {void}
-     * @example
-     * service.addFields({ users: ['id', 'email', 'username'] });
-     * service.addFields({ posts: ['title', 'content'] });
+     * @param field - Field to use for sorting
+     * @param {SortEnum} order - A value from the SortEnum enumeration
+     * @returns {this}
+     * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
-    addFields(fields) {
-        this._nest.update(nest => {
-            const mergedFields = { ...nest.fields };
-            Object.keys(fields).forEach(model => {
-                const existingFields = mergedFields[model] || [];
-                const newFields = fields[model];
-                // Use Set to prevent duplicates
-                const uniqueFields = Array.from(new Set([...existingFields, ...newFields]));
-                mergedFields[model] = uniqueFields;
-            });
-            return {
-                ...nest,
-                fields: mergedFields
-            };
+    addSort(field, order) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedSortError());
+        this._nestService.addSort({
+            field,
+            order
         });
+        return this;
     }
     /**
-     * Add filters to the request
-     * Automatically prevents duplicate filter values for each filter key
+     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
-     * @param {IFilters} filters - Object mapping filter keys to arrays of values
-     * @return {void}
-     * @example
-     * service.addFilters({ id: [1, 2, 3] });
-     * service.addFilters({ status: ['active', 'pending'] });
-     */
-    addFilters(filters) {
-        this._nest.update(nest => {
-            const mergedFilters = { ...nest.filters };
-            Object.keys(filters).forEach(key => {
-                const existingValues = mergedFilters[key] || [];
-                const newValues = filters[key];
+     * ```
+     * ngQubeeService.deleteFields({
+     *   users: ['email', 'password'],
+     *   address: ['zipcode']
+     * });
+     * ```
+     *
+     * @param {IFields} fields - Object mapping model names to field arrays to remove
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    deleteFields(fields) {
+        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 (JSON:API and Spatie only)
+     *
+     * ```
+     * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
+     * ```
+     *
+     * @param model - Model that holds the fields
+     * @param {string[]} fields - Fields to delete from the state
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    deleteFieldsByModel(model, ...fields) {
+        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.deleteFields({
+            [model]: fields
+        });
+        return this;
+    }
+    /**
+     * 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.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
+        if (!filters.length) {
+            return this;
+        }
+        this._nestService.deleteFilters(...filters);
+        return this;
+    }
+    /**
+     * 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.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
+        if (!includes.length) {
+            return this;
+        }
+        this._nestService.deleteIncludes(...includes);
+        return this;
+    }
+    /**
+     * Remove operator filters by field name (NestJS only)
+     *
+     * @param {string[]} fields - Field names of operator filters to remove
+     * @returns {this}
+     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
+     */
+    deleteOperatorFilters(...fields) {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.deleteOperatorFilters(...fields);
+        return this;
+    }
+    /**
+     * Remove search term from the query builder state (NestJS only)
+     *
+     * @returns {this}
+     * @throws {UnsupportedSearchError} If the active driver does not support search
+     */
+    deleteSearch() {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
+        this._nestService.deleteSearch();
+        return this;
+    }
+    /**
+     * Remove flat field selections from the query builder state (NestJS only)
+     *
+     * @param {string[]} fields - Fields to remove from selection
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     */
+    deleteSelect(...fields) {
+        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.deleteSelect(...fields);
+        return this;
+    }
+    /**
+     * 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.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedSortError());
+        this._nestService.deleteSorts(...sorts);
+        return this;
+    }
+    /**
+     * Generate a URI accordingly to the given data and active driver
+     *
+     * @returns {Observable<string>} An observable that emits the generated URI
+     */
+    generateUri() {
+        try {
+            this._uri$.next(this._requestStrategy.buildUri(this._nestService.nest(), this._options));
+            return this.uri$;
+        }
+        catch (error) {
+            return throwError(() => error);
+        }
+    }
+    /**
+     * Clear the current state and reset the Query Builder to a fresh, clean condition
+     *
+     * @returns {this}
+     */
+    reset() {
+        this._nestService.reset();
+        return this;
+    }
+    /**
+     * Set the base URL to use for composing the address
+     *
+     * @param {string} baseUrl - The base URL
+     * @returns {this}
+     */
+    setBaseUrl(baseUrl) {
+        this._nestService.baseUrl = baseUrl;
+        return this;
+    }
+    /**
+     * 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;
+        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;
+        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);
+        return this;
+    }
+}
+
+/**
+ * Error thrown when an invalid resource name is provided
+ *
+ * Resource name must be a non-empty string.
+ */
+class InvalidResourceNameError extends Error {
+    constructor(resource) {
+        super(`Invalid resource name: Resource name must be a non-empty string. Received: ${JSON.stringify(resource)}`);
+        this.name = 'InvalidResourceNameError';
+    }
+}
+
+class InvalidPageNumberError extends Error {
+    constructor(page) {
+        super(`Invalid page number: Page must be a positive integer greater than 0. Received: ${page}`);
+        this.name = 'InvalidPageNumberError';
+    }
+}
+
+const INITIAL_STATE = {
+    baseUrl: '',
+    fields: {},
+    filters: {},
+    includes: [],
+    limit: 15,
+    operatorFilters: [],
+    page: 1,
+    resource: '',
+    search: '',
+    select: [],
+    sorts: []
+};
+class NestService {
+    /**
+     * Private writable signal that holds the Query Builder state
+     *
+     * @type {IQueryBuilderState}
+     */
+    _nest = signal(this._clone(INITIAL_STATE), ...(ngDevMode ? [{ debugName: "_nest" }] : []));
+    /**
+     * A computed signal that makes readonly the writable signal _nest
+     *
+     * @type {Signal<IQueryBuilderState>}
+     */
+    nest = computed(() => this._clone(this._nest()), ...(ngDevMode ? [{ debugName: "nest" }] : []));
+    constructor() {
+        // Nothing to see here
+    }
+    /**
+     * Set the base URL for the API
+     *
+     * @param {string} baseUrl - The base URL to prepend to generated URIs
+     * @example
+     * service.baseUrl = 'https://api.example.com';
+     */
+    set baseUrl(baseUrl) {
+        this._nest.update(nest => ({
+            ...nest,
+            baseUrl
+        }));
+    }
+    /**
+     * Set the limit for paginated results
+     *
+     * 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
+     * @example
+     * service.limit = 25;
+     */
+    set limit(limit) {
+        this._nest.update(nest => ({
+            ...nest,
+            limit
+        }));
+    }
+    /**
+     * Set the page number for pagination
+     * Must be a positive integer greater than 0
+     *
+     * @param {number} page - The page number to fetch
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @example
+     * service.page = 2;
+     */
+    set page(page) {
+        this._validatePageNumber(page);
+        this._nest.update(nest => ({
+            ...nest,
+            page
+        }));
+    }
+    /**
+     * Set the resource name for the query
+     * Must be a non-empty string
+     *
+     * @param {string} resource - The API resource name (e.g., 'users', 'posts')
+     * @throws {InvalidResourceNameError} If resource is not a non-empty string
+     * @example
+     * service.resource = 'users';
+     */
+    set resource(resource) {
+        this._validateResourceName(resource);
+        this._nest.update(nest => ({
+            ...nest,
+            resource
+        }));
+    }
+    _clone(obj) {
+        return JSON.parse(JSON.stringify(obj));
+    }
+    /**
+     * Validates that the page number is a positive integer
+     *
+     * @param {number} page - The page number to validate
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @private
+     */
+    _validatePageNumber(page) {
+        if (!Number.isInteger(page) || page < 1) {
+            throw new InvalidPageNumberError(page);
+        }
+    }
+    /**
+     * Validates that the resource name is a non-empty string
+     *
+     * @param {string} resource - The resource name to validate
+     * @throws {InvalidResourceNameError} If resource is not a non-empty string
+     * @private
+     */
+    _validateResourceName(resource) {
+        if (!resource || typeof resource !== 'string' || resource.trim().length === 0) {
+            throw new InvalidResourceNameError(resource);
+        }
+    }
+    /**
+     * Add selectable fields for the given model to the request
+     * Automatically prevents duplicate fields for each model
+     *
+     * @param {IFields} fields - Object mapping model names to arrays of field names
+     * @return {void}
+     * @example
+     * service.addFields({ users: ['id', 'email', 'username'] });
+     * service.addFields({ posts: ['title', 'content'] });
+     */
+    addFields(fields) {
+        this._nest.update(nest => {
+            const mergedFields = { ...nest.fields };
+            Object.keys(fields).forEach(model => {
+                const existingFields = mergedFields[model] || [];
+                const newFields = fields[model];
+                // Use Set to prevent duplicates
+                const uniqueFields = Array.from(new Set([...existingFields, ...newFields]));
+                mergedFields[model] = uniqueFields;
+            });
+            return {
+                ...nest,
+                fields: mergedFields
+            };
+        });
+    }
+    /**
+     * Add filters to the request
+     * Automatically prevents duplicate filter values for each filter key
+     *
+     * @param {IFilters} filters - Object mapping filter keys to arrays of values
+     * @return {void}
+     * @example
+     * service.addFilters({ id: [1, 2, 3] });
+     * service.addFilters({ status: ['active', 'pending'] });
+     */
+    addFilters(filters) {
+        this._nest.update(nest => {
+            const mergedFilters = { ...nest.filters };
+            Object.keys(filters).forEach(key => {
+                const existingValues = mergedFilters[key] || [];
+                const newValues = filters[key];
                 // Use Set to prevent duplicates
                 const uniqueValues = Array.from(new Set([...existingValues, ...newValues]));
                 mergedFilters[key] = uniqueValues;
@@ -635,483 +997,444 @@ class NestService {
      * @return {void}
      * @example
      * service.deleteSearch();
-     */
-    deleteSearch() {
-        this._nest.update(nest => ({
-            ...nest,
-            search: ''
-        }));
-    }
-    /**
-     * Remove flat field selections from the state (NestJS only)
-     *
-     * @param {...string[]} fields - Field names to remove from selection
-     * @return {void}
-     * @example
-     * service.deleteSelect('email');
-     * service.deleteSelect('name', 'email');
-     */
-    deleteSelect(...fields) {
-        this._nest.update(nest => ({
-            ...nest,
-            select: nest.select.filter(f => !fields.includes(f))
-        }));
-    }
-    /**
-     * Remove sorts from the request by field name
-     *
-     * @param {...string[]} sorts - Field names of sorts to remove
-     * @return {void}
-     * @example
-     * service.deleteSorts('created_at');
-     * service.deleteSorts('name', 'created_at');
-     */
-    deleteSorts(...sorts) {
-        const s = [...this._nest().sorts];
-        sorts.forEach(field => {
-            const p = s.findIndex(sort => sort.field === field);
-            if (p > -1) {
-                s.splice(p, 1);
-            }
-        });
-        this._nest.update(nest => ({
-            ...nest,
-            sorts: s
-        }));
-    }
-    /**
-     * Set the full-text search term (NestJS only)
-     *
-     * @param {string} search - The search term
-     * @return {void}
-     * @example
-     * service.setSearch('john doe');
-     */
-    setSearch(search) {
-        this._nest.update(nest => ({
-            ...nest,
-            search
-        }));
-    }
-    /**
-     * Reset the query builder state to initial values
-     * Clears all fields, filters, includes, sorts, and resets pagination
-     *
-     * @return {void}
-     * @example
-     * service.reset();
-     */
-    reset() {
-        this._nest.update(_ => this._clone(INITIAL_STATE));
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService, decorators: [{
-            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;
-    }
-    /**
-     * 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 (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;
-    }
-    /**
-     * 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}
-     * @throws {UnsupportedFilterError} If the active driver does not support filters
-     */
-    addFilter(field, ...values) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedFilterError());
-        if (!values.length) {
-            return this;
-        }
-        this._nestService.addFilters({
-            [field]: values
-        });
-        return this;
-    }
-    /**
-     * Add a filter with an explicit operator (NestJS only)
-     *
-     * Produces: `filter.field=$operator:value`
-     *
-     * @param {string} field - Name of the field to filter
-     * @param {FilterOperatorEnum} operator - The filter operator to apply
-     * @param {(string | number | boolean)[]} values - The value(s) for the filter
-     * @returns {this}
-     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
-     */
-    addFilterOperator(field, operator, ...values) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
-        if (!values.length) {
-            return this;
-        }
-        this._nestService.addOperatorFilters([{ field, operator, values }]);
-        return this;
-    }
-    /**
-     * Add related entities to include in the request (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());
-        if (!models.length) {
-            return this;
-        }
-        this._nestService.addIncludes(models);
-        return this;
+     */
+    deleteSearch() {
+        this._nest.update(nest => ({
+            ...nest,
+            search: ''
+        }));
     }
     /**
-     * Add flat field selection (NestJS only)
-     *
-     * Produces: `select=col1,col2`
+     * Remove flat field selections from the state (NestJS only)
      *
-     * @param {string[]} fields - Fields to select
-     * @returns {this}
-     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     * @param {...string[]} fields - Field names to remove from selection
+     * @return {void}
+     * @example
+     * service.deleteSelect('email');
+     * service.deleteSelect('name', 'email');
      */
-    addSelect(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
-        if (!fields.length) {
-            return this;
-        }
-        this._nestService.addSelect(fields);
-        return this;
+    deleteSelect(...fields) {
+        this._nest.update(nest => ({
+            ...nest,
+            select: nest.select.filter(f => !fields.includes(f))
+        }));
     }
     /**
-     * Add a field with a sort criteria (Spatie and NestJS only)
+     * Remove sorts from the request by field name
      *
-     * @param field - Field to use for sorting
-     * @param {SortEnum} order - A value from the SortEnum enumeration
-     * @returns {this}
-     * @throws {UnsupportedSortError} If the active driver does not support sorts
+     * @param {...string[]} sorts - Field names of sorts to remove
+     * @return {void}
+     * @example
+     * service.deleteSorts('created_at');
+     * service.deleteSorts('name', 'created_at');
      */
-    addSort(field, order) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedSortError());
-        this._nestService.addSort({
-            field,
-            order
+    deleteSorts(...sorts) {
+        const s = [...this._nest().sorts];
+        sorts.forEach(field => {
+            const p = s.findIndex(sort => sort.field === field);
+            if (p > -1) {
+                s.splice(p, 1);
+            }
         });
-        return this;
+        this._nest.update(nest => ({
+            ...nest,
+            sorts: s
+        }));
     }
     /**
-     * Delete selected fields for the given models in the current query builder state (Spatie only)
-     *
-     * ```
-     * ngQubeeService.deleteFields({
-     *   users: ['email', 'password'],
-     *   address: ['zipcode']
-     * });
-     * ```
+     * Set the full-text search term (NestJS only)
      *
-     * @param {IFields} fields - Object mapping model names to field arrays to remove
-     * @returns {this}
-     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     * @param {string} search - The search term
+     * @return {void}
+     * @example
+     * service.setSearch('john doe');
      */
-    deleteFields(fields) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        this._nestService.deleteFields(fields);
-        return this;
+    setSearch(search) {
+        this._nest.update(nest => ({
+            ...nest,
+            search
+        }));
     }
     /**
-     * Delete selected fields for the given model in the current query builder state (Spatie only)
-     *
-     * ```
-     * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
-     * ```
+     * Reset the query builder state to initial values
+     * Clears all fields, filters, includes, sorts, and resets pagination
      *
-     * @param model - Model that holds the fields
-     * @param {string[]} fields - Fields to delete from the state
-     * @returns {this}
-     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     * @return {void}
+     * @example
+     * service.reset();
      */
-    deleteFieldsByModel(model, ...fields) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        if (!fields.length) {
-            return this;
-        }
-        this._nestService.deleteFields({
-            [model]: fields
-        });
-        return this;
+    reset() {
+        this._nest.update(_ => this._clone(INITIAL_STATE));
     }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: NestService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+class PaginationService {
     /**
-     * Remove given filters from the query builder state (Spatie and NestJS only)
-     *
-     * @param {string[]} filters - Filters to remove
-     * @returns {this}
-     * @throws {UnsupportedFilterError} If the active driver does not support filters
+     * Resolved response key name options
      */
-    deleteFilters(...filters) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedFilterError());
-        if (!filters.length) {
-            return this;
-        }
-        this._nestService.deleteFilters(...filters);
-        return this;
-    }
+    _options;
     /**
-     * Remove selected related models from the query builder state (Spatie only)
-     *
-     * @param {string[]} includes - Models to remove
-     * @returns {this}
-     * @throws {UnsupportedIncludesError} If the active driver does not support includes
+     * The response strategy that parses responses for the active driver
      */
-    deleteIncludes(...includes) {
-        this._assertDriver([DriverEnum.SPATIE], new UnsupportedIncludesError());
-        if (!includes.length) {
-            return this;
-        }
-        this._nestService.deleteIncludes(...includes);
-        return this;
+    _responseStrategy;
+    constructor(responseStrategy, options = {}) {
+        this._options = new ResponseOptions(options);
+        this._responseStrategy = responseStrategy;
     }
     /**
-     * Remove operator filters by field name (NestJS only)
+     * Transform a raw API response into a typed PaginatedCollection
      *
-     * @param {string[]} fields - Field names of operator filters to remove
-     * @returns {this}
-     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
+     * Delegates to the active driver's response strategy for parsing.
+     *
+     * @param response - The raw API response object
+     * @returns A typed PaginatedCollection instance
      */
-    deleteOperatorFilters(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
-        if (!fields.length) {
-            return this;
-        }
-        this._nestService.deleteOperatorFilters(...fields);
-        return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response) {
+        return this._responseStrategy.paginate(response, this._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 {
     /**
-     * Remove search term from the query builder state (NestJS only)
-     *
-     * @returns {this}
-     * @throws {UnsupportedSearchError} If the active driver does not support search
+     * @param limit - The rejected limit value
+     * @param allowFetchAll - Whether the active driver accepts `-1` (fetch all)
      */
-    deleteSearch() {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
-        this._nestService.deleteSearch();
-        return this;
+    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 {
     /**
-     * Remove flat field selections from the query builder state (NestJS only)
+     * Accumulator for composing the URI string
+     */
+    _uri = '';
+    /**
+     * Build a URI string from the given state using the JSON:API format
      *
-     * @param {string[]} fields - Fields to remove from selection
-     * @returns {this}
-     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     * @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
      */
-    deleteSelect(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
-        if (!fields.length) {
-            return this;
+    buildUri(state, options) {
+        if (!state.resource) {
+            throw new Error('Set the resource property BEFORE adding filters or calling the url() / get() methods');
         }
-        this._nestService.deleteSelect(...fields);
-        return this;
+        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;
     }
     /**
-     * Remove sort rules from the query builder state (Spatie and NestJS only)
+     * Validate that the given limit is accepted by the JSON:API driver
      *
-     * @param sorts - Fields used for sorting to remove
-     * @returns {this}
-     * @throws {UnsupportedSortError} If the active driver does not support sorts
+     * 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
      */
-    deleteSorts(...sorts) {
-        this._assertDriver([DriverEnum.SPATIE, DriverEnum.NESTJS], new UnsupportedSortError());
-        this._nestService.deleteSorts(...sorts);
-        return this;
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && limit >= 1) {
+            return;
+        }
+        throw new InvalidLimitError(limit);
     }
     /**
-     * Generate a URI accordingly to the given data and active driver
+     * Parse and append field selection parameters
      *
-     * @returns {Observable<string>} An observable that emits the generated URI
+     * 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
      */
-    generateUri() {
-        try {
-            this._uri$.next(this._requestStrategy.buildUri(this._nestService.nest(), this._options));
-            return this.uri$;
+    _parseFields(state, options) {
+        if (!Object.keys(state.fields).length) {
+            return this._uri;
         }
-        catch (error) {
-            return throwError(() => error);
+        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;
     }
     /**
-     * Clear the current state and reset the Query Builder to a fresh, clean condition
+     * Parse and append filter parameters
      *
-     * @returns {this}
+     * 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
      */
-    reset() {
-        this._nestService.reset();
-        return this;
+    _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;
     }
     /**
-     * Set the base URL to use for composing the address
+     * Parse and append include parameters
      *
-     * @param {string} baseUrl - The base URL
-     * @returns {this}
+     * 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
      */
-    setBaseUrl(baseUrl) {
-        this._nestService.baseUrl = baseUrl;
-        return this;
+    _parseIncludes(state, options) {
+        if (!state.includes.length) {
+            return this._uri;
+        }
+        const param = `${this._prepend(state)}${options.includes}=${state.includes}`;
+        this._uri += param;
+        return param;
     }
     /**
-     * Set the items per page number
+     * Parse and append pagination parameters in JSON:API bracket notation
      *
-     * @param limit - Number of items per page
-     * @returns {this}
+     * 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
      */
-    setLimit(limit) {
-        this._nestService.limit = limit;
-        return this;
+    _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;
     }
     /**
-     * Set the page that the backend will use to paginate the result set
+     * Parse and append sort parameters
      *
-     * @param page - Page number
-     * @returns {this}
+     * 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
      */
-    setPage(page) {
-        this._nestService.page = page;
-        return this;
+    _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;
     }
     /**
-     * Set the API resource to run the query against
+     * Determine the appropriate URI prefix based on the current accumulator state
      *
-     * @param {string} resource - Resource name (e.g. 'users' produces /users)
-     * @returns {this}
+     * 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
      */
-    setResource(resource) {
-        this._nestService.resource = resource;
-        return this;
+    _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 {
     /**
-     * Set the search term for full-text search (NestJS only)
+     * Parse a JSON:API pagination response into a PaginatedCollection
      *
-     * Produces: `search=term`
+     * 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 {string} search - The search term
-     * @returns {this}
-     * @throws {UnsupportedSearchError} If the active driver does not support search
+     * @param response - The raw API response object
+     * @param options - The response key name configuration
+     * @returns A typed PaginatedCollection instance
      */
-    setSearch(search) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
-        this._nestService.setSearch(search);
-        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);
     }
-    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
+     * Resolve a value from a response object using a dot-notation path
+     *
+     * 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
      */
-    _options;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _resolve(response, path) {
+        return path.split('.').reduce((obj, key) => obj?.[key], response);
+    }
     /**
-     * The response strategy that parses responses for the active driver
+     * Resolve the "from" index value
+     *
+     * If the path resolves to a value in the response, use it.
+     * Otherwise, compute it from currentPage and perPage:
+     * `(currentPage - 1) * perPage + 1`
+     *
+     * @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 +1460,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 +1507,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 +1547,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 +1801,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 +1839,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
      *
@@ -1678,6 +2034,8 @@ class SpatieResponseStrategy {
  */
 function resolveRequestStrategy$1(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiRequestStrategy();
         case DriverEnum.NESTJS:
             return new NestjsRequestStrategy();
         case DriverEnum.SPATIE:
@@ -1694,6 +2052,8 @@ function resolveRequestStrategy$1(driver) {
  */
 function resolveResponseStrategy$1(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiResponseStrategy();
         case DriverEnum.NESTJS:
             return new NestjsResponseStrategy();
         case DriverEnum.SPATIE:
@@ -1727,6 +2087,9 @@ class NgQubeeModule {
                     provide: PaginationService,
                     useFactory: () => {
                         const responseConfig = Object.assign({}, config.response);
+                        if (driver === DriverEnum.JSON_API) {
+                            return new PaginationService(responseStrategy, new JsonApiResponseOptions(responseConfig));
+                        }
                         return driver === DriverEnum.NESTJS
                             ? new PaginationService(responseStrategy, new NestjsResponseOptions(responseConfig))
                             : new PaginationService(responseStrategy, responseConfig);
@@ -1752,6 +2115,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
  */
 function resolveRequestStrategy(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiRequestStrategy();
         case DriverEnum.NESTJS:
             return new NestjsRequestStrategy();
         case DriverEnum.SPATIE:
@@ -1768,6 +2133,8 @@ function resolveRequestStrategy(driver) {
  */
 function resolveResponseStrategy(driver) {
     switch (driver) {
+        case DriverEnum.JSON_API:
+            return new JsonApiResponseStrategy();
         case DriverEnum.NESTJS:
             return new NestjsResponseStrategy();
         case DriverEnum.SPATIE:
@@ -1797,6 +2164,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';
@@ -1828,6 +2204,9 @@ function provideNgQubee(config) {
             provide: PaginationService,
             useFactory: () => {
                 const responseConfig = Object.assign({}, config.response);
+                if (driver === DriverEnum.JSON_API) {
+                    return new PaginationService(responseStrategy, new JsonApiResponseOptions(responseConfig));
+                }
                 return driver === DriverEnum.NESTJS
                     ? new PaginationService(responseStrategy, new NestjsResponseOptions(responseConfig))
                     : new PaginationService(responseStrategy, responseConfig);
@@ -1868,5 +2247,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, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, provideNgQubee };
 //# sourceMappingURL=ng-qubee.mjs.map