ng-qubee 3.1.0 → 3.3.0

package/fesm2022/ng-qubee.mjs

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
-import { signal, computed, Injectable, NgModule, makeEnvironmentProviders } from '@angular/core';
-import { BehaviorSubject, filter, throwError } from 'rxjs';
+import { signal, computed, Injectable, InjectionToken, Inject, makeEnvironmentProviders, NgModule } from '@angular/core';
 import * as qs from 'qs';
+import { BehaviorSubject, filter, throwError } from 'rxjs';
 
 class KeyNotFoundError extends Error {
     constructor(key) {
@@ -77,6 +77,7 @@ var DriverEnum;
     DriverEnum["JSON_API"] = "json-api";
     DriverEnum["LARAVEL"] = "laravel";
     DriverEnum["NESTJS"] = "nestjs";
+    DriverEnum["POSTGREST"] = "postgrest";
     DriverEnum["SPATIE"] = "spatie";
 })(DriverEnum || (DriverEnum = {}));
 
@@ -171,1977 +172,2573 @@ 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';
-    }
-}
+var SortEnum;
+(function (SortEnum) {
+    SortEnum["ASC"] = "asc";
+    SortEnum["DESC"] = "desc";
+})(SortEnum || (SortEnum = {}));
 
-/**
- * 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';
+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.`);
     }
 }
 
 /**
- * Error thrown when search is attempted with a driver that does not support it
+ * Thrown when a limit value does not satisfy the active driver's constraints
  *
- * Search is only supported by the NestJS driver.
+ * 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 UnsupportedSearchError extends Error {
-    constructor() {
-        super('Search is only supported by the NestJS driver.');
-        this.name = 'UnsupportedSearchError';
+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';
     }
 }
 
 /**
- * Error thrown when flat field selection is attempted with a driver that does not support it
+ * Base class for request strategies
  *
- * 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
+ * Concentrates the glue every concrete strategy used to copy: the
+ * resource-required guard, the `?`/`&` URL composition, and the default
+ * positive-integer `validateLimit`. Concrete strategies override only
+ * the parts that differ — the per-driver wire format goes into a single
+ * `protected parts(state, options): string[]` method that returns the
+ * ordered query-string segments the base then joins.
  *
- * Sorts are only supported by the Spatie and NestJS drivers.
+ * Drivers that need a non-default `validateLimit` (e.g. NestJS, which
+ * accepts `-1` as a fetch-all sentinel) override that method directly.
  */
-class UnsupportedSortError extends Error {
-    constructor() {
-        super('Sorts are only supported by the Spatie and NestJS drivers.');
-        this.name = 'UnsupportedSortError';
+class AbstractRequestStrategy {
+    /**
+     * Compose the full request URI from the given state
+     *
+     * Template method: validates the resource, computes the base path,
+     * delegates the per-driver query-string segments to `parts(...)`, and
+     * joins them with the conventional `?`/`&` separators.
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The composed URI string
+     * @throws Error if the resource is not set
+     */
+    buildUri(state, options) {
+        this.assertResource(state);
+        const segments = this.parts(state, options);
+        return this.join(this.baseUri(state), segments);
     }
-}
-
-/**
- * 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';
+    /**
+     * Validate that a limit value is acceptable for this driver
+     *
+     * Default policy: positive integer. Drivers that recognise a sentinel
+     * (NestJS treats `-1` as "fetch all") override this method.
+     *
+     * @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);
     }
-}
-
-class NgQubeeService {
-    _nestService;
     /**
-     * The active pagination driver
+     * Throw if the resource is not set on the state
+     *
+     * Centralises the message that was previously copy-pasted across four
+     * of the five concrete strategies.
+     *
+     * @param state - The current query builder state
+     * @throws Error if `state.resource` is empty
      */
-    _driver;
+    assertResource(state) {
+        if (!state.resource) {
+            throw new Error('Set the resource property BEFORE adding filters or calling the url() / get() methods');
+        }
+    }
     /**
-     * Resolved query parameter key name options
+     * Compute the base path (no query string)
+     *
+     * @param state - The current query builder state
+     * @returns The base URI without the query separator (e.g. `/users` or `https://api.example.com/users`)
      */
-    _options;
+    baseUri(state) {
+        return state.baseUrl ? `${state.baseUrl}/${state.resource}` : `/${state.resource}`;
+    }
     /**
-     * The request strategy that builds URIs for the active driver
+     * Glue the base URI and the per-driver query-string segments
+     *
+     * Returns the bare base when no segments were emitted (e.g. PostgREST
+     * in RANGE mode with no filters), otherwise joins with `?` + `&`.
+     *
+     * @param base - The base URI from `_baseUri`
+     * @param segments - The query-string fragments from `parts(...)`
+     * @returns The full URI
      */
-    _requestStrategy;
+    join(base, segments) {
+        return segments.length ? `${base}?${segments.join('&')}` : base;
+    }
+}
+
+/**
+ * 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 extends AbstractRequestStrategy {
     /**
-     * Internal BehaviorSubject that holds the latest generated URI
+     * Filters, sorts, includes, per-model fields — same shape as Spatie
+     * but with bracket-style pagination
      */
-    _uri$ = new BehaviorSubject('');
+    capabilities = {
+        fields: true,
+        filters: true,
+        includes: true,
+        operatorFilters: false,
+        search: false,
+        select: false,
+        sort: true
+    };
     /**
-     * Observable that emits non-empty generated URIs
+     * Emit JSON:API-format query-string segments in canonical order:
+     * include → fields → filters → pagination → sort
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
      */
-    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;
+    parts(state, options) {
+        const out = [];
+        this._appendIncludes(state, options, out);
+        this._appendFields(state, options, out);
+        this._appendFilters(state, options, out);
+        this._appendPagination(state, options, out);
+        this._appendSort(state, options, out);
+        return out;
     }
     /**
-     * Assert that the active driver is one of the allowed drivers
+     * Append per-type field selection in bracket notation
      *
-     * @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 state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
+     * @throws Error if the resource is missing from the fields object
+     * @throws UnselectableModelError if a field type is not the resource or in includes
      */
-    _assertDriver(allowed, error) {
-        if (!allowed.includes(this._driver)) {
-            throw error;
+    _appendFields(state, options, out) {
+        if (!Object.keys(state.fields).length) {
+            return;
+        }
+        if (!(state.resource in state.fields)) {
+            throw new Error(`Key ${state.resource} is missing in the fields object`);
         }
+        const grouped = {};
+        for (const type in state.fields) {
+            if (!state.fields.hasOwnProperty(type)) {
+                continue;
+            }
+            if (type !== state.resource && !state.includes.includes(type)) {
+                throw new UnselectableModelError(type);
+            }
+            grouped[`${options.fields}[${type}]`] = state.fields[type].join(',');
+        }
+        out.push(qs.stringify(grouped, { encode: false }));
     }
     /**
-     * Add fields to the select statement for the given model (JSON:API and Spatie only)
+     * Append filter parameters in bracket notation: `filter[key]=value`
      *
-     * @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
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addFields(model, fields) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        if (!fields.length) {
-            return this;
+    _appendFilters(state, options, out) {
+        const keys = Object.keys(state.filters);
+        if (!keys.length) {
+            return;
         }
-        this._nestService.addFields({ [model]: fields });
-        return this;
+        const wrapper = {
+            [options.filters]: keys.reduce((acc, key) => {
+                return Object.assign(acc, { [key]: state.filters[key].join(',') });
+            }, {})
+        };
+        out.push(qs.stringify(wrapper, { encode: false }));
     }
     /**
-     * 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)
+     * Append include parameter as `include=author,comments.author`
      *
-     * @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
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addFilter(field, ...values) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
-        if (!values.length) {
-            return this;
+    _appendIncludes(state, options, out) {
+        if (!state.includes.length) {
+            return;
         }
-        this._nestService.addFilters({
-            [field]: values
-        });
-        return this;
+        out.push(`${options.includes}=${state.includes}`);
     }
     /**
-     * Add a filter with an explicit operator (NestJS only)
+     * Append JSON:API bracket pagination as `page[number]=1&page[size]=15`
      *
-     * Produces: `filter.field=$operator:value`
+     * `qs.stringify` already returns the two segments joined with `&`, so we
+     * push the whole string as one accumulator entry — `_join` will glue
+     * it onto the rest with the same separator.
      *
-     * @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
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addFilterOperator(field, operator, ...values) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
-        if (!values.length) {
-            return this;
-        }
-        this._nestService.addOperatorFilters([{ field, operator, values }]);
-        return this;
+    _appendPagination(state, options, out) {
+        const pagination = qs.stringify({ [options.page]: { number: state.page, size: state.limit } }, { encode: false });
+        out.push(pagination);
     }
     /**
-     * Add related entities to include in the request (JSON:API and Spatie only)
+     * Append sort parameter as `sort=-field1,field2` (`-` prefix = DESC)
      *
-     * @param {string[]} models - Models to include
-     * @returns {this}
-     * @throws {UnsupportedIncludesError} If the active driver does not support includes
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addIncludes(...models) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
-        if (!models.length) {
-            return this;
+    _appendSort(state, options, out) {
+        if (!state.sorts.length) {
+            return;
         }
-        this._nestService.addIncludes(models);
-        return this;
+        const pairs = state.sorts.map(sort => `${sort.order === SortEnum.DESC ? '-' : ''}${sort.field}`);
+        out.push(`${options.sort}=${pairs.join(',')}`);
     }
+}
+
+/**
+ * Base class for response strategies whose pagination metadata lives at
+ * dot-notation paths inside the response body
+ *
+ * JSON:API and NestJS share an identical body-traversal algorithm: the
+ * total / current-page / etc. live at nested keys like `meta.total`, and
+ * `from`/`to` are either present directly or must be derived from
+ * `currentPage` × `perPage`. Both strategies were duplicating this
+ * verbatim before this base existed; concrete classes now extend and
+ * provide only the docstring describing their driver's specific path
+ * conventions (see `JsonApiResponseStrategy`, `NestjsResponseStrategy`).
+ *
+ * Drivers whose pagination metadata travels via HTTP headers (PostgREST)
+ * or whose body has a flat shape with no dot paths (Laravel, Spatie) do
+ * not extend this class — they implement `IResponseStrategy` directly.
+ */
+class AbstractDotPathResponseStrategy {
     /**
-     * Add flat field selection (NestJS only)
+     * Parse a nested-envelope pagination response into a PaginatedCollection
      *
-     * Produces: `select=col1,col2`
-     *
-     * @param {string[]} fields - Fields to select
-     * @returns {this}
-     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     * @param response - The raw API response object
+     * @param options - The response key name configuration (dot-notation paths supported)
+     * @returns A typed PaginatedCollection instance
      */
-    addSelect(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
-        if (!fields.length) {
-            return this;
-        }
-        this._nestService.addSelect(fields);
-        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);
     }
     /**
-     * Add a field with a sort criteria (JSON:API, NestJS, and Spatie)
+     * Resolve a value from a response object using a dot-notation path
      *
-     * @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
+     * Supports both flat keys (`'data'`) and nested paths (`'meta.totalItems'`).
+     *
+     * @param response - The raw response object
+     * @param path - The dot-notation path to resolve
+     * @returns The resolved value, or undefined if any segment is missing
      */
-    addSort(field, order) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedSortError());
-        this._nestService.addSort({
-            field,
-            order
-        });
-        return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolve(response, path) {
+        return path.split('.').reduce((obj, key) => obj?.[key], response);
     }
     /**
-     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
+     * Resolve the "from" index value
      *
-     * ```
-     * ngQubeeService.deleteFields({
-     *   users: ['email', 'password'],
-     *   address: ['zipcode']
-     * });
-     * ```
+     * If `options.from` resolves to a value in the response, use it.
+     * Otherwise compute `(currentPage - 1) * perPage + 1` when both are known.
      *
-     * @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 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 "from" index, or `undefined` when neither path nor inputs suffice
      */
-    deleteFields(fields) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        this._nestService.deleteFields(fields);
-        return this;
+    // 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;
     }
     /**
-     * Delete selected fields for the given model in the current query builder state (JSON:API and Spatie only)
+     * Resolve the "to" index value
      *
-     * ```
-     * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
-     * ```
+     * If `options.to` resolves to a value in the response, use it.
+     * Otherwise compute `Math.min(currentPage * perPage, total)` when all
+     * three are known.
      *
-     * @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
+     * @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 "to" index, or `undefined` when neither path nor inputs suffice
      */
-    deleteFieldsByModel(model, ...fields) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedFieldSelectionError());
-        if (!fields.length) {
-            return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolveTo(response, options, currentPage, perPage, total) {
+        const direct = this.resolve(response, options.to);
+        if (direct !== undefined) {
+            return direct;
         }
-        this._nestService.deleteFields({
-            [model]: fields
-        });
-        return this;
+        if (currentPage && perPage && total) {
+            return Math.min(currentPage * perPage, total);
+        }
+        return undefined;
     }
+}
+
+/**
+ * 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"
+ *   }
+ * }
+ * ```
+ *
+ * Default key paths are configured in `JsonApiResponseOptions`. The
+ * traversal algorithm (dot-notation resolution + computed `from`/`to`) is
+ * inherited from `AbstractDotPathResponseStrategy`; this class exists so
+ * `DriverEnum.JSON_API` resolves to a distinct identity at the DI layer
+ * even though the parsing logic is shared with NestJS.
+ *
+ * @see https://jsonapi.org/format/
+ */
+class JsonApiResponseStrategy extends AbstractDotPathResponseStrategy {
+}
+
+/**
+ * Request strategy for the Laravel (pagination-only) driver
+ *
+ * Generates simple pagination URIs:
+ * - `/{resource}?limit=N&page=N`
+ *
+ * Filters, sorts, fields, includes, search, and select in state are ignored.
+ */
+class LaravelRequestStrategy extends AbstractRequestStrategy {
+    /**
+     * Pagination-only driver — no filtering, sorting, or column selection
+     */
+    capabilities = {
+        fields: false,
+        filters: false,
+        includes: false,
+        operatorFilters: false,
+        search: false,
+        select: false,
+        sort: false
+    };
     /**
-     * Remove given filters from the query builder state (JSON:API, NestJS, and Spatie)
+     * Emit only the pagination params; filters/sorts/etc. are ignored
      *
-     * @param {string[]} filters - Filters to remove
-     * @returns {this}
-     * @throws {UnsupportedFilterError} If the active driver does not support filters
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The two pagination query-string fragments
      */
-    deleteFilters(...filters) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.NESTJS, DriverEnum.SPATIE], new UnsupportedFilterError());
-        if (!filters.length) {
-            return this;
-        }
-        this._nestService.deleteFilters(...filters);
-        return this;
+    parts(state, options) {
+        return [
+            `${options.limit}=${state.limit}`,
+            `${options.page}=${state.page}`
+        ];
     }
