ng-qubee 3.1.0 → 3.3.0

package/types/ng-qubee.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { ModuleWithProviders, EnvironmentProviders, Signal } from '@angular/core';
+import { ModuleWithProviders, Provider, EnvironmentProviders, Signal, InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 
 interface INormalized {
@@ -49,9 +49,27 @@ declare enum DriverEnum {
     JSON_API = "json-api",
     LARAVEL = "laravel",
     NESTJS = "nestjs",
+    POSTGREST = "postgrest",
     SPATIE = "spatie"
 }
 
+/**
+ * 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.
+ */
+declare enum PaginationModeEnum {
+    QUERY = "query",
+    RANGE = "range"
+}
+
 /**
  * Configuration interface for customizing response field key names
  *
@@ -135,6 +153,12 @@ interface IQueryBuilderConfig {
 interface IConfig {
     /** The pagination driver to use */
     driver: DriverEnum;
+    /**
+     * Wire-level pagination mechanism. Defaults to `PaginationModeEnum.QUERY`
+     * when omitted. Currently honoured only by the PostgREST driver; other
+     * drivers ignore it.
+     */
+    pagination?: PaginationModeEnum;
     /** Custom key names for request query parameters */
     request?: IQueryBuilderConfig;
     /** Custom key names for response field mapping */
@@ -154,6 +178,23 @@ declare class NgQubeeModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<NgQubeeModule>;
 }
 
+/**
+ * Build the core provider list shared by `provideNgQubee()` and
+ * `NgQubeeModule.forRoot()`
+ *
+ * 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.
+ *
+ * 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
+ */
+declare function buildNgQubeeProviders(config: IConfig): Provider[];
 /**
  * Sets up providers necessary to enable `NgQubee` functionality for the application.
  *
@@ -198,19 +239,57 @@ declare class NgQubeeModule {
  * @returns A set of providers to setup NgQubee
  */
 declare function provideNgQubee(config: IConfig): EnvironmentProviders;
+/**
+ * Providers for a component-scoped NgQubee instance
+ *
+ * Use this inside a standalone component's `providers: [...]` to get a
+ * dedicated `NgQubeeService` (and its `NestService` / `PaginationService`
+ * collaborators) whose query-builder and pagination state does not bleed
+ * with the app-wide shared instance provided by `provideNgQubee()`.
+ *
+ * @usageNotes
+ *
+ * ```
+ * @Component({
+ *   standalone: true,
+ *   providers: [...provideNgQubeeInstance()]
+ * })
+ * export class MyFeatureComponent {
+ *   constructor(private _qb: NgQubeeService) {}
+ * }
+ * ```
+ *
+ * The driver, strategies, and options are inherited from the environment
+ * injector (`provideNgQubee()` at root), so only the service instances are
+ * re-created at the component level.
+ *
+ * @publicApi
+ * @returns A provider array to spread into a component's `providers`
+ */
+declare function provideNgQubeeInstance(): Provider[];
 
 /**
- * Enum representing the available filter operators for the NestJS driver
+ * Enum representing the available filter operators for explicit operator
+ * filters
  *
- * These operators map to the nestjs-paginate filter syntax:
- * `filter.field=$operator:value`
+ * 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
  */
 declare enum FilterOperatorEnum {
     BTW = "$btw",
     CONTAINS = "$contains",
     EQ = "$eq",
+    FTS = "$fts",
     GT = "$gt",
     GTE = "$gte",
     ILIKE = "$ilike",
@@ -219,7 +298,10 @@ declare enum FilterOperatorEnum {
     LTE = "$lte",
     NOT = "$not",
     NULL = "$null",
-    SW = "$sw"
+    PHFTS = "$phfts",
+    PLFTS = "$plfts",
+    SW = "$sw",
+    WFTS = "$wfts"
 }
 
 declare enum SortEnum {
@@ -280,6 +362,10 @@ interface IQueryBuilderState {
     filters: IFilters;
     /** Related models to include (Spatie only) */
     includes: string[];
+    /** Whether the last paginated response has synced `lastPage` into state */
+    isLastPageKnown: boolean;
+    /** Last page number known from the most recent paginated response; only meaningful when `isLastPageKnown` is true */
+    lastPage: number;
     /** Number of items per page (all drivers) */
     limit: number;
     /** Filters with explicit operators (NestJS only) */
@@ -296,6 +382,33 @@ interface IQueryBuilderState {
     sorts: ISort[];
 }
 
+/**
+ * Capability flags declared by an `IRequestStrategy`
+ *
+ * Single source of truth for what a driver supports. Replaces the inline
+ * `DriverEnum` allowlists previously scattered across `NgQubeeService`'s
+ * `_assertDriver(...)` call sites.
+ *
+ * Adding a new driver means defining one of these objects on the new
+ * strategy class — `NgQubeeService` does not need to be touched.
+ */
+interface IStrategyCapabilities {
+    /** Per-model field selection (e.g. JSON:API `fields[type]=col1,col2`) */
+    readonly fields: boolean;
+    /** Simple key-value filters (e.g. `filter.status=active`) */
+    readonly filters: boolean;
+    /** Related-resource includes (e.g. JSON:API/Spatie `include=author`) */
+    readonly includes: boolean;
+    /** Filters with explicit operators (e.g. NestJS `$gte`, PostgREST `gte.`) */
+    readonly operatorFilters: boolean;
+    /** Global full-text search via a single term (NestJS `search=…`) */
+    readonly search: boolean;
+    /** Flat column-list selection (NestJS / PostgREST `select=col1,col2`) */
+    readonly select: boolean;
+    /** Sort ordering on one or more fields */
+    readonly sort: boolean;
+}
+
 /**
  * Resolved query parameter key names with defaults applied
  *
@@ -323,6 +436,14 @@ declare class QueryBuilderOptions {
  * in the format expected by the corresponding backend.
  */
 interface IRequestStrategy {
+    /**
+     * Capability flags declared by this driver
+     *
+     * Read by `NgQubeeService` to gate feature methods (e.g. `addFilter`)
+     * without hardcoding `DriverEnum` checks. Each strategy returns a
+     * static, immutable capability map.
+     */
+    readonly capabilities: IStrategyCapabilities;
     /**
      * Build a URI string from the given query builder state
      *
@@ -331,6 +452,23 @@ interface IRequestStrategy {
      * @returns The composed URI string
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Compute HTTP request headers carrying pagination metadata
+     *
+     * Honoured only by drivers that support header-based pagination (the
+     * PostgREST driver configured with `PaginationModeEnum.RANGE`). All
+     * other drivers should return `null` — which is also the default when
+     * a driver does not override this method.
+     *
+     * When the method returns a non-null object, `NgQubeeService.buildUri`
+     * is expected to have already omitted URL-level pagination params for
+     * that request; the consumer then merges these headers into the HTTP
+     * call so the server knows the requested range.
+     *
+     * @param state - The current query builder state
+     * @returns A map of header name → value, or `null` when not applicable
+     */
+    buildPaginationHeaders?(state: IQueryBuilderState): Record<string, string> | null;
     /**
      * Assert that the given limit value is valid for this driver
      *
@@ -560,6 +698,19 @@ declare class NestService {
      * service.setSearch('john doe');
      */
     setSearch(search: string): void;
+    /**
+     * 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: number): void;
     /**
      * Reset the query builder state to initial values
      * Clears all fields, filters, includes, sorts, and resets pagination
@@ -595,15 +746,19 @@ declare class NgQubeeService {
      * Observable that emits non-empty generated URIs
      */
     uri$: Observable<string>;
-    constructor(_nestService: NestService, requestStrategy: IRequestStrategy, driver: DriverEnum, options?: IQueryBuilderConfig);
+    constructor(_nestService: NestService, requestStrategy: IRequestStrategy, driver: DriverEnum, options?: QueryBuilderOptions);
     /**
-     * Assert that the active driver is one of the allowed drivers
+     * Assert that the active strategy declares support for a capability
+     *
+     * 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 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 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
      */
-    private _assertDriver;
+    private _assertCapability;
     /**
      * Add fields to the select statement for the given model (JSON:API and Spatie only)
      *
@@ -614,7 +769,7 @@ declare class NgQubeeService {
      */
     addFields(model: string, fields: string[]): this;
     /**
-     * Add a filter with the given value(s) (JSON:API, NestJS, and Spatie)
+     * Add a filter with the given value(s) (JSON:API, NestJS, PostgREST, and Spatie)
      *
      * Produces: `filter[field]=value` (JSON:API / Spatie) or `filter.field=value` (NestJS)
      *
@@ -625,7 +780,7 @@ declare class NgQubeeService {
      */
     addFilter(field: string, ...values: (string | number | boolean)[]): this;
     /**
-     * Add a filter with an explicit operator (NestJS only)
+     * Add a filter with an explicit operator (NestJS and PostgREST)
      *
      * Produces: `filter.field=$operator:value`
      *
@@ -645,7 +800,7 @@ declare class NgQubeeService {
      */
     addIncludes(...models: string[]): this;
     /**
-     * Add flat field selection (NestJS only)
+     * Add flat field selection (NestJS and PostgREST)
      *
      * Produces: `select=col1,col2`
      *
@@ -655,7 +810,7 @@ declare class NgQubeeService {
      */
     addSelect(...fields: string[]): this;
     /**
-     * Add a field with a sort criteria (JSON:API, NestJS, and Spatie)
+     * Add a field with a sort criteria (JSON:API, NestJS, PostgREST, and Spatie)
      *
      * @param field - Field to use for sorting
      * @param {SortEnum} order - A value from the SortEnum enumeration
@@ -663,6 +818,13 @@ declare class NgQubeeService {
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     addSort(field: string, order: SortEnum): this;
+    /**
+     * Get the current page number
+     *
+     * @remarks Always safe to call. Thin accessor over the internal state's `page` field.
+     * @returns The current page number
+     */
+    currentPage(): number;
     /**
      * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
@@ -692,7 +854,7 @@ declare class NgQubeeService {
      */
     deleteFieldsByModel(model: string, ...fields: string[]): this;
     /**
-     * Remove given filters from the query builder state (JSON:API, NestJS, and Spatie)
+     * Remove given filters from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)
      *
      * @param {string[]} filters - Filters to remove
      * @returns {this}
@@ -708,7 +870,7 @@ declare class NgQubeeService {
      */
     deleteIncludes(...includes: string[]): this;
     /**
-     * Remove operator filters by field name (NestJS only)
+     * Remove operator filters by field name (NestJS and PostgREST)
      *
      * @param {string[]} fields - Field names of operator filters to remove
      * @returns {this}
@@ -723,7 +885,7 @@ declare class NgQubeeService {
      */
     deleteSearch(): this;
     /**
-     * Remove flat field selections from the query builder state (NestJS only)
+     * Remove flat field selections from the query builder state (NestJS and PostgREST)
      *
      * @param {string[]} fields - Fields to remove from selection
      * @returns {this}
@@ -731,19 +893,101 @@ declare class NgQubeeService {
      */
     deleteSelect(...fields: string[]): this;
     /**
-     * Remove sort rules from the query builder state (JSON:API, NestJS, and Spatie)
+     * Remove sort rules from the query builder state (JSON:API, NestJS, PostgREST, and Spatie)
      *
      * @param sorts - Fields used for sorting to remove
      * @returns {this}
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     deleteSorts(...sorts: string[]): this;
+    /**
+     * Navigate to the first page (page 1)
+     *
+     * @remarks Never throws. Idempotent when already on page 1.
+     * @returns {this}
+     */
+    firstPage(): this;
     /**
      * Generate a URI accordingly to the given data and active driver
      *
      * @returns {Observable<string>} An observable that emits the generated URI
      */
     generateUri(): Observable<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
+     */
+    goToPage(n: number): this;
+    /**
+     * Check whether a next page exists
+     *
+     * @remarks Template-safe. Returns `true` when pagination bounds are unknown (conservative default — keeps a "Next" button enabled before the first `paginate()` call).
+     * @returns `true` if `state.page < state.lastPage` when bounds are known, or `true` when bounds are unknown
+     */
+    hasNextPage(): boolean;
+    /**
+     * Check whether a previous page exists
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page > 1`
+     */
+    hasPreviousPage(): boolean;
+    /**
+     * Check whether the current page is the first page
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page === 1`
+     */
+    isFirstPage(): boolean;
+    /**
+     * Check whether the current page is the last page
+     *
+     * @remarks Template-safe. Returns `false` when pagination bounds are unknown (no paginated response has been synced yet) — keeps "Next" navigation unblocked until the first `paginate()` call syncs.
+     * @returns `true` only when `state.isLastPageKnown` and `state.page === state.lastPage`
+     */
+    isLastPage(): boolean;
+    /**
+     * Navigate to the last page known from the most recent paginated response
+     *
+     * @remarks Requires at least one `PaginationService.paginate()` call to have synced `state.lastPage`. Before that, the bound is unknown and this method throws.
+     * @returns {this}
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    lastPage(): 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(): this;
+    /**
+     * HTTP request headers the active driver wants the consumer to apply
+     *
+     * 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' }`.
+     *
+     * @returns Map of headers to apply to the HTTP request, or `null` when not needed
+     */
+    paginationHeaders(): Record<string, string> | null;
+    /**
+     * Navigate to the previous page
+     *
+     * @remarks Never throws. Idempotent at page 1 (floored). Pair with `hasPreviousPage()` for a disable-state binding.
+     * @returns {this}
+     */
+    previousPage(): this;
     /**
      * Clear the current state and reset the Query Builder to a fresh, clean condition
      *
@@ -794,8 +1038,39 @@ declare class NgQubeeService {
      * @throws {UnsupportedSearchError} If the active driver does not support search
      */
     setSearch(search: string): this;
+    /**
+     * Get the total number of pages reported by the most recent paginated response
+     *
+     * @remarks Throws when called before any `paginate()` has synced a value. For a non-throwing read in a template, read `nest().isLastPageKnown` first as a guard.
+     * @returns The last page number
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    totalPages(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgQubeeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NgQubeeService>;
 }
 
+/**
+ * A minimal bag of HTTP response headers that a response strategy can read
+ * by name.
+ *
+ * Accepts anything that exposes a `.get(name): string | null` method
+ * (Angular's `HttpHeaders`, the DOM `Headers` class) or a plain object
+ * keyed by header name. Consumers should not need to convert between them.
+ */
+type HeaderBag = {
+    get(name: string): string | null;
+} | Record<string, string | null | undefined>;
+/**
+ * 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
+ */
+declare function readHeader(bag: HeaderBag | null | undefined, name: string): string | null;
+
 /**
  * Resolved response field key names with defaults applied
  *
@@ -836,14 +1111,25 @@ interface IResponseStrategy {
     /**
      * Parse a raw API response into a typed PaginatedCollection
      *
-     * @param response - The raw API response object
+     * @param response - The raw API response object (body). For drivers that
+     * emit a bare array body (e.g. PostgREST), pass the array here.
      * @param options - The response key name configuration
+     * @param headers - Optional HTTP response headers. Drivers that carry
+     * pagination metadata in headers (PostgREST's `Content-Range`) read from
+     * this bag; body-only drivers ignore it. Accepts anything with a `.get()`
+     * accessor (`HttpHeaders`, `Headers`) or a plain `Record<string, string>`.
      * @returns A typed PaginatedCollection instance
      */
-    paginate<T extends IPaginatedObject>(response: Record<string, unknown>, options: ResponseOptions): PaginatedCollection<T>;
+    paginate<T extends IPaginatedObject>(response: Record<string, unknown>, options: ResponseOptions, headers?: HeaderBag): PaginatedCollection<T>;
 }
 
 declare 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()`)
+     */
+    private _nestService;
     /**
      * Resolved response key name options
      */
@@ -852,18 +1138,56 @@ declare class PaginationService {
      * The response strategy that parses responses for the active driver
      */
     private _responseStrategy;
-    constructor(responseStrategy: IResponseStrategy, options?: IPaginationConfig);
+    constructor(nestService: NestService, responseStrategy: IResponseStrategy, options?: ResponseOptions);
     /**
      * Transform a raw API response into a typed PaginatedCollection
      *
-     * Delegates to the active driver's response strategy for parsing.
-     *
-     * @param response - The raw API response object
+     * 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
      */
     paginate<T extends IPaginatedObject>(response: {
         [key: string]: any;
-    }): PaginatedCollection<T>;
+    }, headers?: HeaderBag): PaginatedCollection<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PaginationService>;
+}
+
+/**
+ * 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.
+ */
+declare class InvalidFilterOperatorValueError extends Error {
+    /**
+     * @param operator - The operator that rejected the values
+     * @param reason - Short human-readable explanation of the constraint
+     */
+    constructor(operator: FilterOperatorEnum, reason: string);
 }
 
 /**
@@ -899,6 +1223,24 @@ declare class KeyNotFoundError extends Error {
     constructor(key: string);
 }
 
+/**
+ * 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.
+ */
+declare 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: string);
+}
+
 declare class UnselectableModelError extends Error {
     constructor(model: string);
 }
@@ -977,185 +1319,303 @@ interface IPage {
 }
 
 /**
- * Request strategy for the JSON:API driver
+ * Injection token for the active pagination 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)
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` from the
+ * user-supplied `IConfig.driver`. Services read it to gate driver-specific
+ * behavior (e.g. `NgQubeeService._assertDriver`).
+ */
+declare const NG_QUBEE_DRIVER: InjectionToken<DriverEnum>;
+/**
+ * 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.
+ */
+declare const NG_QUBEE_REQUEST_STRATEGY: InjectionToken<IRequestStrategy>;
+/**
+ * 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.
  */
-declare class JsonApiRequestStrategy implements IRequestStrategy {
+declare const NG_QUBEE_REQUEST_OPTIONS: InjectionToken<QueryBuilderOptions>;
+/**
+ * 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.
+ */
+declare const NG_QUBEE_RESPONSE_STRATEGY: InjectionToken<IResponseStrategy>;
+/**
+ * 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`.
+ */
+declare const NG_QUBEE_RESPONSE_OPTIONS: InjectionToken<ResponseOptions>;
+
+/**
+ * Base class for request strategies
+ *
+ * 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.
+ *
+ * Drivers that need a non-default `validateLimit` (e.g. NestJS, which
+ * accepts `-1` as a fetch-all sentinel) override that method directly.
+ */
+declare abstract class AbstractRequestStrategy implements IRequestStrategy {
     /**
-     * Accumulator for composing the URI string
+     * Capability declaration for this driver
+     *
+     * Concrete strategies must provide a static, immutable capability map
+     * so `NgQubeeService._assertCapability(...)` can read it.
      */
-    private _uri;
+    abstract readonly capabilities: IStrategyCapabilities;
     /**
-     * Build a URI string from the given state using the JSON:API format
+     * 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 resource is not set
+     * @throws Error if the resource is not set
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
     /**
-     * Validate that the given limit is accepted by the JSON:API driver
+     * Validate that a limit value is acceptable for this driver
      *
-     * The JSON:API specification leaves pagination semantics to the server and
-     * does not define a "fetch all" sentinel, so only positive integers are
-     * accepted.
+     * 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: number): void;
     /**
-     * Parse and append field selection parameters
+     * Per-driver query-string segments, in emission order
      *
-     * Validates that each field model exists either as the main resource
-     * or in the includes list. Fields are grouped by type in bracket notation.
+     * Each entry is one `key=value` (or `key=v1&key=v2` for compound
+     * params like PostgREST's `BTW`). Empty arrays are valid and produce
+     * a URI containing only the resource path.
      *
      * @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
+     * @returns Ordered list of query-string fragments
      */
-    private _parseFields;
+    protected abstract parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
     /**
-     * Parse and append filter parameters
+     * Throw if the resource is not set on the state
      *
-     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     * Centralises the message that was previously copy-pasted across four
+     * of the five concrete strategies.
      *
      * @param state - The current query builder state
-     * @param options - The query parameter key name configuration
-     * @returns The generated filter parameter string
+     * @throws Error if `state.resource` is empty
      */
-    private _parseFilters;
+    protected assertResource(state: IQueryBuilderState): void;
     /**
-     * Parse and append include parameters
+     * Compute the base path (no query string)
      *
-     * Generates: `include=author,comments.author`
+     * @param state - The current query builder state
+     * @returns The base URI without the query separator (e.g. `/users` or `https://api.example.com/users`)
+     */
+    protected baseUri(state: IQueryBuilderState): string;
+    /**
+     * 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
+     */
+    protected join(base: string, segments: string[]): string;
+}
+
+/**
+ * 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/
+ */
+declare class JsonApiRequestStrategy extends AbstractRequestStrategy {
+    /**
+     * Filters, sorts, includes, per-model fields — same shape as Spatie
+     * but with bracket-style pagination
+     */
+    readonly capabilities: IStrategyCapabilities;
+    /**
+     * 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 The generated include parameter string
+     * @returns Ordered query-string fragments
      */
-    private _parseIncludes;
+    protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
     /**
-     * Parse and append pagination parameters in JSON:API bracket notation
-     *
-     * Generates: `page[number]=1&page[size]=15`
+     * Append per-type field selection in bracket notation
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated pagination parameter string
+     * @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
      */
-    private _parsePagination;
+    private _appendFields;
     /**
-     * Parse and append sort parameters
+     * Append filter parameters in bracket notation: `filter[key]=value`
      *
-     * Generates: `sort=-field1,field2` where `-` prefix indicates DESC order
+     * @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
+     */
+    private _appendFilters;
+    /**
+     * Append include parameter as `include=author,comments.author`
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated sort parameter string
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _parseSort;
+    private _appendIncludes;
     /**
-     * Determine the appropriate URI prefix based on the current accumulator state
+     * Append JSON:API bracket pagination as `page[number]=1&page[size]=15`
+     *
+     * `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.
      *
-     * Returns the full base path with `?` for the first parameter,
-     * or `&` for subsequent parameters.
+     * @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
+     */
+    private _appendPagination;
+    /**
+     * Append sort parameter as `sort=-field1,field2` (`-` prefix = DESC)
      *
      * @param state - The current query builder state
-     * @returns The prefix string to prepend to the next parameter
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _prepend;
+    private _appendSort;
 }
 
 /**
- * Response strategy for the JSON:API driver
+ * Base class for response strategies whose pagination metadata lives at
+ * dot-notation paths inside the response body
  *
- * 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"
- *   }
- * }
- * ```
+ * 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`).
  *
- * @see https://jsonapi.org/format/
+ * 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.
  */
-declare class JsonApiResponseStrategy implements IResponseStrategy {
+declare abstract class AbstractDotPathResponseStrategy implements IResponseStrategy {
     /**
-     * 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.
+     * Parse a nested-envelope pagination response into a PaginatedCollection
      *
      * @param response - The raw API response object
-     * @param options - The response key name configuration
+     * @param options - The response key name configuration (dot-notation paths supported)
      * @returns A typed PaginatedCollection instance
      */
     paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
     /**
      * Resolve a value from a response object using a dot-notation path
      *
-     * Supports both flat keys ('data') and nested paths ('meta.current-page').
+     * 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 not found
+     * @returns The resolved value, or undefined if any segment is missing
      */
-    private _resolve;
+    protected resolve(response: Record<string, any>, path: string): unknown;
     /**
      * 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`
+     * If `options.from` resolves to a value in the response, use it.
+     * Otherwise compute `(currentPage - 1) * perPage + 1` when both are known.
      *
      * @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
+     * @returns The "from" index, or `undefined` when neither path nor inputs suffice
      */
-    private _resolveFrom;
+    protected resolveFrom(response: Record<string, any>, options: ResponseOptions, currentPage: number, perPage?: number): number | undefined;
     /**
      * Resolve the "to" index value
      *
-     * 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)`
+     * 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 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 The "to" index, or `undefined` when neither path nor inputs suffice
      */
-    private _resolveTo;
+    protected resolveTo(response: Record<string, any>, options: ResponseOptions, currentPage: number, perPage?: number, total?: number): number | 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/
+ */
+declare class JsonApiResponseStrategy extends AbstractDotPathResponseStrategy {
 }
 
 /**
@@ -1166,26 +1626,19 @@ declare class JsonApiResponseStrategy implements IResponseStrategy {
  *
  * Filters, sorts, fields, includes, search, and select in state are ignored.
  */
-declare class LaravelRequestStrategy implements IRequestStrategy {
+declare class LaravelRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Build a pagination-only URI from the given state
-     *
-     * @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
+     * Pagination-only driver — no filtering, sorting, or column selection
      */
-    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    readonly capabilities: IStrategyCapabilities;
     /**
-     * Validate that the given limit is accepted by the Laravel driver
-     *
-     * Laravel pagination does not recognize `-1` as a "fetch all" sentinel,
-     * so only positive integers are accepted.
+     * Emit only the pagination params; filters/sorts/etc. are ignored
      *
-     * @param limit - The limit value to validate
-     * @throws {InvalidLimitError} If the value is not a positive integer
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The two pagination query-string fragments
      */
-    validateLimit(limit: number): void;
+    protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
 }
 
 /**
@@ -1228,20 +1681,12 @@ declare class LaravelResponseStrategy implements IResponseStrategy {
  *
  * @see https://github.com/ppetzold/nestjs-paginate
  */
-declare class NestjsRequestStrategy implements IRequestStrategy {
+declare class NestjsRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Accumulator for composing the URI string
+     * Filters, operator filters, sorts, flat select, global search — no
+     * per-model fields, no includes
      */
-    private _uri;
-    /**
-     * Build a URI string from the given state using the NestJS paginate format
-     *
-     * @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
-     */
-    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    readonly capabilities: IStrategyCapabilities;
     /**
      * Validate that the given limit is accepted by nestjs-paginate
      *
@@ -1253,76 +1698,72 @@ declare class NestjsRequestStrategy implements IRequestStrategy {
      */
     validateLimit(limit: number): void;
     /**
-     * Parse and append simple filter parameters
-     *
-     * Generates: `filter.field=value1,value2` for each filter
+     * Emit NestJS-format query-string segments in canonical order:
+     * filters → operator filters → sortBy → select → search → limit → page
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
      */
-    private _parseFilters;
+    protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
     /**
-     * Parse and append the limit parameter
+     * Append simple filter parameters as `filter.field=value1,value2`
      *
      * @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
      */
-    private _parseLimit;
+    private _appendFilters;
     /**
-     * Parse and append operator filter parameters
-     *
-     * Groups operator filters by field and generates:
-     * - Single value: `filter.field=$operator:value`
-     * - Multiple values ($in, $btw): `filter.field=$operator:val1,val2`
+     * Append the limit parameter
      *
      * @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
      */
-    private _parseOperatorFilters;
+    private _appendLimit;
     /**
-     * Parse and append the page parameter
+     * Append operator-filter parameters as `filter.field=$op:value`
+     *
+     * Groups by field; multi-value operators ($in, $btw) join values with commas.
      *
      * @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
      */
-    private _parsePage;
+    private _appendOperatorFilters;
     /**
-     * Parse and append the search parameter
-     *
-     * Generates: `search=term`
+     * Append the page parameter
      *
      * @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
      */
-    private _parseSearch;
+    private _appendPage;
     /**
-     * Parse and append the select parameter
-     *
-     * Generates: `select=col1,col2`
+     * Append the search parameter as `search=term`
      *
      * @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
      */
-    private _parseSelect;
+    private _appendSearch;
     /**
-     * Parse and append sort parameters
-     *
-     * Generates: `sortBy=field1:DESC,field2:ASC`
+     * Append the select parameter as `select=col1,col2`
      *
      * @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
      */
-    private _parseSort;
+    private _appendSelect;
     /**
-     * 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.
+     * Append sort parameter as `sortBy=field1:DESC,field2:ASC`
      *
      * @param state - The current query builder state
-     * @returns The prefix string to prepend to the next parameter
+     * @param options - The query parameter key name configuration
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _prepend;
+    private _appendSort;
 }
 
 /**
@@ -1348,60 +1789,214 @@ declare class NestjsRequestStrategy implements IRequestStrategy {
  * }
  * ```
  *
+ * 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
  */
-declare class NestjsResponseStrategy implements IResponseStrategy {
+declare class NestjsResponseStrategy extends AbstractDotPathResponseStrategy {
+}
+
+/**
+ * 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
+ */
+declare class PostgrestRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Parse a nested NestJS pagination response into a PaginatedCollection
+     * 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)
+     */
+    readonly capabilities: IStrategyCapabilities;
+    private static readonly _offsetKey;
+    private static readonly _orderKey;
+    /**
+     * Active pagination mode
      *
-     * 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.
+     * QUERY (default) → URL emits limit/offset.
+     * RANGE → URL omits them; `buildPaginationHeaders()` returns the
+     * `Range-Unit` / `Range` HTTP headers instead.
+     */
+    private readonly _paginationMode;
+    /**
+     * @param paginationMode - Wire-level pagination mechanism. Defaults to
+     * `PaginationModeEnum.QUERY`; `provideNgQubee` wires this from
+     * `IConfig.pagination`.
+     */
+    constructor(paginationMode?: PaginationModeEnum);
+    /**
+     * Compute `Range-Unit` / `Range` HTTP headers for RANGE pagination mode
      *
-     * @param response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
+     * 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`
      */
-    paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
+    buildPaginationHeaders(state: IQueryBuilderState): Record<string, string> | null;
     /**
-     * Resolve a value from a response object using a dot-notation path
+     * 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)
      *
-     * Supports both flat keys ('data') and nested paths ('meta.currentPage').
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns Ordered query-string fragments
+     */
+    protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
+    /**
+     * Append filter parameters in PostgREST format
      *
-     * @param response - The raw response object
-     * @param path - The dot-notation path to resolve
-     * @returns The resolved value, or undefined if not found
+     * 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
      */
-    private _resolve;
+    private _appendFilters;
     /**
-     * Resolve the "from" index value
+     * Append the limit parameter
      *
-     * If the path resolves to a value in the response, use it.
-     * Otherwise, compute it from currentPage and perPage:
-     * `(currentPage - 1) * perPage + 1`
+     * @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
+     */
+    private _appendLimit;
+    /**
+     * Append the offset parameter, derived from state.page
      *
-     * @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
+     * 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
      */
-    private _resolveFrom;
+    private _appendOffset;
     /**
-     * Resolve the "to" index value
+     * Append explicit operator filters
      *
-     * 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)`
+     * 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 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 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
+     */
+    private _appendOperatorFilters;
+    /**
+     * Append a `BTW` operator filter as two PostgREST segments
+     *
+     * 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
+     */
+    private _appendBetweenFilter;
+    /**
+     * 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
+     */
+    private _formatOperatorRhs;
+    /**
+     * Append the order parameter as `order=col1.asc,col2.desc`
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _resolveTo;
+    private _appendOrder;
+    /**
+     * Append the select parameter as `select=col1,col2`
+     *
+     * 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
+     */
+    private _appendSelect;
+}
+
+/**
+ * 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
+ */
+declare class PostgrestResponseStrategy implements IResponseStrategy {
+    private static readonly _contentRangeHeader;
+    private static readonly _contentRangeRegex;
+    /**
+     * 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<T extends IPaginatedObject>(response: Record<string, unknown>, options: ResponseOptions, headers?: HeaderBag): PaginatedCollection<T>;
+    /**
+     * 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
+     */
+    private _parseContentRange;
 }
 
 /**
@@ -1416,99 +2011,74 @@ declare class NestjsResponseStrategy implements IResponseStrategy {
  *
  * @see https://spatie.be/docs/laravel-query-builder
  */
-declare class SpatieRequestStrategy implements IRequestStrategy {
+declare class SpatieRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Accumulator for composing the URI string
+     * Filters, sorts, includes, per-model fields — no operators, no flat
+     * select, no global search
      */
-    private _uri;
+    readonly capabilities: IStrategyCapabilities;
     /**
-     * Build a URI string from the given state using the Spatie format
+     * Emit Spatie-format query-string segments in canonical order:
+     * include → fields → filters → limit → page → sort
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The composed URI string
-     * @throws Error if resource is not set
-     */
-    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
-    /**
-     * Validate that the given limit is accepted by the Spatie driver
-     *
-     * Spatie query-builder does not recognize `-1` as a "fetch all" sentinel,
-     * so only positive integers are accepted.
-     *
-     * @param limit - The limit value to validate
-     * @throws {InvalidLimitError} If the value is not a positive integer
+     * @returns Ordered query-string fragments
      */
-    validateLimit(limit: number): void;
+    protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
     /**
-     * Parse and append field selection parameters
+     * Append per-model field selection in bracket notation
      *
      * Validates that each field model exists either as the main resource
-     * or in the includes list. Fields are grouped by model in bracket notation.
+     * or in the includes list.
      *
      * @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
+     * @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
      */
-    private _parseFields;
+    private _appendFields;
     /**
-     * Parse and append filter parameters
-     *
-     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     * Append filter parameters in bracket notation: `filter[key]=value`
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated filter parameter string
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _parseFilters;
+    private _appendFilters;
     /**
-     * Parse and append include parameters
-     *
-     * Generates: `include=model1,model2`
+     * Append include parameter as `include=model1,model2`
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated include parameter string
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _parseIncludes;
+    private _appendIncludes;
     /**
-     * Parse and append the limit parameter
+     * Append the limit parameter
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated limit parameter string
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _parseLimit;
+    private _appendLimit;
     /**
-     * Parse and append the page parameter
+     * Append the page parameter
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated page parameter string
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _parsePage;
+    private _appendPage;
     /**
-     * Parse and append sort parameters
-     *
-     * Generates: `sort=-field1,field2` where `-` prefix indicates DESC order
+     * Append sort parameter as `sort=-field1,field2` (`-` prefix = DESC)
      *
      * @param state - The current query builder state
      * @param options - The query parameter key name configuration
-     * @returns The generated sort parameter string
-     */
-    private _parseSort;
-    /**
-     * 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
+     * @param out - The accumulator the caller joins into the URI
      */
-    private _prepend;
+    private _appendSort;
 }
 
 /**
@@ -1540,5 +2110,5 @@ declare class SpatieResponseStrategy implements IResponseStrategy {
     paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
 }
 
-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 type { IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };
+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 };
+export type { HeaderBag, IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };