ng-qubee 3.4.0 → 3.5.0

package/fesm2022/ng-qubee.mjs

@@ -74,6 +74,7 @@ class PaginatedCollection {
  */
 var DriverEnum;
 (function (DriverEnum) {
+    DriverEnum["DRF"] = "drf";
     DriverEnum["JSON_API"] = "json-api";
     DriverEnum["LARAVEL"] = "laravel";
     DriverEnum["NESTJS"] = "nestjs";
@@ -124,6 +125,35 @@ class ResponseOptions {
         this.total = options.total || 'total';
     }
 }
+/**
+ * Pre-configured ResponseOptions for the Django REST Framework (DRF) driver
+ *
+ * DRF's `PageNumberPagination` envelope is `{ count, next, previous,
+ * results }`, with no body field naming the current page, per-page, or
+ * last-page. The strategy parses those from the `next` / `previous`
+ * URLs, so the corresponding key paths default to empty strings; the
+ * strategy ignores `options.currentPage`, `options.perPage`,
+ * `options.lastPage`, `options.from`, `options.to`, `options.path`,
+ * `options.firstPageUrl`, and `options.lastPageUrl`.
+ */
+class DrfResponseOptions extends ResponseOptions {
+    constructor(options) {
+        super({
+            currentPage: options.currentPage || '',
+            data: options.data || 'results',
+            firstPageUrl: options.firstPageUrl || '',
+            from: options.from || '',
+            lastPage: options.lastPage || '',
+            lastPageUrl: options.lastPageUrl || '',
+            nextPageUrl: options.nextPageUrl || 'next',
+            path: options.path || '',
+            perPage: options.perPage || '',
+            prevPageUrl: options.prevPageUrl || 'previous',
+            to: options.to || '',
+            total: options.total || 'count'
+        });
+    }
+}
 /**
  * Pre-configured ResponseOptions for the JSON:API driver
  *
@@ -199,15 +229,85 @@ class StrapiResponseOptions extends ResponseOptions {
     }
 }
 
+/**
+ * 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 = {}));
+
 var SortEnum;
 (function (SortEnum) {
     SortEnum["ASC"] = "asc";
     SortEnum["DESC"] = "desc";
 })(SortEnum || (SortEnum = {}));
 
-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.`);
+/**
+ * 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';
+    }
+}
+
+/**
+ * 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';
     }
 }
 
@@ -317,6 +417,428 @@ class AbstractRequestStrategy {
     }
 }
 
+/**
+ * Request strategy for the Django REST Framework (DRF) driver
+ *
+ * Generates URIs in DRF's flat query-parameter format, augmented by
+ * django-filter's double-underscore lookup convention:
+ *
+ * - Simple filters: `field=value` (multi-value collapses to `field__in=v1,v2`)
+ * - Operator filters: `field__lookup=value` (translated from
+ *   `FilterOperatorEnum` — `GTE`→`__gte`, `ILIKE`→`__icontains`,
+ *   `BTW`→`__range`, `NULL`→`__isnull`, etc.)
+ * - Ordering: `ordering=-field1,field2` (`-` prefix = DESC)
+ * - Search: `search=term` (DRF's SearchFilter)
+ * - Pagination: `page=N&page_size=M` (PageNumberPagination)
+ *
+ * `ordering` and `page_size` are DRF-idiomatic param names and are
+ * intentionally not configurable via `QueryBuilderOptions` — same
+ * precedent as PostgREST's `order` and `offset`. PostgREST's full-text
+ * search operators (`FTS`, `PHFTS`, `PLFTS`, `WFTS`) and the generic
+ * `NOT` have no django-filter equivalent and throw
+ * `UnsupportedFilterOperatorError`.
+ *
+ * @see https://www.django-rest-framework.org/api-guide/filtering/
+ * @see https://django-filter.readthedocs.io/
+ */
+class DrfRequestStrategy extends AbstractRequestStrategy {
+    /**
+     * Simple filters, operator filters (django-filter lookups), sorts, and
+     * global search — no per-model fields, no relation includes, no flat
+     * select (django-restql adds it but is not core DRF)
+     */
+    capabilities = {
+        fields: false,
+        filters: true,
+        includes: false,
+        operatorFilters: true,
+        search: true,
+        select: false,
+        sort: true
+    };
+    /**
+     * DRF-native names of the three hardcoded query keys
+     *
+     * `ordering` and `page_size` are DRF/django-filter conventions and are
+     * intentionally not configurable through `QueryBuilderOptions`. `page`
+     * matches the default `QueryBuilderOptions.page`, and `search` matches
+     * the default `QueryBuilderOptions.search`, so those flow through the
+     * shared options object.
+     */
+    static _orderingKey = 'ordering';
+    static _pageSizeKey = 'page_size';
+    /**
+     * Emit DRF-format query-string segments in canonical order:
+     * filters → operator filters → ordering → search → pagination
+     *
+     * @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._appendOrdering(state, out);
+        this._appendSearch(state, options, out);
+        this._appendPagination(state, options, out);
+        return out;
+    }
+    /**
+     * Append simple filter parameters
+     *
+     * Single-value filters emit `field=value` (django-filter's default
+     * exact match). Multi-value filters collapse to django-filter's
+     * `field__in=v1,v2,v3` form, which is the idiomatic way to express
+     * "value in list" in DRF.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _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;
+            }
+            if (values.length === 1) {
+                out.push(`${key}=${values[0]}`);
+                return;
+            }
+            out.push(`${key}__in=${values.join(',')}`);
+        });
+    }
+    /**
+     * Append operator-filter parameters as `field__lookup=value`
+     *
+     * Maps each `FilterOperatorEnum` value to a django-filter lookup
+     * suffix. `BTW` expands to `field__range=min,max`; `NULL` emits
+     * `field__isnull=true|false`; the generic `NOT` and PostgREST-only
+     * FTS operators are unsupported.
+     *
+     * @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 two values, or `NULL` does not receive exactly one boolean
+     * @throws {UnsupportedFilterOperatorError} If the operator has no
+     * django-filter equivalent
+     */
+    _appendOperatorFilters(state, out) {
+        if (!state.operatorFilters.length) {
+            return;
+        }
+        state.operatorFilters.forEach((filter) => {
+            const [suffix, value] = this._formatOperatorPayload(filter);
+            const key = suffix ? `${filter.field}__${suffix}` : filter.field;
+            out.push(`${key}=${value}`);
+        });
+    }
+    /**
+     * Append `ordering=-field1,field2` (django's `-` prefix = DESC)
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendOrdering(state, out) {
+        if (!state.sorts.length) {
+            return;
+        }
+        const pairs = state.sorts.map(sort => `${sort.order === SortEnum.DESC ? '-' : ''}${sort.field}`);
+        out.push(`${DrfRequestStrategy._orderingKey}=${pairs.join(',')}`);
+    }
+    /**
+     * Append `page=N&page_size=M`
+     *
+     * `page` follows `options.page` (default `page`, matching DRF); the
+     * size key is hardcoded to DRF's idiomatic `page_size`.
+     *
+     * @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
+     */
+    _appendPagination(state, options, out) {
+        out.push(`${options.page}=${state.page}`);
+        out.push(`${DrfRequestStrategy._pageSizeKey}=${state.limit}`);
+    }
+    /**
+     * Append `search=term` when a search term is set
+     *
+     * @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
+     */
+    _appendSearch(state, options, out) {
+        if (!state.search) {
+            return;
+        }
+        out.push(`${options.search}=${state.search}`);
+    }
+    /**
+     * Translate a `FilterOperatorEnum` operator filter into a
+     * `[suffix, serializedValue]` pair
+     *
+     * The suffix is appended to the field name with a `__` separator on the
+     * wire side (`field__gte=18`). The empty string means "no suffix" —
+     * django-filter's implicit `exact` lookup.
+     *
+     * Mapping:
+     * - `EQ` → `''` (no suffix; default exact match)
+     * - `GT`/`GTE`/`LT`/`LTE`/`CONTAINS` → identity (lowercased name)
+     * - `ILIKE` → `icontains` (closest case-insensitive analog)
+     * - `IN` → `in` with comma-joined values
+     * - `SW` → `startswith`
+     * - `BTW` → `range` with comma-joined `[min, max]` (arity-checked)
+     * - `NULL` → `isnull` with boolean value (arity- and type-checked)
+     * - `NOT` → `UnsupportedFilterOperatorError` (no generic negation in
+     *   django-filter; use `__exclude` on the queryset instead)
+     * - `FTS`/`PLFTS`/`PHFTS`/`WFTS` → `UnsupportedFilterOperatorError`
+     *
+     * @param filter - The operator filter to translate
+     * @returns A `[lookupSuffix, serializedValue]` tuple
+     * @throws {InvalidFilterOperatorValueError} If `BTW` does not receive
+     * exactly two values, or `NULL` does not receive exactly one boolean
+     * @throws {UnsupportedFilterOperatorError} If the operator has no
+     * django-filter equivalent
+     */
+    _formatOperatorPayload(filter) {
+        const { operator, values } = filter;
+        const first = values[0];
+        switch (operator) {
+            case FilterOperatorEnum.EQ: return ['', String(first)];
+            case FilterOperatorEnum.GT: return ['gt', String(first)];
+            case FilterOperatorEnum.GTE: return ['gte', String(first)];
+            case FilterOperatorEnum.LT: return ['lt', String(first)];
+            case FilterOperatorEnum.LTE: return ['lte', String(first)];
+            case FilterOperatorEnum.CONTAINS: return ['contains', String(first)];
+            case FilterOperatorEnum.ILIKE: return ['icontains', String(first)];
+            case FilterOperatorEnum.IN: return ['in', values.join(',')];
+            case FilterOperatorEnum.SW: return ['startswith', String(first)];
+            case FilterOperatorEnum.BTW: {
+                if (values.length !== 2) {
+                    throw new InvalidFilterOperatorValueError(operator, 'BTW requires exactly 2 values (min, max)');
+                }
+                return ['range', 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 ['isnull', String(first)];
+            }
+            case FilterOperatorEnum.NOT:
+            case FilterOperatorEnum.FTS:
+            case FilterOperatorEnum.PHFTS:
+            case FilterOperatorEnum.PLFTS:
+            case FilterOperatorEnum.WFTS:
+                throw new UnsupportedFilterOperatorError();
+        }
+    }
+}
+
+/**
+ * Response strategy for the Django REST Framework (DRF) driver
+ *
+ * Parses DRF `PageNumberPagination` responses:
+ *
+ * ```json
+ * {
+ *   "count": 100,
+ *   "next": "http://api.example.com/items/?page=3",
+ *   "previous": "http://api.example.com/items/?page=1",
+ *   "results": [...]
+ * }
+ * ```
+ *
+ * DRF emits no `current_page` field in the body, so this strategy
+ * **derives** the current page (and the page size) by inspecting the
+ * `next` / `previous` URLs:
+ *
+ * - `previous === null` → current page is **1**.
+ * - `previous` set but has no `?page=N` param → DRF omits `page=1` from
+ *   URLs when the previous page is the first, so we infer **2**.
+ * - `previous` has `?page=N` → current page is **N + 1**.
+ *
+ * Similarly, `perPage` is parsed from any `?page_size=N` query param on
+ * `next` or `previous`, and `lastPage` is computed as
+ * `ceil(count / perPage)`. When `perPage` cannot be discovered (e.g. on a
+ * single-page response that emits both URLs as `null`), `perPage` and
+ * `lastPage` are left undefined.
+ *
+ * Key paths are resolved through `DrfResponseOptions`, which defaults
+ * `data → 'results'`, `total → 'count'`, `nextPageUrl → 'next'`,
+ * `prevPageUrl → 'previous'`. The current-page / per-page / last-page
+ * paths default to empty strings — the strategy ignores `options` for
+ * those slots and uses URL inspection instead.
+ *
+ * @see https://www.django-rest-framework.org/api-guide/pagination/#pagenumberpagination
+ */
+class DrfResponseStrategy {
+    /**
+     * Parse a DRF pagination response into a PaginatedCollection
+     *
+     * @param response - The raw API response body
+     * @param options - The response key name configuration
+     * @returns A typed PaginatedCollection instance
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paginate(response, options) {
+        const data = response[options.data];
+        const total = response[options.total];
+        const prevPageUrl = (response[options.prevPageUrl] ?? null);
+        const nextPageUrl = (response[options.nextPageUrl] ?? null);
+        const currentPage = this._deriveCurrentPage(prevPageUrl);
+        const perPage = this._derivePerPage(nextPageUrl, prevPageUrl);
+        const lastPage = this._deriveLastPage(total, perPage);
+        const from = this._deriveFrom(currentPage, perPage);
+        const to = this._deriveTo(currentPage, perPage, total);
+        return new PaginatedCollection(data, currentPage, from, to, total, perPage, prevPageUrl ?? undefined, nextPageUrl ?? undefined, lastPage, undefined, undefined);
+    }
+    /**
+     * Derive the current page number from the `previous` URL
+     *
+     * - `null` → page 1
+     * - URL without `?page=N` → page 2 (DRF omits `page=1` from URLs)
+     * - URL with `?page=N` → N + 1
+     *
+     * @param prevPageUrl - The `previous` link from the DRF response, or null
+     * @returns The current page number
+     */
+    _deriveCurrentPage(prevPageUrl) {
+        if (prevPageUrl === null) {
+            return 1;
+        }
+        const prevPage = this._extractPageParam(prevPageUrl);
+        return prevPage === undefined ? 2 : prevPage + 1;
+    }
+    /**
+     * Derive `from` as the 1-indexed offset of the first item on this page
+     *
+     * @param currentPage - The current page number
+     * @param perPage - The page size (may be undefined)
+     * @returns The 1-indexed `from` index, or undefined when perPage is unknown
+     */
+    _deriveFrom(currentPage, perPage) {
+        if (!perPage) {
+            return undefined;
+        }
+        return (currentPage - 1) * perPage + 1;
+    }
+    /**
+     * Derive the last page number as `ceil(total / perPage)`
+     *
+     * Both inputs must be defined; an empty result set (`total === 0`)
+     * yields `lastPage = 0` which the caller treats as "no useful info"
+     * and skips the sync to `NestService.lastPage`.
+     *
+     * @param total - The total item count
+     * @param perPage - The page size
+     * @returns The last page number, or undefined when either input is missing
+     */
+    _deriveLastPage(total, perPage) {
+        if (total === undefined || perPage === undefined || perPage <= 0) {
+            return undefined;
+        }
+        return Math.ceil(total / perPage);
+    }
+    /**
+     * Derive `perPage` by parsing `?page_size=N` from any available URL
+     *
+     * Tries `next` first (page 1 always has a `next` URL with `page_size`
+     * if any non-default size was requested), then falls back to
+     * `previous`. Returns undefined when neither URL contains the param —
+     * the consumer is then on a single-page result with the server's
+     * default page size, which is not introspectable from the body alone.
+     *
+     * @param nextPageUrl - The `next` link from the response, or null
+     * @param prevPageUrl - The `previous` link from the response, or null
+     * @returns The page size, or undefined
+     */
+    _derivePerPage(nextPageUrl, prevPageUrl) {
+        return this._extractPageSizeParam(nextPageUrl) ?? this._extractPageSizeParam(prevPageUrl);
+    }
+    /**
+     * Derive `to` as the 1-indexed offset of the last item on this page
+     *
+     * Clamped to `total` so the last page does not report past the end.
+     *
+     * @param currentPage - The current page number
+     * @param perPage - The page size (may be undefined)
+     * @param total - The total item count (may be undefined)
+     * @returns The 1-indexed `to` index, or undefined when inputs insufficient
+     */
+    _deriveTo(currentPage, perPage, total) {
+        if (perPage === undefined || total === undefined) {
+            return undefined;
+        }
+        return Math.min(currentPage * perPage, total);
+    }
+    /**
+     * Extract the `page` query parameter from a DRF pagination URL
+     *
+     * Returns the integer value of `?page=N`, or undefined when the URL is
+     * malformed or has no `page` param (which, by DRF convention, means
+     * page 1 — the caller infers the semantics).
+     *
+     * @param url - The URL to parse
+     * @returns The integer page value, or undefined
+     */
+    _extractPageParam(url) {
+        const raw = this._extractQueryParam(url, 'page');
+        if (raw === undefined) {
+            return undefined;
+        }
+        const parsed = Number.parseInt(raw, 10);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    /**
+     * Extract the `page_size` query parameter from a DRF pagination URL
+     *
+     * @param url - The URL to parse (or null)
+     * @returns The integer page-size value, or undefined
+     */
+    _extractPageSizeParam(url) {
+        if (url === null) {
+            return undefined;
+        }
+        const raw = this._extractQueryParam(url, 'page_size');
+        if (raw === undefined) {
+            return undefined;
+        }
+        const parsed = Number.parseInt(raw, 10);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    /**
+     * Extract a single query parameter from a URL via the WHATWG URL parser
+     *
+     * Returns undefined when the URL is unparseable (relative URL without a
+     * base, or malformed) or when the parameter is absent.
+     *
+     * @param url - The URL to parse
+     * @param name - The query-parameter name to look up
+     * @returns The raw string value of the parameter, or undefined
+     */
+    _extractQueryParam(url, name) {
+        try {
+            const parsed = new URL(url);
+            const value = parsed.searchParams.get(name);
+            return value === null ? undefined : value;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+
+class UnselectableModelError extends Error {
+    constructor(model) {
+        super(`Unselectable Model: the selected model (${model}) is not present neither in the "model" property, nor in the includes object.`);
+    }
+}
+
 /**
  * Request strategy for the JSON:API driver
  *
@@ -625,6 +1147,39 @@ class LaravelRequestStrategy extends AbstractRequestStrategy {
     }
 }
 
+/**
+ * Base class for response strategies whose pagination metadata is a flat
+ * key-value envelope on the response body
+ *
+ * Laravel's stock pagination and Spatie's `QueryBuilder` both emit the
+ * same flat shape — `{ data, current_page, total, per_page, from, to,
+ * next_page_url, prev_page_url, first_page_url, last_page, last_page_url
+ * }` — and both response strategies were duplicating the byte-identical
+ * `new PaginatedCollection(response[options.X], ...)` body before this
+ * base existed. Concrete classes now extend and provide only the
+ * docstring describing their driver's specific shape (see
+ * `LaravelResponseStrategy`, `SpatieResponseStrategy`).
+ *
+ * Drivers whose pagination metadata is a nested envelope (JSON:API,
+ * NestJS, Strapi) extend `AbstractDotPathResponseStrategy` instead.
+ * Drivers whose metadata comes from HTTP headers (PostgREST) or is
+ * derived from response URLs (DRF) implement `IResponseStrategy`
+ * directly.
+ */
+class AbstractFlatResponseStrategy {
+    /**
+     * Parse a flat-envelope pagination response into a PaginatedCollection
+     *
+     * @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]);
+    }
+}
+
 /**
  * Response strategy for the Laravel (pagination-only) driver
  *
@@ -637,22 +1192,20 @@ class LaravelRequestStrategy extends AbstractRequestStrategy {
  *   "per_page": 15,
  *   "from": 1,
  *   "to": 15,
- *   ...
+ *   "next_page_url": "...",
+ *   "prev_page_url": "...",
+ *   "first_page_url": "...",
+ *   "last_page": 7,
+ *   "last_page_url": "..."
  * }
  * ```
+ *
+ * The traversal algorithm (flat `response[options.X]` lookups) is
+ * inherited from `AbstractFlatResponseStrategy`; this class exists so
+ * `DriverEnum.LARAVEL` resolves to a distinct identity at the DI layer
+ * even though the parsing logic is shared with Spatie.
  */
-class LaravelResponseStrategy {
-    /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
-     *
-     * @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]);
-    }
+class LaravelResponseStrategy extends AbstractFlatResponseStrategy {
 }
 
 /**
@@ -847,43 +1400,6 @@ class NestjsRequestStrategy extends AbstractRequestStrategy {
 class NestjsResponseStrategy extends AbstractDotPathResponseStrategy {
 }
 
-/**
- * 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
  *
@@ -902,32 +1418,6 @@ var PaginationModeEnum;
     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';
-    }
-}
-
 /**
  * Request strategy for the PostgREST driver
  *
@@ -1442,7 +1932,8 @@ class SpatieRequestStrategy extends AbstractRequestStrategy {
 /**
  * Response strategy for the Spatie Query Builder driver
  *
- * Parses flat Laravel pagination responses:
+ * Parses flat Laravel-style pagination responses (Spatie's Query Builder
+ * is built on Laravel's pagination):
  * ```json
  * {
  *   "data": [...],
@@ -1455,33 +1946,14 @@ class SpatieRequestStrategy extends AbstractRequestStrategy {
  * }
  * ```
  *
- * @see https://spatie.be/docs/laravel-query-builder
- */
-class SpatieResponseStrategy {
-    /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
-     *
-     * @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]);
-    }
-}
-
-/**
- * Error thrown when filter operators are attempted with a driver that does not support them
+ * The traversal algorithm (flat `response[options.X]` lookups) is
+ * inherited from `AbstractFlatResponseStrategy`; this class exists so
+ * `DriverEnum.SPATIE` resolves to a distinct identity at the DI layer
+ * even though the parsing logic is shared with the plain Laravel driver.
  *
- * Filter operators are only supported by the NestJS driver.
- * Use `addFilter()` for Spatie implicit equality filters.
+ * @see https://spatie.be/docs/laravel-query-builder
  */
-class UnsupportedFilterOperatorError extends Error {
-    constructor() {
-        super('Filter operators are only supported by the NestJS driver. Use addFilter() for Spatie.');
-        this.name = 'UnsupportedFilterOperatorError';
-    }
+class SpatieResponseStrategy extends AbstractFlatResponseStrategy {
 }
 
 /**
@@ -1764,6 +2236,11 @@ class StrapiResponseStrategy extends AbstractDotPathResponseStrategy {
  * `switch` blocks.
  */
 const DRIVERS = {
+    [DriverEnum.DRF]: {
+        createRequestStrategy: () => new DrfRequestStrategy(),
+        createResponseStrategy: () => new DrfResponseStrategy(),
+        createResponseOptions: (config) => new DrfResponseOptions(config)
+    },
     [DriverEnum.JSON_API]: {
         createRequestStrategy: () => new JsonApiRequestStrategy(),
         createResponseStrategy: () => new JsonApiResponseStrategy(),