+}
+
+/**
+ * Response strategy for the Laravel (pagination-only) driver
+ *
+ * Parses flat Laravel pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "current_page": 1,
+ *   "total": 100,
+ *   "per_page": 15,
+ *   "from": 1,
+ *   "to": 15,
+ *   ...
+ * }
+ * ```
+ */
+class LaravelResponseStrategy {
     /**
-     * Remove selected related models from the query builder state (JSON:API and Spatie only)
+     * Parse a flat Laravel pagination response into a PaginatedCollection
      *
-     * @param {string[]} includes - Models to remove
-     * @returns {this}
-     * @throws {UnsupportedIncludesError} If the active driver does not support includes
+     * @param response - The raw API response object
+     * @param options - The response key name configuration
+     * @returns A typed PaginatedCollection instance
      */
-    deleteIncludes(...includes) {
-        this._assertDriver([DriverEnum.JSON_API, DriverEnum.SPATIE], new UnsupportedIncludesError());
-        if (!includes.length) {
-            return this;
-        }
-        this._nestService.deleteIncludes(...includes);
-        return this;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response, options) {
+        return new PaginatedCollection(response[options.data], response[options.currentPage], response[options.from], response[options.to], response[options.total], response[options.perPage], response[options.prevPageUrl], response[options.nextPageUrl], response[options.lastPage], response[options.firstPageUrl], response[options.lastPageUrl]);
     }
+}
+
+/**
+ * Request strategy for the NestJS (nestjs-paginate) driver
+ *
+ * Generates URIs in the NestJS paginate format:
+ * - Simple filters: `filter.field=value`
+ * - Operator filters: `filter.field=$operator:value`
+ * - Sorts: `sortBy=field1:DESC,field2:ASC`
+ * - Select: `select=col1,col2`
+ * - Search: `search=term`
+ * - Pagination: `limit=N&page=N`
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
+ */
+class NestjsRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Remove operator filters by field name (NestJS only)
+     * Filters, operator filters, sorts, flat select, global search — no
+     * per-model fields, no includes
+     */
+    capabilities = {
+        fields: false,
+        filters: true,
+        includes: false,
+        operatorFilters: true,
+        search: true,
+        select: true,
+        sort: true
+    };
+    /**
+     * Validate that the given limit is accepted by nestjs-paginate
      *
-     * @param {string[]} fields - Field names of operator filters to remove
-     * @returns {this}
-     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
+     * 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
      */
-    deleteOperatorFilters(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedFilterOperatorError());
-        if (!fields.length) {
-            return this;
+    validateLimit(limit) {
+        if (Number.isInteger(limit) && (limit === -1 || limit >= 1)) {
+            return;
         }
-        this._nestService.deleteOperatorFilters(...fields);
-        return this;
+        throw new InvalidLimitError(limit, true);
     }
     /**
-     * Remove search term from the query builder state (NestJS only)
+     * Emit NestJS-format query-string segments in canonical order:
+     * filters → operator filters → sortBy → select → search → limit → page
      *
-     * @returns {this}
-     * @throws {UnsupportedSearchError} If the active driver does not support search
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
      */
-    deleteSearch() {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
-        this._nestService.deleteSearch();
-        return this;
+    parts(state, options) {
+        const out = [];
+        this._appendFilters(state, options, out);
+        this._appendOperatorFilters(state, options, out);
+        this._appendSort(state, options, out);
+        this._appendSelect(state, options, out);
+        this._appendSearch(state, options, out);
+        this._appendLimit(state, options, out);
+        this._appendPage(state, options, out);
+        return out;
     }
     /**
-     * Remove flat field selections from the query builder state (NestJS only)
+     * Append simple filter parameters as `filter.field=value1,value2`
      *
-     * @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
+     * @param out - The accumulator the caller joins into the URI
      */
-    deleteSelect(...fields) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSelectError());
-        if (!fields.length) {
-            return this;
+    _appendFilters(state, options, out) {
+        const keys = Object.keys(state.filters);
+        if (!keys.length) {
+            return;
         }
-        this._nestService.deleteSelect(...fields);
-        return this;
+        keys.forEach(key => {
+            const values = state.filters[key].join(',');
+            out.push(`${options.filters}.${key}=${values}`);
+        });
     }
     /**
-     * Remove sort rules from the query builder state (JSON:API, NestJS, and Spatie)
+     * Append the limit parameter
      *
-     * @param sorts - Fields used for sorting to remove
-     * @returns {this}
-     * @throws {UnsupportedSortError} If the active driver does not support sorts
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    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);
-        }
+    _appendLimit(state, options, out) {
+        out.push(`${options.limit}=${state.limit}`);
     }
     /**
-     * Clear the current state and reset the Query Builder to a fresh, clean condition
+     * Append operator-filter parameters as `filter.field=$op:value`
      *
-     * @returns {this}
-     */
-    reset() {
-        this._nestService.reset();
-        return this;
-    }
-    /**
-     * Set the base URL to use for composing the address
+     * Groups by field; multi-value operators ($in, $btw) join values with commas.
      *
-     * @param {string} baseUrl - The base URL
-     * @returns {this}
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    setBaseUrl(baseUrl) {
-        this._nestService.baseUrl = baseUrl;
-        return this;
+    _appendOperatorFilters(state, options, out) {
+        if (!state.operatorFilters.length) {
+            return;
+        }
+        state.operatorFilters.forEach((opFilter) => {
+            const values = opFilter.values.join(',');
+            out.push(`${options.filters}.${opFilter.field}=${opFilter.operator}:${values}`);
+        });
     }
     /**
-     * Set the items per page number
+     * Append the page parameter
      *
-     * 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
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    setLimit(limit) {
-        this._requestStrategy.validateLimit(limit);
-        this._nestService.limit = limit;
-        return this;
+    _appendPage(state, options, out) {
+        out.push(`${options.page}=${state.page}`);
     }
     /**
-     * Set the page that the backend will use to paginate the result set
+     * Append the search parameter as `search=term`
      *
-     * @param page - Page number
-     * @returns {this}
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    setPage(page) {
-        this._nestService.page = page;
-        return this;
+    _appendSearch(state, options, out) {
+        if (!state.search) {
+            return;
+        }
+        out.push(`${options.search}=${state.search}`);
     }
     /**
-     * Set the API resource to run the query against
+     * Append the select parameter as `select=col1,col2`
      *
-     * @param {string} resource - Resource name (e.g. 'users' produces /users)
-     * @returns {this}
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    setResource(resource) {
-        this._nestService.resource = resource;
-        return this;
+    _appendSelect(state, options, out) {
+        if (!state.select.length) {
+            return;
+        }
+        out.push(`${options.select}=${state.select.join(',')}`);
     }
     /**
-     * Set the search term for full-text search (NestJS only)
-     *
-     * Produces: `search=term`
+     * Append sort parameter as `sortBy=field1:DESC,field2:ASC`
      *
-     * @param {string} search - The search term
-     * @returns {this}
-     * @throws {UnsupportedSearchError} If the active driver does not support search
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    setSearch(search) {
-        this._assertDriver([DriverEnum.NESTJS], new UnsupportedSearchError());
-        this._nestService.setSearch(search);
-        return this;
+    _appendSort(state, options, out) {
+        if (!state.sorts.length) {
+            return;
+        }
+        const pairs = state.sorts.map(sort => `${sort.field}:${sort.order === SortEnum.DESC ? 'DESC' : 'ASC'}`);
+        out.push(`${options.sortBy}=${pairs.join(',')}`);
     }
 }
 
 /**
- * Error thrown when an invalid resource name is provided
+ * Response strategy for the NestJS (nestjs-paginate) driver
  *
- * Resource name must be a non-empty string.
+ * Parses nested NestJS pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "meta": {
+ *     "currentPage": 1,
+ *     "totalItems": 100,
+ *     "itemsPerPage": 10,
+ *     "totalPages": 10
+ *   },
+ *   "links": {
+ *     "first": "url",
+ *     "previous": "url",
+ *     "next": "url",
+ *     "last": "url",
+ *     "current": "url"
+ *   }
+ * }
+ * ```
+ *
+ * Default key paths are configured in `NestjsResponseOptions`. The
+ * traversal algorithm (dot-notation resolution + computed `from`/`to`) is
+ * inherited from `AbstractDotPathResponseStrategy`; this class exists so
+ * `DriverEnum.NESTJS` resolves to a distinct identity at the DI layer
+ * even though the parsing logic is shared with JSON:API.
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
  */
-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 NestjsResponseStrategy extends AbstractDotPathResponseStrategy {
 }
 
-class InvalidPageNumberError extends Error {
-    constructor(page) {
-        super(`Invalid page number: Page must be a positive integer greater than 0. Received: ${page}`);
-        this.name = 'InvalidPageNumberError';
+/**
+ * Enum representing the available filter operators for explicit operator
+ * filters
+ *
+ * NestJS encodes these with the `$` prefix at the wire level
+ * (`filter.field=$operator:value`); PostgREST translates them to its own
+ * prefix notation (`col=eq.val`, `col=is.null`, etc.). The enum values are
+ * intentionally the NestJS form; each driver's request strategy is
+ * responsible for mapping them into its own shape.
+ *
+ * `FTS`, `PLFTS`, `PHFTS`, `WFTS` are PostgREST-native full-text search
+ * variants; they throw `UnsupportedFilterOperatorError` on every other
+ * driver that does not recognise them.
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
+ * @see https://postgrest.org/en/stable/api.html#operators
+ */
+var FilterOperatorEnum;
+(function (FilterOperatorEnum) {
+    FilterOperatorEnum["BTW"] = "$btw";
+    FilterOperatorEnum["CONTAINS"] = "$contains";
+    FilterOperatorEnum["EQ"] = "$eq";
+    FilterOperatorEnum["FTS"] = "$fts";
+    FilterOperatorEnum["GT"] = "$gt";
+    FilterOperatorEnum["GTE"] = "$gte";
+    FilterOperatorEnum["ILIKE"] = "$ilike";
+    FilterOperatorEnum["IN"] = "$in";
+    FilterOperatorEnum["LT"] = "$lt";
+    FilterOperatorEnum["LTE"] = "$lte";
+    FilterOperatorEnum["NOT"] = "$not";
+    FilterOperatorEnum["NULL"] = "$null";
+    FilterOperatorEnum["PHFTS"] = "$phfts";
+    FilterOperatorEnum["PLFTS"] = "$plfts";
+    FilterOperatorEnum["SW"] = "$sw";
+    FilterOperatorEnum["WFTS"] = "$wfts";
+})(FilterOperatorEnum || (FilterOperatorEnum = {}));
+
+/**
+ * Enum representing the wire-level pagination mechanism
+ *
+ * `QUERY` (default) — the request strategy emits `limit` and `offset` (or
+ * equivalent) query parameters on the URL.
+ *
+ * `RANGE` — the request strategy omits URL-based pagination and the
+ * consumer instead applies HTTP request headers returned by
+ * `NgQubeeService.paginationHeaders()`. Currently honoured only by the
+ * PostgREST driver, which maps it to `Range-Unit: items` + `Range: 0-9`.
+ * Other drivers ignore the setting.
+ */
+var PaginationModeEnum;
+(function (PaginationModeEnum) {
+    PaginationModeEnum["QUERY"] = "query";
+    PaginationModeEnum["RANGE"] = "range";
+})(PaginationModeEnum || (PaginationModeEnum = {}));
+
+/**
+ * Thrown when a filter operator receives a value array of the wrong shape
+ *
+ * Some operators have arity or type constraints that the library enforces
+ * at call time so misuse fails loudly instead of silently emitting invalid
+ * server requests:
+ *
+ * - `BTW` requires exactly two values (min, max).
+ * - `NULL` requires exactly one boolean value (`true` for `IS NULL`,
+ *   `false` for `IS NOT NULL`).
+ *
+ * Operators with looser shape rules leave validation to the server; this
+ * error is reserved for cases where the library itself can detect the
+ * problem unambiguously from the call site.
+ */
+class InvalidFilterOperatorValueError extends Error {
+    /**
+     * @param operator - The operator that rejected the values
+     * @param reason - Short human-readable explanation of the constraint
+     */
+    constructor(operator, reason) {
+        super(`Invalid values for filter operator ${operator}: ${reason}`);
+        this.name = 'InvalidFilterOperatorValueError';
     }
 }
 
-const INITIAL_STATE = {
-    baseUrl: '',
-    fields: {},
-    filters: {},
-    includes: [],
-    limit: 15,
-    operatorFilters: [],
-    page: 1,
-    resource: '',
-    search: '',
-    select: [],
-    sorts: []
-};
-class NestService {
+/**
+ * Request strategy for the PostgREST driver
+ *
+ * PostgREST auto-generates REST APIs from PostgreSQL schemas and is the
+ * backbone of Supabase's data API. This strategy produces URIs in
+ * PostgREST's native query-string format:
+ *
+ * - Filters: `col=eq.val` (single value) / `col=in.(v1,v2,v3)` (multi-value)
+ * - Order: `order=col1.asc,col2.desc`
+ * - Select: `select=col1,col2`
+ * - Pagination: `limit=N&offset=M` (offset derived from state.page)
+ *
+ * The `order` and `offset` query-parameter names are PostgREST conventions
+ * and are intentionally not configurable via `QueryBuilderOptions` (see
+ * issue #50 MVP scope). `limit`, `select`, and `filters` (per-column name)
+ * honour the existing option keys.
+ *
+ * @see https://postgrest.org/en/stable/api.html
+ * @see https://supabase.com/docs/reference/javascript/select
+ */
+class PostgrestRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Private writable signal that holds the Query Builder state
-     *
-     * @type {IQueryBuilderState}
+     * Filters, operator filters (incl. FTS), sorts, flat select — no
+     * per-model fields, no JSON:API/Spatie-style includes, no global
+     * search (per-column FTS via the operator family covers it)
      */
-    _nest = signal(this._clone(INITIAL_STATE), ...(ngDevMode ? [{ debugName: "_nest" }] : []));
+    capabilities = {
+        fields: false,
+        filters: true,
+        includes: false,
+        operatorFilters: true,
+        search: false,
+        select: true,
+        sort: true
+    };
+    static _offsetKey = 'offset';
+    static _orderKey = 'order';
     /**
-     * A computed signal that makes readonly the writable signal _nest
+     * Active pagination mode
      *
-     * @type {Signal<IQueryBuilderState>}
+     * QUERY (default) → URL emits limit/offset.
+     * RANGE → URL omits them; `buildPaginationHeaders()` returns the
+     * `Range-Unit` / `Range` HTTP headers instead.
      */
-    nest = computed(() => this._clone(this._nest()), ...(ngDevMode ? [{ debugName: "nest" }] : []));
-    constructor() {
-        // Nothing to see here
+    _paginationMode;
+    /**
+     * @param paginationMode - Wire-level pagination mechanism. Defaults to
+     * `PaginationModeEnum.QUERY`; `provideNgQubee` wires this from
+     * `IConfig.pagination`.
+     */
+    constructor(paginationMode = PaginationModeEnum.QUERY) {
+        super();
+        this._paginationMode = paginationMode;
     }
     /**
-     * Set the base URL for the API
+     * Compute `Range-Unit` / `Range` HTTP headers for RANGE pagination mode
      *
-     * @param {string} baseUrl - The base URL to prepend to generated URIs
-     * @example
-     * service.baseUrl = 'https://api.example.com';
+     * In QUERY mode this returns `null` so `NgQubeeService.paginationHeaders()`
+     * conveys "no headers needed" to the consumer. In RANGE mode the method
+     * converts the 1-indexed `state.page` + `state.limit` into PostgREST's
+     * 0-indexed inclusive range (`from = (page - 1) * limit`,
+     * `to = from + limit - 1`) and returns both header values.
+     *
+     * @param state - The current query builder state
+     * @returns `{ 'Range-Unit': 'items', 'Range': 'from-to' }` or `null`
      */
-    set baseUrl(baseUrl) {
-        this._nest.update(nest => ({
-            ...nest,
-            baseUrl
-        }));
+    buildPaginationHeaders(state) {
+        if (this._paginationMode !== PaginationModeEnum.RANGE) {
+            return null;
+        }
+        const from = (state.page - 1) * state.limit;
+        const to = from + state.limit - 1;
+        /* eslint-disable @typescript-eslint/naming-convention */
+        return {
+            'Range-Unit': 'items',
+            'Range': `${from}-${to}`
+        };
+        /* eslint-enable @typescript-eslint/naming-convention */
     }
     /**
-     * Set the limit for paginated results
+     * Emit PostgREST-format query-string segments in canonical order:
+     * filters → operator filters → order → select → (limit + offset in
+     * QUERY mode only — RANGE mode passes pagination via headers instead)
      *
-     * 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 state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
+     */
+    parts(state, options) {
+        const out = [];
+        this._appendFilters(state, out);
+        this._appendOperatorFilters(state, out);
+        this._appendOrder(state, out);
+        this._appendSelect(state, options, out);
+        if (this._paginationMode === PaginationModeEnum.QUERY) {
+            this._appendLimit(state, options, out);
+            this._appendOffset(state, out);
+        }
+        return out;
+    }
+    /**
+     * Append filter parameters in PostgREST format
      *
-     * @param {number} limit - The number of items per page
-     * @example
-     * service.limit = 25;
+     * Every filter is operator-prefixed (PostgREST has no implicit equality):
+     * a single value yields `col=eq.val`; multiple values collapse into
+     * PostgREST's native IN-list syntax `col=in.(v1,v2,v3)`.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
      */
-    set limit(limit) {
-        this._nest.update(nest => ({
-            ...nest,
-            limit
-        }));
+    _appendFilters(state, out) {
+        const keys = Object.keys(state.filters);
+        if (!keys.length) {
+            return;
+        }
+        keys.forEach(key => {
+            const values = state.filters[key];
+            if (!values.length) {
+                return;
+            }
+            // single-value → eq.<val>
+            // multi-value → in.(v1,v2,v3)
+            const rhs = values.length === 1
+                ? `eq.${values[0]}`
+                : `in.(${values.join(',')})`;
+            out.push(`${key}=${rhs}`);
+        });
     }
     /**
-     * Set the page number for pagination
-     * Must be a positive integer greater than 0
+     * Append the limit parameter
      *
-     * @param {number} page - The page number to fetch
-     * @throws {InvalidPageNumberError} If page is not a positive integer
-     * @example
-     * service.page = 2;
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    set page(page) {
-        this._validatePageNumber(page);
-        this._nest.update(nest => ({
-            ...nest,
-            page
-        }));
+    _appendLimit(state, options, out) {
+        out.push(`${options.limit}=${state.limit}`);
     }
     /**
-     * Set the resource name for the query
-     * Must be a non-empty string
+     * Append the offset parameter, derived from state.page
      *
-     * @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';
+     * PostgREST uses offset-based pagination, not page-based. The offset is
+     * computed as `(page - 1) * limit`. Omitted when offset would be 0
+     * (i.e. page 1) since PostgREST defaults to offset=0 anyway and dropping
+     * it keeps the URI shorter.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
      */
-    set resource(resource) {
-        this._validateResourceName(resource);
-        this._nest.update(nest => ({
-            ...nest,
-            resource
-        }));
-    }
-    _clone(obj) {
-        return JSON.parse(JSON.stringify(obj));
+    _appendOffset(state, out) {
+        const offset = (state.page - 1) * state.limit;
+        if (offset <= 0) {
+            return;
+        }
+        out.push(`${PostgrestRequestStrategy._offsetKey}=${offset}`);
     }
     /**
-     * Validates that the page number is a positive integer
+     * Append explicit operator filters
      *
-     * @param {number} page - The page number to validate
-     * @throws {InvalidPageNumberError} If page is not a positive integer
-     * @private
+     * Maps each `FilterOperatorEnum` value to PostgREST's prefix-operator
+     * syntax. `BTW` expands to two query params (`gte` + `lte`); `NULL`
+     * emits `is.null` / `is.not.null` based on the boolean value; `NOT`
+     * picks its inner operator by arity (`not.eq.val` for single values,
+     * `not.in.(v1,v2)` for multi-value).
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     * @throws {InvalidFilterOperatorValueError} If `BTW` does not receive exactly 2 values, or `NULL` does not receive exactly 1 boolean
      */
-    _validatePageNumber(page) {
-        if (!Number.isInteger(page) || page < 1) {
-            throw new InvalidPageNumberError(page);
+    _appendOperatorFilters(state, out) {
+        if (!state.operatorFilters.length) {
+            return;
         }
+        state.operatorFilters.forEach(filter => {
+            // BTW expands to two segments: col=gte.min and col=lte.max
+            if (filter.operator === FilterOperatorEnum.BTW) {
+                this._appendBetweenFilter(filter, out);
+                return;
+            }
+            const rhs = this._formatOperatorRhs(filter);
+            out.push(`${filter.field}=${rhs}`);
+        });
     }
     /**
-     * Validates that the resource name is a non-empty string
+     * Append a `BTW` operator filter as two PostgREST segments
      *
-     * @param {string} resource - The resource name to validate
-     * @throws {InvalidResourceNameError} If resource is not a non-empty string
-     * @private
+     * Produces: `col=gte.min` and `col=lte.max`. Values must be exactly
+     * `[min, max]`.
+     *
+     * @param filter - The operator filter carrying the BTW bounds
+     * @param out - The accumulator the caller joins into the URI
+     * @throws {InvalidFilterOperatorValueError} If values.length !== 2
      */
-    _validateResourceName(resource) {
-        if (!resource || typeof resource !== 'string' || resource.trim().length === 0) {
-            throw new InvalidResourceNameError(resource);
+    _appendBetweenFilter(filter, out) {
+        if (filter.values.length !== 2) {
+            throw new InvalidFilterOperatorValueError(filter.operator, 'BTW requires exactly 2 values (min, max)');
+        }
+        const [min, max] = filter.values;
+        out.push(`${filter.field}=gte.${min}`);
+        out.push(`${filter.field}=lte.${max}`);
+    }
+    /**
+     * Build the right-hand-side of a PostgREST filter param for the given operator
+     *
+     * Kept as a separate helper so each operator's shape is visible in one
+     * place and the dispatch is exhaustively typed against
+     * `FilterOperatorEnum`.
+     *
+     * @param filter - The operator filter (field, operator, values)
+     * @returns The PostgREST-formatted value portion (right of the `=` sign)
+     * @throws {InvalidFilterOperatorValueError} If NULL receives a non-boolean or wrong arity
+     */
+    _formatOperatorRhs(filter) {
+        const { operator, values } = filter;
+        const first = values[0];
+        switch (operator) {
+            case FilterOperatorEnum.EQ: return `eq.${first}`;
+            case FilterOperatorEnum.GT: return `gt.${first}`;
+            case FilterOperatorEnum.GTE: return `gte.${first}`;
+            case FilterOperatorEnum.LT: return `lt.${first}`;
+            case FilterOperatorEnum.LTE: return `lte.${first}`;
+            case FilterOperatorEnum.ILIKE: return `ilike.${first}`;
+            case FilterOperatorEnum.IN: return `in.(${values.join(',')})`;
+            case FilterOperatorEnum.SW: return `like.${first}*`;
+            case FilterOperatorEnum.CONTAINS: return `ilike.%${first}%`;
+            case FilterOperatorEnum.FTS: return `fts.${first}`;
+            case FilterOperatorEnum.PLFTS: return `plfts.${first}`;
+            case FilterOperatorEnum.PHFTS: return `phfts.${first}`;
+            case FilterOperatorEnum.WFTS: return `wfts.${first}`;
+            case FilterOperatorEnum.NOT:
+                return values.length === 1
+                    ? `not.eq.${first}`
+                    : `not.in.(${values.join(',')})`;
+            case FilterOperatorEnum.NULL: {
+                if (values.length !== 1 || typeof first !== 'boolean') {
+                    throw new InvalidFilterOperatorValueError(operator, 'NULL requires exactly 1 boolean value (true → IS NULL, false → IS NOT NULL)');
+                }
+                return first ? 'is.null' : 'is.not.null';
+            }
+            // BTW is dispatched by _appendOperatorFilters; falling through would be a bug
+            case FilterOperatorEnum.BTW:
+                throw new InvalidFilterOperatorValueError(operator, 'BTW should be dispatched to _appendBetweenFilter — this indicates a bug');
         }
     }
     /**
-     * Add selectable fields for the given model to the request
-     * Automatically prevents duplicate fields for each model
+     * Append the order parameter as `order=col1.asc,col2.desc`
      *
-     * @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 state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
      */
-    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
-            };
-        });
+    _appendOrder(state, out) {
+        if (!state.sorts.length) {
+            return;
+        }
+        const pairs = state.sorts.map(sort => `${sort.field}.${sort.order === SortEnum.DESC ? 'desc' : 'asc'}`);
+        out.push(`${PostgrestRequestStrategy._orderKey}=${pairs.join(',')}`);
     }
     /**
-     * Add filters to the request
-     * Automatically prevents duplicate filter values for each filter key
+     * Append the select parameter as `select=col1,col2`
      *
-     * @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'] });
+     * PostgREST uses a `select` query param for column pruning, matching
+     * NestJS semantics.
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    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;
-            });
-            return {
-                ...nest,
-                filters: mergedFilters
-            };
-        });
+    _appendSelect(state, options, out) {
+        if (!state.select.length) {
+            return;
+        }
+        out.push(`${options.select}=${state.select.join(',')}`);
+    }
+}
+
+/**
+ * Read a header value by name from a `HeaderBag`, regardless of whether the
+ * bag exposes a `.get()` accessor or plain property access.
+ *
+ * @param bag - The header bag to read from
+ * @param name - The header name (case-sensitivity follows the underlying bag)
+ * @returns The header value, or `null` if absent or the bag itself is falsy
+ */
+function readHeader(bag, name) {
+    if (!bag) {
+        return null;
+    }
+    const accessor = bag;
+    if (typeof accessor.get === 'function') {
+        return accessor.get(name);
+    }
+    const value = bag[name];
+    return value ?? null;
+}
+
+/**
+ * Response strategy for the PostgREST driver
+ *
+ * PostgREST (and Supabase, which wraps it) returns a bare array body for
+ * collection endpoints. Pagination metadata is carried in the
+ * `Content-Range` HTTP response header, e.g. `0-9/50` meaning "items 0–9
+ * out of 50 total". Consumers opt into totals by sending the
+ * `Prefer: count=exact` request header.
+ *
+ * This strategy expects the consumer to pass the array body as `response`
+ * (or a plain object with `response[options.data]` pointing at the array)
+ * and the response headers via the optional `headers` bag. See
+ * `PaginationService.paginate()` for the call-site shape.
+ *
+ * @see https://postgrest.org/en/stable/references/api/pagination_count.html
+ */
+class PostgrestResponseStrategy {
+    static _contentRangeHeader = 'Content-Range';
+    static _contentRangeRegex = /^(\d+)-(\d+)\/(\*|\d+)$/;
+    /**
+     * Parse a PostgREST response into a typed PaginatedCollection
+     *
+     * @param response - The raw response. Either the array body directly, or
+     * an object with the array at `response[options.data]`.
+     * @param options - The response key configuration (only `options.data` is
+     * consulted; all pagination metadata comes from the Content-Range header).
+     * @param headers - Optional HTTP response headers. The `Content-Range`
+     * header drives page/total derivation; omission is tolerated and yields
+     * a collection with `undefined` bounds (auto-sync will leave
+     * `isLastPageKnown` at `false`).
+     * @returns A typed PaginatedCollection instance
+     */
+    paginate(response, options, headers) {
+        // Body may be a bare array or an envelope with the array at options.data
+        const data = (Array.isArray(response) ? response : response[options.data]);
+        // Header-driven pagination metadata
+        const contentRange = readHeader(headers, PostgrestResponseStrategy._contentRangeHeader);
+        const { from, to, total } = this._parseContentRange(contentRange);
+        // Per-page can only be derived from the from/to range; fall back to undefined
+        const perPage = (from !== undefined && to !== undefined) ? (to - from + 1) : undefined;
+        // Page is 1-based in ng-qubee state; PostgREST reports 0-based indices
+        const page = (perPage && from !== undefined) ? Math.floor(from / perPage) + 1 : 1;
+        const lastPage = (total !== undefined && perPage) ? Math.ceil(total / perPage) : undefined;
+        // Library convention: from/to are 1-indexed and inclusive; PostgREST emits 0-indexed
+        const fromOneIndexed = from !== undefined ? from + 1 : undefined;
+        const toOneIndexed = to !== undefined ? to + 1 : undefined;
+        // PostgREST does not emit page URLs, so prev/next/first/last URLs stay undefined
+        return new PaginatedCollection(data, page, fromOneIndexed, toOneIndexed, total, perPage, undefined, undefined, lastPage);
+    }
+    /**
+     * Extract `{from, to, total}` from a PostgREST `Content-Range` value
+     *
+     * Expected format: `<from>-<to>/<total|*>`. Any shape mismatch returns
+     * an empty object; `*` as the total yields `total: undefined`.
+     *
+     * @param value - Raw header value (possibly null/undefined)
+     * @returns Parsed integers; missing fields indicate an unparseable header
+     */
+    _parseContentRange(value) {
+        if (!value) {
+            return {};
+        }
+        const match = value.trim().match(PostgrestResponseStrategy._contentRangeRegex);
+        if (!match) {
+            return {};
+        }
+        const from = parseInt(match[1], 10);
+        const to = parseInt(match[2], 10);
+        const total = match[3] === '*' ? undefined : parseInt(match[3], 10);
+        return { from, to, total };
     }
+}
+
+/**
+ * Request strategy for the Spatie Query Builder driver
+ *
+ * Generates URIs in the Spatie format:
+ * - Fields: `fields[model]=col1,col2`
+ * - Filters: `filter[field]=value`
+ * - Includes: `include=model1,model2`
+ * - Sorts: `sort=-field1,field2` (- prefix = DESC)
+ * - Pagination: `limit=N&page=N`
+ *
+ * @see https://spatie.be/docs/laravel-query-builder
+ */
+class SpatieRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Add resources to include with the request
-     * Automatically prevents duplicate includes
+     * Filters, sorts, includes, per-model fields — no operators, no flat
+     * select, no global search
+     */
+    capabilities = {
+        fields: true,
+        filters: true,
+        includes: true,
+        operatorFilters: false,
+        search: false,
+        select: false,
+        sort: true
+    };
+    /**
+     * Emit Spatie-format query-string segments in canonical order:
+     * include → fields → filters → limit → page → sort
      *
-     * @param {string[]} includes - Array of resource names to include in the response
-     * @return {void}
-     * @example
-     * service.addIncludes(['profile', 'posts']);
-     * service.addIncludes(['comments']);
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
      */
-    addIncludes(includes) {
-        this._nest.update(nest => {
-            // Use Set to prevent duplicates
-            const uniqueIncludes = Array.from(new Set([...nest.includes, ...includes]));
-            return {
-                ...nest,
-                includes: uniqueIncludes
-            };
-        });
+    parts(state, options) {
+        const out = [];
+        this._appendIncludes(state, options, out);
+        this._appendFields(state, options, out);
+        this._appendFilters(state, options, out);
+        this._appendLimit(state, options, out);
+        this._appendPage(state, options, out);
+        this._appendSort(state, options, out);
+        return out;
     }
     /**
-     * Add filters with explicit operators (NestJS only)
-     * Automatically prevents duplicate operator filters for the same field + operator combination
+     * Append per-model field selection in bracket notation
      *
-     * @param {IOperatorFilter[]} filters - Array of operator filter configurations
-     * @return {void}
-     * @example
-     * import { FilterOperatorEnum } from 'ng-qubee';
-     * service.addOperatorFilters([{ field: 'age', operator: FilterOperatorEnum.GTE, values: [18] }]);
+     * Validates that each field model exists either as the main resource
+     * or in the includes list.
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
+     * @throws Error if the resource is required but not set
+     * @throws UnselectableModelError if a field model is not in resource or includes
      */
-    addOperatorFilters(filters) {
-        this._nest.update(nest => {
-            const merged = [...nest.operatorFilters];
-            filters.forEach(newFilter => {
-                const existingIdx = merged.findIndex(f => f.field === newFilter.field && f.operator === newFilter.operator);
-                if (existingIdx > -1) {
-                    const existingValues = merged[existingIdx].values;
-                    merged[existingIdx] = {
-                        ...merged[existingIdx],
-                        values: Array.from(new Set([...existingValues, ...newFilter.values]))
-                    };
-                }
-                else {
-                    merged.push({ ...newFilter });
-                }
-            });
-            return {
-                ...nest,
-                operatorFilters: merged
-            };
-        });
+    _appendFields(state, options, out) {
+        if (!Object.keys(state.fields).length) {
+            return;
+        }
+        if (!(state.resource in state.fields)) {
+            throw new Error(`Key ${state.resource} is missing in the fields object`);
+        }
+        const grouped = {};
+        for (const model in state.fields) {
+            if (!state.fields.hasOwnProperty(model)) {
+                continue;
+            }
+            if (model !== state.resource && !state.includes.includes(model)) {
+                throw new UnselectableModelError(model);
+            }
+            grouped[`${options.fields}[${model}]`] = state.fields[model].join(',');
+        }
+        out.push(qs.stringify(grouped, { encode: false }));
     }
     /**
-     * Add flat field selection columns (NestJS only)
-     * Automatically prevents duplicate select fields
+     * Append filter parameters in bracket notation: `filter[key]=value`
      *
-     * @param {string[]} fields - Array of column names to select
-     * @return {void}
-     * @example
-     * service.addSelect(['id', 'name', 'email']);
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addSelect(fields) {
-        this._nest.update(nest => {
-            const uniqueSelect = Array.from(new Set([...nest.select, ...fields]));
-            return {
-                ...nest,
-                select: uniqueSelect
-            };
-        });
+    _appendFilters(state, options, out) {
+        const keys = Object.keys(state.filters);
+        if (!keys.length) {
+            return;
+        }
+        const wrapper = {
+            [options.filters]: keys.reduce((acc, key) => {
+                return Object.assign(acc, { [key]: state.filters[key].join(',') });
+            }, {})
+        };
+        out.push(qs.stringify(wrapper, { encode: false }));
     }
     /**
-     * Add a field that should be used for sorting data
+     * Append include parameter as `include=model1,model2`
      *
-     * @param {ISort} sort - Sort configuration with field name and order (ASC/DESC)
-     * @return {void}
-     * @example
-     * import { SortEnum } from 'ng-qubee';
-     * service.addSort({ field: 'created_at', order: SortEnum.DESC });
-     * service.addSort({ field: 'name', order: SortEnum.ASC });
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    addSort(sort) {
-        this._nest.update(nest => ({
-            ...nest,
-            sorts: [...nest.sorts, sort]
-        }));
+    _appendIncludes(state, options, out) {
+        if (!state.includes.length) {
+            return;
+        }
+        out.push(`${options.includes}=${state.includes}`);
     }
     /**
-     * Remove fields for the given model
-     * Uses deep cloning to prevent mutations to the original state
+     * Append the limit parameter
      *
-     * @param {IFields} fields - Object mapping model names to arrays of field names to remove
-     * @return {void}
-     * @example
-     * service.deleteFields({ users: ['email'] });
-     * service.deleteFields({ posts: ['content', 'body'] });
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    deleteFields(fields) {
-        // Deep clone the fields object to prevent mutations
-        const f = this._clone(this._nest().fields);
-        Object.keys(fields).forEach(k => {
-            if (!(k in f)) {
-                return;
-            }
-            f[k] = f[k].filter(v => !fields[k].includes(v));
-        });
-        this._nest.update(nest => ({
-            ...nest,
-            fields: f
-        }));
+    _appendLimit(state, options, out) {
+        out.push(`${options.limit}=${state.limit}`);
     }
     /**
-     * Remove filters from the request
-     * Uses deep cloning to prevent mutations to the original state
+     * Append the page parameter
      *
-     * @param {...string[]} filters - Filter keys to remove
-     * @return {void}
-     * @example
-     * service.deleteFilters('id');
-     * service.deleteFilters('status', 'type');
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    deleteFilters(...filters) {
-        // Deep clone the filters object to prevent mutations
-        const f = this._clone(this._nest().filters);
-        filters.forEach(k => delete f[k]);
-        this._nest.update(nest => ({
-            ...nest,
-            filters: f
-        }));
+    _appendPage(state, options, out) {
+        out.push(`${options.page}=${state.page}`);
     }
     /**
-     * Remove includes from the request
+     * Append sort parameter as `sort=-field1,field2` (`-` prefix = DESC)
      *
-     * @param {...string[]} includes - Include names to remove
-     * @return {void}
-     * @example
-     * service.deleteIncludes('profile');
-     * service.deleteIncludes('posts', 'comments');
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    deleteIncludes(...includes) {
-        this._nest.update(nest => ({
-            ...nest,
-            includes: nest.includes.filter(v => !includes.includes(v))
-        }));
+    _appendSort(state, options, out) {
+        if (!state.sorts.length) {
+            return;
+        }
+        const pairs = state.sorts.map(sort => `${sort.order === SortEnum.DESC ? '-' : ''}${sort.field}`);
+        out.push(`${options.sort}=${pairs.join(',')}`);
     }
+}
+
+/**
+ * Response strategy for the Spatie Query Builder driver
+ *
+ * Parses flat Laravel pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "current_page": 1,
+ *   "total": 100,
+ *   "per_page": 15,
+ *   "from": 1,
+ *   "to": 15,
+ *   ...
+ * }
+ * ```
+ *
+ * @see https://spatie.be/docs/laravel-query-builder
+ */
+class SpatieResponseStrategy {
     /**
-     * Remove operator filters by field name (NestJS only)
+     * Parse a flat Laravel pagination response into a PaginatedCollection
      *
-     * @param {...string[]} fields - Field names of operator filters to remove
-     * @return {void}
-     * @example
-     * service.deleteOperatorFilters('age');
-     * service.deleteOperatorFilters('price', 'quantity');
+     * @param response - The raw API response object
+     * @param options - The response key name configuration
+     * @returns A typed PaginatedCollection instance
      */
-    deleteOperatorFilters(...fields) {
-        this._nest.update(nest => ({
-            ...nest,
-            operatorFilters: nest.operatorFilters.filter(f => !fields.includes(f.field))
-        }));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response, options) {
+        return new PaginatedCollection(response[options.data], response[options.currentPage], response[options.from], response[options.to], response[options.total], response[options.perPage], response[options.prevPageUrl], response[options.nextPageUrl], response[options.lastPage], response[options.firstPageUrl], response[options.lastPageUrl]);
+    }
+}
+
+/**
+ * Driver registry — single source of truth for what each `DriverEnum`
+ * value resolves to
+ *
+ * `Record<DriverEnum, IDriverDefinition>` gives compile-time
+ * exhaustiveness: adding a new value to `DriverEnum` fails to compile
+ * until its definition is added here. `provideNgQubee` looks up the
+ * definition by driver and calls the three factories — no more parallel
+ * `switch` blocks.
+ */
+const DRIVERS = {
+    [DriverEnum.JSON_API]: {
+        createRequestStrategy: () => new JsonApiRequestStrategy(),
+        createResponseStrategy: () => new JsonApiResponseStrategy(),
+        createResponseOptions: (config) => new JsonApiResponseOptions(config)
+    },
+    [DriverEnum.LARAVEL]: {
+        createRequestStrategy: () => new LaravelRequestStrategy(),
+        createResponseStrategy: () => new LaravelResponseStrategy(),
+        createResponseOptions: (config) => new ResponseOptions(config)
+    },
+    [DriverEnum.NESTJS]: {
+        createRequestStrategy: () => new NestjsRequestStrategy(),
+        createResponseStrategy: () => new NestjsResponseStrategy(),
+        createResponseOptions: (config) => new NestjsResponseOptions(config)
+    },
+    [DriverEnum.POSTGREST]: {
+        createRequestStrategy: (mode) => new PostgrestRequestStrategy(mode),
+        createResponseStrategy: () => new PostgrestResponseStrategy(),
+        createResponseOptions: (config) => new ResponseOptions(config)
+    },
+    [DriverEnum.SPATIE]: {
+        createRequestStrategy: () => new SpatieRequestStrategy(),
+        createResponseStrategy: () => new SpatieResponseStrategy(),
+        createResponseOptions: (config) => new ResponseOptions(config)
+    }
+};
+
+/**
+ * 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';
+    }
+}
+
+/**
+ * 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: [],
+    isLastPageKnown: false,
+    lastPage: 1,
+    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
     }
     /**
-     * Remove the search term from the state (NestJS only)
+     * Set the base URL for the API
      *
-     * @return {void}
+     * @param {string} baseUrl - The base URL to prepend to generated URIs
      * @example
-     * service.deleteSearch();
+     * service.baseUrl = 'https://api.example.com';
      */
-    deleteSearch() {
+    set baseUrl(baseUrl) {
         this._nest.update(nest => ({
             ...nest,
-            search: ''
+            baseUrl
         }));
     }
     /**
-     * Remove flat field selections from the state (NestJS only)
+     * Set the limit for paginated results
      *
-     * @param {...string[]} fields - Field names to remove from selection
-     * @return {void}
+     * 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.deleteSelect('email');
-     * service.deleteSelect('name', 'email');
+     * service.limit = 25;
      */
-    deleteSelect(...fields) {
+    set limit(limit) {
         this._nest.update(nest => ({
             ...nest,
-            select: nest.select.filter(f => !fields.includes(f))
+            limit
         }));
     }
     /**
-     * Remove sorts from the request by field name
+     * Set the page number for pagination
+     * Must be a positive integer greater than 0
      *
-     * @param {...string[]} sorts - Field names of sorts to remove
-     * @return {void}
+     * @param {number} page - The page number to fetch
+     * @throws {InvalidPageNumberError} If page is not a positive integer
      * @example
-     * service.deleteSorts('created_at');
-     * service.deleteSorts('name', 'created_at');
+     * service.page = 2;
      */
-    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);
-            }
-        });
+    set page(page) {
+        this._validatePageNumber(page);
         this._nest.update(nest => ({
             ...nest,
-            sorts: s
+            page
         }));
     }
     /**
-     * Set the full-text search term (NestJS only)
+     * Set the resource name for the query
+     * Must be a non-empty string
      *
-     * @param {string} search - The search term
-     * @return {void}
+     * @param {string} resource - The API resource name (e.g., 'users', 'posts')
+     * @throws {InvalidResourceNameError} If resource is not a non-empty string
      * @example
-     * service.setSearch('john doe');
+     * service.resource = 'users';
      */
-    setSearch(search) {
+    set resource(resource) {
+        this._validateResourceName(resource);
         this._nest.update(nest => ({
             ...nest,
-            search
+            resource
         }));
     }
+    _clone(obj) {
+        return JSON.parse(JSON.stringify(obj));
+    }
     /**
-     * Reset the query builder state to initial values
-     * Clears all fields, filters, includes, sorts, and resets pagination
+     * Validates that the page number is a positive integer
      *
-     * @return {void}
-     * @example
-     * service.reset();
+     * @param {number} page - The page number to validate
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @private
      */
-    reset() {
-        this._nest.update(_ => this._clone(INITIAL_STATE));
+    _validatePageNumber(page) {
+        if (!Number.isInteger(page) || page < 1) {
+            throw new InvalidPageNumberError(page);
+        }
     }
-    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 {
-    /**
-     * Resolved response key name options
-     */
-    _options;
     /**
-     * The response strategy that parses responses for the active driver
+     * 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
      */
-    _responseStrategy;
-    constructor(responseStrategy, options = {}) {
-        this._options = new ResponseOptions(options);
-        this._responseStrategy = responseStrategy;
+    _validateResourceName(resource) {
+        if (!resource || typeof resource !== 'string' || resource.trim().length === 0) {
+            throw new InvalidResourceNameError(resource);
+        }
     }
     /**
-     * Transform a raw API response into a typed PaginatedCollection
+     * Add selectable fields for the given model to the request
+     * Automatically prevents duplicate fields for each model
      *
-     * Delegates to the active driver's response strategy for parsing.
+     * @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 response - The raw API response object
-     * @returns A typed PaginatedCollection instance
+     * @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'] });
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    paginate(response) {
-        return this._responseStrategy.paginate(response, this._options);
+    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;
+            });
+            return {
+                ...nest,
+                filters: mergedFilters
+            };
+        });
     }
-}
-
-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)
+     * Add resources to include with the request
+     * Automatically prevents duplicate includes
+     *
+     * @param {string[]} includes - Array of resource names to include in the response
+     * @return {void}
+     * @example
+     * service.addIncludes(['profile', 'posts']);
+     * service.addIncludes(['comments']);
      */
-    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';
+    addIncludes(includes) {
+        this._nest.update(nest => {
+            // Use Set to prevent duplicates
+            const uniqueIncludes = Array.from(new Set([...nest.includes, ...includes]));
+            return {
+                ...nest,
+                includes: uniqueIncludes
+            };
+        });
     }
-}
-
-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.`);
+    /**
+     * Add filters with explicit operators (NestJS only)
+     * Automatically prevents duplicate operator filters for the same field + operator combination
+     *
+     * @param {IOperatorFilter[]} filters - Array of operator filter configurations
+     * @return {void}
+     * @example
+     * import { FilterOperatorEnum } from 'ng-qubee';
+     * service.addOperatorFilters([{ field: 'age', operator: FilterOperatorEnum.GTE, values: [18] }]);
+     */
+    addOperatorFilters(filters) {
+        this._nest.update(nest => {
+            const merged = [...nest.operatorFilters];
+            filters.forEach(newFilter => {
+                const existingIdx = merged.findIndex(f => f.field === newFilter.field && f.operator === newFilter.operator);
+                if (existingIdx > -1) {
+                    const existingValues = merged[existingIdx].values;
+                    merged[existingIdx] = {
+                        ...merged[existingIdx],
+                        values: Array.from(new Set([...existingValues, ...newFilter.values]))
+                    };
+                }
+                else {
+                    merged.push({ ...newFilter });
+                }
+            });
+            return {
+                ...nest,
+                operatorFilters: merged
+            };
+        });
     }
-}
-
-/**
- * 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
+     * Add flat field selection columns (NestJS only)
+     * Automatically prevents duplicate select fields
+     *
+     * @param {string[]} fields - Array of column names to select
+     * @return {void}
+     * @example
+     * service.addSelect(['id', 'name', 'email']);
      */
-    _uri = '';
+    addSelect(fields) {
+        this._nest.update(nest => {
+            const uniqueSelect = Array.from(new Set([...nest.select, ...fields]));
+            return {
+                ...nest,
+                select: uniqueSelect
+            };
+        });
+    }
     /**
-     * Build a URI string from the given state using the JSON:API format
+     * Add a field that should be used for sorting data
      *
-     * @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
+     * @param {ISort} sort - Sort configuration with field name and order (ASC/DESC)
+     * @return {void}
+     * @example
+     * import { SortEnum } from 'ng-qubee';
+     * service.addSort({ field: 'created_at', order: SortEnum.DESC });
+     * service.addSort({ field: 'name', order: SortEnum.ASC });
      */
-    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;
+    addSort(sort) {
+        this._nest.update(nest => ({
+            ...nest,
+            sorts: [...nest.sorts, sort]
+        }));
     }
     /**
-     * Validate that the given limit is accepted by the JSON:API driver
+     * Remove fields for the given model
+     * Uses deep cloning to prevent mutations to the original state
      *
-     * 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 {IFields} fields - Object mapping model names to arrays of field names to remove
+     * @return {void}
+     * @example
+     * service.deleteFields({ users: ['email'] });
+     * service.deleteFields({ posts: ['content', 'body'] });
+     */
+    deleteFields(fields) {
+        // Deep clone the fields object to prevent mutations
+        const f = this._clone(this._nest().fields);
+        Object.keys(fields).forEach(k => {
+            if (!(k in f)) {
+                return;
+            }
+            f[k] = f[k].filter(v => !fields[k].includes(v));
+        });
+        this._nest.update(nest => ({
+            ...nest,
+            fields: f
+        }));
+    }
+    /**
+     * Remove filters from the request
+     * Uses deep cloning to prevent mutations to the original state
      *
-     * @param limit - The limit value to validate
-     * @throws {InvalidLimitError} If the value is not a positive integer
+     * @param {...string[]} filters - Filter keys to remove
+     * @return {void}
+     * @example
+     * service.deleteFilters('id');
+     * service.deleteFilters('status', 'type');
      */
-    validateLimit(limit) {
-        if (Number.isInteger(limit) && limit >= 1) {
-            return;
-        }
-        throw new InvalidLimitError(limit);
+    deleteFilters(...filters) {
+        // Deep clone the filters object to prevent mutations
+        const f = this._clone(this._nest().filters);
+        filters.forEach(k => delete f[k]);
+        this._nest.update(nest => ({
+            ...nest,
+            filters: f
+        }));
     }
     /**
-     * Parse and append field selection parameters
+     * Remove includes from the request
      *
-     * 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 {...string[]} includes - Include names to remove
+     * @return {void}
+     * @example
+     * service.deleteIncludes('profile');
+     * service.deleteIncludes('posts', 'comments');
+     */
+    deleteIncludes(...includes) {
+        this._nest.update(nest => ({
+            ...nest,
+            includes: nest.includes.filter(v => !includes.includes(v))
+        }));
+    }
+    /**
+     * Remove operator filters by field name (NestJS only)
      *
-     * @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
+     * @param {...string[]} fields - Field names of operator filters to remove
+     * @return {void}
+     * @example
+     * service.deleteOperatorFilters('age');
+     * service.deleteOperatorFilters('price', 'quantity');
      */
-    _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;
+    deleteOperatorFilters(...fields) {
+        this._nest.update(nest => ({
+            ...nest,
+            operatorFilters: nest.operatorFilters.filter(f => !fields.includes(f.field))
+        }));
     }
     /**
-     * Parse and append filter parameters
+     * Remove the search term from the state (NestJS only)
      *
-     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     * @return {void}
+     * @example
+     * service.deleteSearch();
+     */
+    deleteSearch() {
+        this._nest.update(nest => ({
+            ...nest,
+            search: ''
+        }));
+    }
+    /**
+     * Remove flat field selections from the state (NestJS only)
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated filter parameter string
+     * @param {...string[]} fields - Field names to remove from selection
+     * @return {void}
+     * @example
+     * service.deleteSelect('email');
+     * service.deleteSelect('name', 'email');
      */
-    _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;
+    deleteSelect(...fields) {
+        this._nest.update(nest => ({
+            ...nest,
+            select: nest.select.filter(f => !fields.includes(f))
+        }));
     }
     /**
-     * Parse and append include parameters
+     * Remove sorts from the request by field name
      *
-     * Generates: `include=author,comments.author`
+     * @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 state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated include parameter string
+     * @param {string} search - The search term
+     * @return {void}
+     * @example
+     * service.setSearch('john doe');
      */
-    _parseIncludes(state, options) {
-        if (!state.includes.length) {
-            return this._uri;
-        }
-        const param = `${this._prepend(state)}${options.includes}=${state.includes}`;
-        this._uri += param;
-        return param;
+    setSearch(search) {
+        this._nest.update(nest => ({
+            ...nest,
+            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
+     *
+     * @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: () => [] });
+
+/**
+ * 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 {
+    /**
+     * @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.
+     */
+    constructor(action) {
+        super(`Cannot ${action}: no paginated response has been synced yet. Call PaginationService.paginate() at least once first.`);
+        this.name = 'PaginationNotSyncedError';
+    }
+}
+
+/**
+ * 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';
     }
-    /**
-     * 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;
+}
+
+/**
+ * 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';
     }
-    /**
-     * 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;
+}
+
+/**
+ * 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';
     }
-    /**
-     * 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}?`;
+}
+
+/**
+ * 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';
     }
 }
 
 /**
- * Response strategy for the JSON:API driver
+ * Injection token for the active pagination 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"
- *   }
- * }
- * ```
+ * 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
  *
- * @see https://jsonapi.org/format/
+ * 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`.
  */
-class JsonApiResponseStrategy {
+const NG_QUBEE_RESPONSE_OPTIONS = new InjectionToken('NG_QUBEE_RESPONSE_OPTIONS');
+
+class NgQubeeService {
+    _nestService;
     /**
-     * Parse a JSON:API pagination response into a PaginatedCollection
-     *
-     * 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 response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
+     * The active pagination driver
      */
-    // 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);
-    }
+    _driver;
     /**
-     * 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
+     * Resolved query parameter key name options
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _resolve(response, path) {
-        return path.split('.').reduce((obj, key) => obj?.[key], response);
-    }
+    _options;
     /**
-     * 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
+     * The request strategy that builds URIs for the active driver
      */
-    // 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;
+    _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;
     }
     /**
-     * Resolve the "to" index value
+     * Assert that the active strategy declares support for a capability
      *
-     * 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)`
+     * Reads from `IRequestStrategy.capabilities` rather than the driver
+     * enum so adding a new driver only requires declaring its capability
+     * map — this method does not change.
      *
-     * @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
+     * @param flag - The capability key to check
+     * @param error - The error to throw if the capability is unsupported
+     * @throws The provided error if the active strategy lacks the capability
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _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);
+    _assertCapability(flag, error) {
+        if (!this._requestStrategy.capabilities[flag]) {
+            throw error;
         }
-        return undefined;
     }
-}
-
-/**
- * Request strategy for the Laravel (pagination-only) driver
- *
- * Generates simple pagination URIs:
- * - `/{resource}?limit=N&page=N`
- *
- * Filters, sorts, fields, includes, search, and select in state are ignored.
- */
-class LaravelRequestStrategy {
     /**
-     * Build a pagination-only URI from the given state
+     * Add fields to the select statement for the given model (JSON:API and Spatie only)
      *
-     * @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
+     * @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
      */
-    buildUri(state, options) {
-        if (!state.resource) {
-            throw new Error('Set the resource property BEFORE calling the url() / get() methods');
+    addFields(model, fields) {
+        this._assertCapability('fields', new UnsupportedFieldSelectionError());
+        if (!fields.length) {
+            return this;
         }
-        const base = state.baseUrl ? `${state.baseUrl}/${state.resource}` : `/${state.resource}`;
-        return `${base}?${options.limit}=${state.limit}&${options.page}=${state.page}`;
+        this._nestService.addFields({ [model]: fields });
+        return this;
     }
     /**
-     * Validate that the given limit is accepted by the Laravel driver
+     * Add a filter with the given value(s) (JSON:API, NestJS, PostgREST, and Spatie)
      *
-     * Laravel pagination does not recognize `-1` as a "fetch all" sentinel,
-     * so only positive integers are accepted.
+     * Produces: `filter[field]=value` (JSON:API / Spatie) or `filter.field=value` (NestJS)
      *
-     * @param limit - The limit value to validate
-     * @throws {InvalidLimitError} If the value is not a positive integer
+     * @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
      */
-    validateLimit(limit) {
-        if (Number.isInteger(limit) && limit >= 1) {
-            return;
+    addFilter(field, ...values) {
+        this._assertCapability('filters', new UnsupportedFilterError());
+        if (!values.length) {
+            return this;
         }
-        throw new InvalidLimitError(limit);
+        this._nestService.addFilters({
+            [field]: values
+        });
+        this._nestService.page = 1;
+        return this;
     }
-}
-
-/**
- * Response strategy for the Laravel (pagination-only) driver
- *
- * Parses flat Laravel pagination responses:
- * ```json
- * {
- *   "data": [...],
- *   "current_page": 1,
- *   "total": 100,
- *   "per_page": 15,
- *   "from": 1,
- *   "to": 15,
- *   ...
- * }
- * ```
- */
-class LaravelResponseStrategy {
     /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
+     * Add a filter with an explicit operator (NestJS and PostgREST)
      *
-     * @param response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    paginate(response, options) {
-        return new PaginatedCollection(response[options.data], response[options.currentPage], response[options.from], response[options.to], response[options.total], response[options.perPage], response[options.prevPageUrl], response[options.nextPageUrl], response[options.lastPage], response[options.firstPageUrl], response[options.lastPageUrl]);
-    }
-}
-
-/**
- * Request strategy for the NestJS (nestjs-paginate) driver
- *
- * Generates URIs in the NestJS paginate format:
- * - Simple filters: `filter.field=value`
- * - Operator filters: `filter.field=$operator:value`
- * - Sorts: `sortBy=field1:DESC,field2:ASC`
- * - Select: `select=col1,col2`
- * - Search: `search=term`
- * - Pagination: `limit=N&page=N`
- *
- * @see https://github.com/ppetzold/nestjs-paginate
- */
-class NestjsRequestStrategy {
-    /**
-     * Accumulator for composing the URI string
-     */
-    _uri = '';
-    /**
-     * Build a URI string from the given state using the NestJS paginate format
+     * Produces: `filter.field=$operator:value`
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The composed URI string
-     * @throws Error if model is not set
+     * @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
      */
-    buildUri(state, options) {
-        if (!state.resource) {
-            throw new Error('Set the resource property BEFORE adding filters or calling the url() / get() methods');
+    addFilterOperator(field, operator, ...values) {
+        this._assertCapability('operatorFilters', new UnsupportedFilterOperatorError());
+        if (!values.length) {
+            return this;
         }
-        this._uri = '';
-        this._parseFilters(state, options);
-        this._parseOperatorFilters(state, options);
-        this._parseSort(state, options);
-        this._parseSelect(state, options);
-        this._parseSearch(state, options);
-        this._parseLimit(state, options);
-        this._parsePage(state, options);
-        return this._uri;
+        this._nestService.addOperatorFilters([{ field, operator, values }]);
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * 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`).
+     * Add related entities to include in the request (JSON:API and Spatie only)
      *
-     * @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
+     * @param {string[]} models - Models to include
+     * @returns {this}
+     * @throws {UnsupportedIncludesError} If the active driver does not support includes
      */
-    validateLimit(limit) {
-        if (Number.isInteger(limit) && (limit === -1 || limit >= 1)) {
-            return;
+    addIncludes(...models) {
+        this._assertCapability('includes', new UnsupportedIncludesError());
+        if (!models.length) {
+            return this;
         }
-        throw new InvalidLimitError(limit, true);
+        this._nestService.addIncludes(models);
+        return this;
     }
     /**
-     * Parse and append simple filter parameters
+     * Add flat field selection (NestJS and PostgREST)
      *
-     * Generates: `filter.field=value1,value2` for each filter
+     * Produces: `select=col1,col2`
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @param {string[]} fields - Fields to select
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
      */
-    _parseFilters(state, options) {
-        const keys = Object.keys(state.filters);
-        if (!keys.length) {
-            return;
+    addSelect(...fields) {
+        this._assertCapability('select', new UnsupportedSelectError());
+        if (!fields.length) {
+            return this;
         }
-        keys.forEach(key => {
-            const values = state.filters[key].join(',');
-            const param = `${this._prepend(state)}${options.filters}.${key}=${values}`;
-            this._uri += param;
-        });
+        this._nestService.addSelect(fields);
+        return this;
     }
     /**
-     * Parse and append the limit parameter
+     * Add a field with a sort criteria (JSON:API, NestJS, PostgREST, and Spatie)
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @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
      */
-    _parseLimit(state, options) {
-        const param = `${this._prepend(state)}${options.limit}=${state.limit}`;
-        this._uri += param;
+    addSort(field, order) {
+        this._assertCapability('sort', new UnsupportedSortError());
+        this._nestService.addSort({
+            field,
+            order
+        });
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * Parse and append operator filter parameters
+     * Get the current page number
      *
-     * Groups operator filters by field and generates:
-     * - Single value: `filter.field=$operator:value`
-     * - Multiple values ($in, $btw): `filter.field=$operator:val1,val2`
-     *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @remarks Always safe to call. Thin accessor over the internal state's `page` field.
+     * @returns The current page number
      */
-    _parseOperatorFilters(state, options) {
-        if (!state.operatorFilters.length) {
-            return;
-        }
-        state.operatorFilters.forEach((opFilter) => {
-            const values = opFilter.values.join(',');
-            const param = `${this._prepend(state)}${options.filters}.${opFilter.field}=${opFilter.operator}:${values}`;
-            this._uri += param;
-        });
+    currentPage() {
+        return this._nestService.nest().page;
     }
     /**
-     * Parse and append the page parameter
+     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * ```
+     * 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
      */
-    _parsePage(state, options) {
-        const param = `${this._prepend(state)}${options.page}=${state.page}`;
-        this._uri += param;
+    deleteFields(fields) {
+        this._assertCapability('fields', new UnsupportedFieldSelectionError());
+        this._nestService.deleteFields(fields);
+        return this;
     }
     /**
-     * Parse and append the search parameter
+     * Delete selected fields for the given model in the current query builder state (JSON:API and Spatie only)
      *
-     * Generates: `search=term`
+     * ```
+     * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
+     * ```
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @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
      */
-    _parseSearch(state, options) {
-        if (!state.search) {
-            return;
+    deleteFieldsByModel(model, ...fields) {
+        this._assertCapability('fields', new UnsupportedFieldSelectionError());
+        if (!fields.length) {
+            return this;
         }
-        const param = `${this._prepend(state)}${options.search}=${state.search}`;
-        this._uri += param;
+        this._nestService.deleteFields({
+            [model]: fields
+        });
+        return this;
     }
     /**
-     * Parse and append the select parameter
+     * Remove given filters from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)
      *
-     * Generates: `select=col1,col2`
-     *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @param {string[]} filters - Filters to remove
+     * @returns {this}
+     * @throws {UnsupportedFilterError} If the active driver does not support filters
      */
-    _parseSelect(state, options) {
-        if (!state.select.length) {
-            return;
+    deleteFilters(...filters) {
+        this._assertCapability('filters', new UnsupportedFilterError());
+        if (!filters.length) {
+            return this;
         }
-        const param = `${this._prepend(state)}${options.select}=${state.select.join(',')}`;
-        this._uri += param;
+        this._nestService.deleteFilters(...filters);
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * Parse and append sort parameters
-     *
-     * Generates: `sortBy=field1:DESC,field2:ASC`
+     * Remove selected related models from the query builder state (JSON:API and Spatie only)
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
+     * @param {string[]} includes - Models to remove
+     * @returns {this}
+     * @throws {UnsupportedIncludesError} If the active driver does not support includes
      */
-    _parseSort(state, options) {
-        if (!state.sorts.length) {
-            return;
+    deleteIncludes(...includes) {
+        this._assertCapability('includes', new UnsupportedIncludesError());
+        if (!includes.length) {
+            return this;
         }
-        const sortPairs = state.sorts.map(sort => `${sort.field}:${sort.order === SortEnum.DESC ? 'DESC' : 'ASC'}`);
-        const param = `${this._prepend(state)}${options.sortBy}=${sortPairs.join(',')}`;
-        this._uri += param;
+        this._nestService.deleteIncludes(...includes);
+        return this;
     }
     /**
-     * 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.
+     * Remove operator filters by field name (NestJS and PostgREST)
      *
-     * @param state - The current query builder state
-     * @returns The prefix string to prepend to the next parameter
+     * @param {string[]} fields - Field names of operator filters to remove
+     * @returns {this}
+     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
      */
-    _prepend(state) {
-        if (this._uri) {
-            return '&';
+    deleteOperatorFilters(...fields) {
+        this._assertCapability('operatorFilters', new UnsupportedFilterOperatorError());
+        if (!fields.length) {
+            return this;
         }
-        return state.baseUrl ? `${state.baseUrl}/${state.resource}?` : `/${state.resource}?`;
+        this._nestService.deleteOperatorFilters(...fields);
+        this._nestService.page = 1;
+        return this;
     }
-}
-
-/**
- * Response strategy for the NestJS (nestjs-paginate) driver
- *
- * Parses nested NestJS pagination responses:
- * ```json
- * {
- *   "data": [...],
- *   "meta": {
- *     "currentPage": 1,
- *     "totalItems": 100,
- *     "itemsPerPage": 10,
- *     "totalPages": 10
- *   },
- *   "links": {
- *     "first": "url",
- *     "previous": "url",
- *     "next": "url",
- *     "last": "url",
- *     "current": "url"
- *   }
- * }
- * ```
- *
- * @see https://github.com/ppetzold/nestjs-paginate
- */
-class NestjsResponseStrategy {
     /**
-     * Parse a nested NestJS pagination response into a PaginatedCollection
-     *
-     * Supports dot-notation key paths for accessing nested values.
-     * Computes `from` and `to` from `currentPage` and `itemsPerPage` when
-     * they are not directly available in the response.
+     * Remove search term from the query builder state (NestJS only)
      *
-     * @param response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
+     * @returns {this}
+     * @throws {UnsupportedSearchError} If the active driver does not support search
      */
-    // 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);
+    deleteSearch() {
+        this._assertCapability('search', new UnsupportedSearchError());
+        this._nestService.deleteSearch();
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * Resolve a value from a response object using a dot-notation path
-     *
-     * Supports both flat keys ('data') and nested paths ('meta.currentPage').
+     * Remove flat field selections from the query builder state (NestJS and PostgREST)
      *
-     * @param response - The raw response object
-     * @param path - The dot-notation path to resolve
-     * @returns The resolved value, or undefined if not found
+     * @param {string[]} fields - Fields to remove from selection
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _resolve(response, path) {
-        return path.split('.').reduce((obj, key) => obj?.[key], response);
+    deleteSelect(...fields) {
+        this._assertCapability('select', new UnsupportedSelectError());
+        if (!fields.length) {
+            return this;
+        }
+        this._nestService.deleteSelect(...fields);
+        return this;
     }
     /**
-     * Resolve the "from" index value
+     * Remove sort rules from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)
      *
-     * 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
+     * @param sorts - Fields used for sorting to remove
+     * @returns {this}
+     * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
-    // 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;
+    deleteSorts(...sorts) {
+        this._assertCapability('sort', new UnsupportedSortError());
+        this._nestService.deleteSorts(...sorts);
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * Resolve the "to" index value
+     * Navigate to the first page (page 1)
      *
-     * 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)`
+     * @remarks Never throws. Idempotent when already on page 1.
+     * @returns {this}
+     */
+    firstPage() {
+        this._nestService.page = 1;
+        return this;
+    }
+    /**
+     * Generate a URI accordingly to the given data and 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
-     * @param total - The total number of items
-     * @returns The computed "to" index
+     * @returns {Observable<string>} An observable that emits the generated URI
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _resolveTo(response, options, currentPage, perPage, total) {
-        const direct = this._resolve(response, options.to);
-        if (direct !== undefined) {
-            return direct;
+    generateUri() {
+        try {
+            this._uri$.next(this._requestStrategy.buildUri(this._nestService.nest(), this._options));
+            return this.uri$;
         }
-        if (currentPage && perPage && total) {
-            return Math.min(currentPage * perPage, total);
+        catch (error) {
+            return throwError(() => error);
         }
-        return undefined;
     }
-}
-
-/**
- * Request strategy for the Spatie Query Builder driver
- *
- * Generates URIs in the Spatie format:
- * - Fields: `fields[model]=col1,col2`
- * - Filters: `filter[field]=value`
- * - Includes: `include=model1,model2`
- * - Sorts: `sort=-field1,field2` (- prefix = DESC)
- * - Pagination: `limit=N&page=N`
- *
- * @see https://spatie.be/docs/laravel-query-builder
- */
-class SpatieRequestStrategy {
     /**
-     * Accumulator for composing the URI string
+     * 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
      */
-    _uri = '';
+    goToPage(n) {
+        const state = this._nestService.nest();
+        if (state.isLastPageKnown && n > state.lastPage) {
+            throw new InvalidPageNumberError(n);
+        }
+        this._nestService.page = n;
+        return this;
+    }
     /**
-     * Build a URI string from the given state using the Spatie format
+     * Check whether a next page exists
      *
-     * @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
+     * @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
      */
-    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._parseLimit(state, options);
-        this._parsePage(state, options);
-        this._parseSort(state, options);
-        return this._uri;
+    hasNextPage() {
+        const state = this._nestService.nest();
+        return !state.isLastPageKnown || state.page < state.lastPage;
     }
     /**
-     * Validate that the given limit is accepted by the Spatie driver
+     * Check whether a previous page exists
      *
-     * Spatie query-builder does not recognize `-1` as a "fetch all" sentinel,
-     * so only positive integers are accepted.
+     * @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
      *
-     * @param limit - The limit value to validate
-     * @throws {InvalidLimitError} If the value is not a positive integer
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page === 1`
      */
-    validateLimit(limit) {
-        if (Number.isInteger(limit) && limit >= 1) {
-            return;
-        }
-        throw new InvalidLimitError(limit);
+    isFirstPage() {
+        return this._nestService.nest().page === 1;
     }
     /**
-     * Parse and append field selection parameters
+     * Check whether the current page is the last page
      *
-     * Validates that each field model exists either as the main resource
-     * or in the includes list. Fields are grouped by model in bracket notation.
+     * @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
      *
-     * @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
+     * @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)
      */
-    _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');
+    lastPage() {
+        const state = this._nestService.nest();
+        if (!state.isLastPageKnown) {
+            throw new PaginationNotSyncedError('navigate to last page');
         }
-        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(',') });
-            }
+        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;
         }
-        const param = `${this._prepend(state)}${qs.stringify(f, { encode: false })}`;
-        this._uri += param;
-        return param;
+        this._nestService.page = state.page + 1;
+        return this;
     }
     /**
-     * Parse and append filter parameters
+     * HTTP request headers the active driver wants the consumer to apply
      *
-     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     * Returns `null` for drivers that pass all pagination metadata on the
+     * URL (Laravel, Spatie, JSON:API, NestJS, and PostgREST in its default
+     * QUERY mode). Returns a map of header name → value when the active
+     * driver uses HTTP headers instead — today, only the PostgREST driver
+     * configured with `PaginationModeEnum.RANGE`, which yields
+     * `{ 'Range-Unit': 'items', 'Range': 'from-to' }`.
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated filter parameter string
+     * @returns Map of headers to apply to the HTTP request, or `null` when not needed
      */
-    _parseFilters(state, options) {
-        const keys = Object.keys(state.filters);
-        if (!keys.length) {
-            return this._uri;
+    paginationHeaders() {
+        if (typeof this._requestStrategy.buildPaginationHeaders !== 'function') {
+            return null;
         }
-        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;
+        return this._requestStrategy.buildPaginationHeaders(this._nestService.nest());
     }
     /**
-     * Parse and append include parameters
+     * Navigate to the previous page
      *
-     * Generates: `include=model1,model2`
-     *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated include parameter string
+     * @remarks Never throws. Idempotent at page 1 (floored). Pair with `hasPreviousPage()` for a disable-state binding.
+     * @returns {this}
      */
-    _parseIncludes(state, options) {
-        if (!state.includes.length) {
-            return this._uri;
+    previousPage() {
+        const state = this._nestService.nest();
+        if (state.page <= 1) {
+            return this;
         }
-        const param = `${this._prepend(state)}${options.includes}=${state.includes}`;
-        this._uri += param;
-        return param;
+        this._nestService.page = state.page - 1;
+        return this;
     }
     /**
-     * Parse and append the limit parameter
+     * Clear the current state and reset the Query Builder to a fresh, clean condition
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated limit parameter string
+     * @returns {this}
      */
-    _parseLimit(state, options) {
-        const param = `${this._prepend(state)}${options.limit}=${state.limit}`;
-        this._uri += param;
-        return param;
+    reset() {
+        this._nestService.reset();
+        return this;
     }
     /**
-     * Parse and append the page parameter
+     * Set the base URL to use for composing the address
      *
-     * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated page parameter string
+     * @param {string} baseUrl - The base URL
+     * @returns {this}
      */
-    _parsePage(state, options) {
-        const param = `${this._prepend(state)}${options.page}=${state.page}`;
-        this._uri += param;
-        return param;
+    setBaseUrl(baseUrl) {
+        this._nestService.baseUrl = baseUrl;
+        return this;
     }
     /**
-     * Parse and append sort parameters
+     * Set the items per page number
      *
-     * Generates: `sort=-field1,field2` where `-` prefix indicates DESC order
+     * 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 state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated sort parameter string
+     * @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
      */
-    _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;
+    setLimit(limit) {
+        this._requestStrategy.validateLimit(limit);
+        this._nestService.limit = limit;
+        this._nestService.page = 1;
+        return this;
     }
     /**
-     * Determine the appropriate URI prefix based on the current accumulator state
+     * Set the page that the backend will use to paginate the result set
      *
-     * Returns the full base path with `?` for the first parameter,
-     * or `&` for subsequent parameters.
+     * @param page - Page number
+     * @returns {this}
+     */
+    setPage(page) {
+        this._nestService.page = page;
+        return this;
+    }
+    /**
+     * Set the API resource to run the query against
      *
-     * @param state - The current query builder state
-     * @returns The prefix string to prepend to the next parameter
+     * @param {string} resource - Resource name (e.g. 'users' produces /users)
+     * @returns {this}
      */
-    _prepend(state) {
-        if (this._uri) {
-            return '&';
-        }
-        return state.baseUrl ? `${state.baseUrl}/${state.resource}?` : `/${state.resource}?`;
+    setResource(resource) {
+        this._nestService.resource = resource;
+        this._nestService.page = 1;
+        return this;
     }
-}
-
-/**
- * Response strategy for the Spatie Query Builder driver
- *
- * Parses flat Laravel pagination responses:
- * ```json
- * {
- *   "data": [...],
- *   "current_page": 1,
- *   "total": 100,
- *   "per_page": 15,
- *   "from": 1,
- *   "to": 15,
- *   ...
- * }
- * ```
- *
- * @see https://spatie.be/docs/laravel-query-builder
- */
-class SpatieResponseStrategy {
     /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
+     * Set the search term for full-text search (NestJS only)
      *
-     * @param response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
+     * Produces: `search=term`
+     *
+     * @param {string} search - The search term
+     * @returns {this}
+     * @throws {UnsupportedSearchError} If the active driver does not support search
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    paginate(response, options) {
-        return new PaginatedCollection(response[options.data], response[options.currentPage], response[options.from], response[options.to], response[options.total], response[options.perPage], response[options.prevPageUrl], response[options.nextPageUrl], response[options.lastPage], response[options.firstPageUrl], response[options.lastPageUrl]);
+    setSearch(search) {
+        this._assertCapability('search', new UnsupportedSearchError());
+        this._nestService.setSearch(search);
+        this._nestService.page = 1;
+        return this;
     }
-}
-
-/**
- * Resolve the request strategy instance for the given driver
- *
- * @param driver - The pagination driver
- * @returns The corresponding request strategy
- */
-function resolveRequestStrategy$1(driver) {
-    switch (driver) {
-        case DriverEnum.JSON_API:
-            return new JsonApiRequestStrategy();
-        case DriverEnum.NESTJS:
-            return new NestjsRequestStrategy();
-        case DriverEnum.SPATIE:
-            return new SpatieRequestStrategy();
-        case DriverEnum.LARAVEL:
-            return new LaravelRequestStrategy();
+    /**
+     * 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 });
 }
-/**
- * Resolve the response strategy instance for the given driver
- *
- * @param driver - The pagination driver
- * @returns The corresponding response strategy
- */
-function resolveResponseStrategy$1(driver) {
-    switch (driver) {
-        case DriverEnum.JSON_API:
-            return new JsonApiResponseStrategy();
-        case DriverEnum.NESTJS:
-            return new NestjsResponseStrategy();
-        case DriverEnum.SPATIE:
-            return new SpatieResponseStrategy();
-        case DriverEnum.LARAVEL:
-            return new LaravelResponseStrategy();
+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;
     }
-}
-// @dynamic
-class NgQubeeModule {
     /**
-     * Configure NgQubee for the root module
+     * Transform a raw API response into a typed PaginatedCollection
      *
-     * @param config - Configuration object with driver, and optional request and response settings
-     * @returns Module with providers configured for the specified driver
+     * 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 body. For drivers that emit a
+     * bare array (PostgREST), pass the array.
+     * @param headers - Optional HTTP response headers. Required by the
+     * PostgREST driver (reads `Content-Range` for pagination metadata);
+     * body-only drivers ignore it. Accepts Angular's `HttpHeaders`, the
+     * native `Headers` class, or a plain `Record<string, string>`.
+     * @returns A typed PaginatedCollection instance
      */
-    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);
-                        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);
-                    }
-                }
-            ]
-        };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response, headers) {
+        const collection = this._responseStrategy.paginate(response, this._options, headers);
+        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: 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 });
+    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: NgQubeeModule, decorators: [{
-            type: NgModule,
-            args: [{}]
-        }] });
+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]
+                }] }] });
 
 /**
- * Resolve the request 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 request strategy
- */
-function resolveRequestStrategy(driver) {
-    switch (driver) {
-        case DriverEnum.JSON_API:
-            return new JsonApiRequestStrategy();
-        case DriverEnum.NESTJS:
-            return new NestjsRequestStrategy();
-        case DriverEnum.SPATIE:
-            return new SpatieRequestStrategy();
-        case DriverEnum.LARAVEL:
-            return new LaravelRequestStrategy();
-    }
-}
-/**
- * Resolve the response strategy instance for the given driver
+ * Looks up the driver definition from the registry and calls its three
+ * factories — request strategy, response strategy, response options.
+ * Adding a driver means adding one entry to `DRIVERS`; this function
+ * does not change.
  *
- * @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.JSON_API:
-            return new JsonApiResponseStrategy();
-        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 paginationMode = config.pagination ?? PaginationModeEnum.QUERY;
+    const definition = DRIVERS[driver];
+    const requestOptions = new QueryBuilderOptions(Object.assign({}, config.request));
+    const responseOptions = definition.createResponseOptions(Object.assign({}, config.response));
+    return [
+        { provide: NG_QUBEE_DRIVER, useValue: driver },
+        { provide: NG_QUBEE_REQUEST_STRATEGY, useValue: definition.createRequestStrategy(paginationMode) },
+        { provide: NG_QUBEE_REQUEST_OPTIONS, useValue: requestOptions },
+        { provide: NG_QUBEE_RESPONSE_STRATEGY, useValue: definition.createResponseStrategy() },
+        { provide: NG_QUBEE_RESPONSE_OPTIONS, useValue: responseOptions },
+        NestService,
+        NgQubeeService,
+        PaginationService
+    ];
 }
 /**
  * Sets up providers necessary to enable `NgQubee` functionality for the application.
@@ -2187,57 +2784,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);
-                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);
-            }
-        }
-    ]);
+    return makeEnvironmentProviders(buildNgQubeeProviders(config));
 }
-
 /**
- * Enum representing the available filter operators for the NestJS driver
+ * Providers for a component-scoped NgQubee instance
  *
- * These operators map to the nestjs-paginate filter syntax:
- * `filter.field=$operator:value`
+ * 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()`.
  *
- * @see https://github.com/ppetzold/nestjs-paginate
+ * @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`
  */
-var FilterOperatorEnum;
-(function (FilterOperatorEnum) {
-    FilterOperatorEnum["BTW"] = "$btw";
-    FilterOperatorEnum["CONTAINS"] = "$contains";
-    FilterOperatorEnum["EQ"] = "$eq";
-    FilterOperatorEnum["GT"] = "$gt";
-    FilterOperatorEnum["GTE"] = "$gte";
-    FilterOperatorEnum["ILIKE"] = "$ilike";
-    FilterOperatorEnum["IN"] = "$in";
-    FilterOperatorEnum["LT"] = "$lt";
-    FilterOperatorEnum["LTE"] = "$lte";
-    FilterOperatorEnum["NOT"] = "$not";
-    FilterOperatorEnum["NULL"] = "$null";
-    FilterOperatorEnum["SW"] = "$sw";
-})(FilterOperatorEnum || (FilterOperatorEnum = {}));
+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: [{}]
+        }] });
 
 /*
  * Public API Surface of angular-query-builder
@@ -2247,5 +2848,5 @@ var FilterOperatorEnum;
  * Generated bundle index. Do not edit.
  */
 
-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 };
+export { DriverEnum, FilterOperatorEnum, InvalidFilterOperatorValueError, 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, PaginationModeEnum, PaginationNotSyncedError, PaginationService, PostgrestRequestStrategy, PostgrestResponseStrategy, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, buildNgQubeeProviders, provideNgQubee, provideNgQubeeInstance, readHeader };
 //# sourceMappingURL=ng-qubee.mjs.map