ng-qubee 3.3.0 → 3.5.0

package/fesm2022/ng-qubee.mjs

@@ -74,11 +74,13 @@ class PaginatedCollection {
  */
 var DriverEnum;
 (function (DriverEnum) {
+    DriverEnum["DRF"] = "drf";
     DriverEnum["JSON_API"] = "json-api";
     DriverEnum["LARAVEL"] = "laravel";
     DriverEnum["NESTJS"] = "nestjs";
     DriverEnum["POSTGREST"] = "postgrest";
     DriverEnum["SPATIE"] = "spatie";
+    DriverEnum["STRAPI"] = "strapi";
 })(DriverEnum || (DriverEnum = {}));
 
 /**
@@ -123,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
  *
@@ -171,6 +202,69 @@ class NestjsResponseOptions extends ResponseOptions {
         });
     }
 }
+/**
+ * Pre-configured ResponseOptions for the Strapi driver
+ *
+ * Uses dot-notation paths to access the nested `meta.pagination.*` envelope
+ * Strapi v4/v5 emits. Strapi does not include navigation links by default,
+ * so the URL paths point at locations that will resolve to `undefined`
+ * unless the consumer overrides them.
+ */
+class StrapiResponseOptions extends ResponseOptions {
+    constructor(options) {
+        super({
+            currentPage: options.currentPage || 'meta.pagination.page',
+            data: options.data || 'data',
+            firstPageUrl: options.firstPageUrl || 'links.first',
+            from: options.from || 'meta.pagination.from',
+            lastPage: options.lastPage || 'meta.pagination.pageCount',
+            lastPageUrl: options.lastPageUrl || 'links.last',
+            nextPageUrl: options.nextPageUrl || 'links.next',
+            path: options.path || 'path',
+            perPage: options.perPage || 'meta.pagination.pageSize',
+            prevPageUrl: options.prevPageUrl || 'links.prev',
+            to: options.to || 'meta.pagination.to',
+            total: options.total || 'meta.pagination.total'
+        });
+    }
+}
+
+/**
+ * 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) {
@@ -178,9 +272,42 @@ var SortEnum;
     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';
     }
 }
 
@@ -290,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
  *
@@ -598,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
  *
@@ -610,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 {
 }
 
 /**
@@ -820,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
  *
@@ -875,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
  *
@@ -1415,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": [...],
@@ -1428,20 +1946,283 @@ class SpatieRequestStrategy extends AbstractRequestStrategy {
  * }
  * ```
  *
+ * 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.
+ *
  * @see https://spatie.be/docs/laravel-query-builder
  */
-class SpatieResponseStrategy {
+class SpatieResponseStrategy extends AbstractFlatResponseStrategy {
+}
+
+/**
+ * Request strategy for the Strapi driver
+ *
+ * Generates URIs in [Strapi's filter API format](https://docs.strapi.io/dev-docs/api/rest/filters-locale-publication):
+ * - Filters: `filters[field][$eq]=value` (multi-value collapses to `$in`)
+ * - Operator filters: `filters[field][$op]=value` (translated from
+ *   `FilterOperatorEnum` — `BTW`→`$between`, `SW`→`$startsWith`,
+ *   `ILIKE`→`$containsi`, `NOT`→`$ne`/`$notIn`,
+ *   `NULL`→`$null`/`$notNull`)
+ * - Sorts: `sort[0]=field:asc&sort[1]=field:desc`
+ * - Field selection (flat): `fields[0]=col1&fields[1]=col2`
+ * - Population: `populate[0]=relation`
+ * - Pagination (page-based): `pagination[page]=N&pagination[pageSize]=N`
+ *
+ * Strapi-native full-text search (`FTS`, `PHFTS`, `PLFTS`, `WFTS`) is
+ * PostgREST-only and throws `UnsupportedFilterOperatorError` here.
+ *
+ * @see https://docs.strapi.io/dev-docs/api/rest/filters-locale-publication
+ */
+class StrapiRequestStrategy extends AbstractRequestStrategy {
+    /**
+     * Filters, operator filters, sorts, populate (`includes`), flat field
+     * selection (`select`) — no per-model fields, no global search (use
+     * `$contains` / `$containsi` operator filters instead)
+     */
+    capabilities = {
+        fields: false,
+        filters: true,
+        includes: true,
+        operatorFilters: true,
+        search: false,
+        select: true,
+        sort: true
+    };
     /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
+     * Strapi-native names of the four hardcoded query keys
      *
-     * @param response - The raw API response object
-     * @param options - The response key name configuration
-     * @returns A typed PaginatedCollection instance
+     * Strapi's wire format is fixed (the server reads `pagination[page]`,
+     * `populate`, `sort`, `fields`); these keys are intentionally not
+     * configurable through `QueryBuilderOptions` and live as private
+     * statics so they are visible in one place.
      */
-    // 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]);
+    static _fieldsKey = 'fields';
+    static _paginationKey = 'pagination';
+    static _populateKey = 'populate';
+    static _sortKey = 'sort';
+    /**
+     * Emit Strapi-format query-string segments in canonical order:
+     * populate → fields → filters (merged) → sort → pagination
+     *
+     * Simple filters and operator filters share a single `filters` wrapper
+     * so qs emits one ordered, deeply-nested bracket structure rather than
+     * two duplicate top-level `filters[...]` blocks.
+     *
+     * @param state - The current query builder state
+     * @param _options - The query parameter key name configuration (unused;
+     * Strapi's wire keys are fixed by the server)
+     * @returns Ordered query-string fragments
+     */
+    parts(state, _options) {
+        const out = [];
+        this._appendPopulate(state, out);
+        this._appendFields(state, out);
+        this._appendFilters(state, out);
+        this._appendSort(state, out);
+        this._appendPagination(state, out);
+        return out;
+    }
+    /**
+     * Append `fields[0]=col1&fields[1]=col2` from the flat select array
+     *
+     * Strapi's `fields` parameter is the column-pruner for the main
+     * resource; per-relation field selection is expressed through the
+     * `populate` deep syntax (out of scope for this driver).
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendFields(state, out) {
+        if (!state.select.length) {
+            return;
+        }
+        out.push(qs.stringify({ [StrapiRequestStrategy._fieldsKey]: state.select }, { encode: false }));
+    }
+    /**
+     * Append the unified `filters[...]` wrapper combining simple filters
+     * and operator filters
+     *
+     * Both kinds emit into the same nested object under `filters` so qs
+     * produces a single deeply-bracketed block per request. Simple
+     * single-value filters fold to `$eq`; simple multi-value filters fold
+     * to `$in`. Operator filters then merge into the same per-field map,
+     * potentially co-existing with a simple filter on the same field.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendFilters(state, out) {
+        const simpleKeys = Object.keys(state.filters);
+        if (!simpleKeys.length && !state.operatorFilters.length) {
+            return;
+        }
+        const filters = {};
+        simpleKeys.forEach(key => {
+            const values = state.filters[key];
+            if (!values.length) {
+                return;
+            }
+            filters[key] = values.length === 1
+                ? { $eq: values[0] }
+                : { $in: values };
+        });
+        state.operatorFilters.forEach((filter) => {
+            const payload = this._formatOperatorPayload(filter);
+            filters[filter.field] = {
+                ...(filters[filter.field] ?? {}),
+                ...payload
+            };
+        });
+        if (!Object.keys(filters).length) {
+            return;
+        }
+        out.push(qs.stringify({ filters }, { encode: false }));
+    }
+    /**
+     * Append the `pagination[page]` / `pagination[pageSize]` wrapper
+     *
+     * Page-based mode is the Strapi default; offset-based
+     * (`pagination[start]` / `pagination[limit]`) is out of scope for this
+     * driver until cursor/offset pagination lands library-wide.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendPagination(state, out) {
+        const wrapper = {
+            [StrapiRequestStrategy._paginationKey]: {
+                page: state.page,
+                pageSize: state.limit
+            }
+        };
+        out.push(qs.stringify(wrapper, { encode: false }));
+    }
+    /**
+     * Append the `populate` parameter from the includes array
+     *
+     * Emits `populate[0]=relation1&populate[1]=relation2`; deep-populate
+     * syntax (`populate[author][fields][0]=name`) is not exposed through
+     * the current state shape.
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendPopulate(state, out) {
+        if (!state.includes.length) {
+            return;
+        }
+        out.push(qs.stringify({ [StrapiRequestStrategy._populateKey]: state.includes }, { encode: false }));
     }
+    /**
+     * Append the `sort[N]=field:dir` array
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    _appendSort(state, out) {
+        if (!state.sorts.length) {
+            return;
+        }
+        const pairs = state.sorts.map(sort => `${sort.field}:${sort.order === SortEnum.DESC ? 'desc' : 'asc'}`);
+        out.push(qs.stringify({ [StrapiRequestStrategy._sortKey]: pairs }, { encode: false }));
+    }
+    /**
+     * Translate a `FilterOperatorEnum` operator filter into Strapi's
+     * `$operator → value` payload shape
+     *
+     * The mapping is library-canonical → Strapi-native:
+     * - `EQ`/`GT`/`GTE`/`LT`/`LTE`/`CONTAINS` → identity (same key name)
+     * - `ILIKE` → `$containsi` (case-insensitive contains)
+     * - `IN` → `$in` (array)
+     * - `SW` → `$startsWith`
+     * - `BTW` → `$between` with `[min, max]` (arity-checked)
+     * - `NOT` → `$ne` (single value) / `$notIn` (multi-value)
+     * - `NULL` → `$null=true` (when value is `true`) / `$notNull=true`
+     *   (when value is `false`); arity- and type-checked
+     *
+     * PostgREST's full-text-search operators (`FTS`, `PHFTS`, `PLFTS`,
+     * `WFTS`) have no Strapi equivalent and throw
+     * `UnsupportedFilterOperatorError`.
+     *
+     * @param filter - The operator filter to translate
+     * @returns A `{ $operator: value }` payload ready to merge under
+     * `filters[field]`
+     * @throws {InvalidFilterOperatorValueError} If `BTW` does not receive
+     * exactly two values, or `NULL` does not receive exactly one boolean
+     * @throws {UnsupportedFilterOperatorError} If the operator is a
+     * PostgREST-only FTS variant
+     */
+    _formatOperatorPayload(filter) {
+        const { operator, values } = filter;
+        const first = values[0];
+        switch (operator) {
+            case FilterOperatorEnum.EQ: return { $eq: first };
+            case FilterOperatorEnum.GT: return { $gt: first };
+            case FilterOperatorEnum.GTE: return { $gte: first };
+            case FilterOperatorEnum.LT: return { $lt: first };
+            case FilterOperatorEnum.LTE: return { $lte: first };
+            case FilterOperatorEnum.CONTAINS: return { $contains: first };
+            case FilterOperatorEnum.ILIKE: return { $containsi: first };
+            case FilterOperatorEnum.IN: return { $in: values };
+            case FilterOperatorEnum.SW: return { $startsWith: first };
+            case FilterOperatorEnum.BTW: {
+                if (values.length !== 2) {
+                    throw new InvalidFilterOperatorValueError(operator, 'BTW requires exactly 2 values (min, max)');
+                }
+                return { $between: values };
+            }
+            case FilterOperatorEnum.NOT:
+                return values.length === 1
+                    ? { $ne: first }
+                    : { $notIn: values };
+            case FilterOperatorEnum.NULL: {
+                if (values.length !== 1 || typeof first !== 'boolean') {
+                    throw new InvalidFilterOperatorValueError(operator, 'NULL requires exactly 1 boolean value (true → IS NULL, false → IS NOT NULL)');
+                }
+                return first ? { $null: true } : { $notNull: true };
+            }
+            case FilterOperatorEnum.FTS:
+            case FilterOperatorEnum.PHFTS:
+            case FilterOperatorEnum.PLFTS:
+            case FilterOperatorEnum.WFTS:
+                throw new UnsupportedFilterOperatorError();
+        }
+    }
+}
+
+/**
+ * Response strategy for the Strapi driver
+ *
+ * Parses Strapi v4/v5 pagination responses:
+ * ```json
+ * {
+ *   "data": [{ "id": 1, "documentId": "abc", "title": "Hello" }],
+ *   "meta": {
+ *     "pagination": {
+ *       "page": 1,
+ *       "pageSize": 10,
+ *       "pageCount": 5,
+ *       "total": 48
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Default key paths are configured in `StrapiResponseOptions`. Strapi
+ * does not include navigation links in the envelope, so `firstPageUrl`,
+ * `prevPageUrl`, `nextPageUrl`, and `lastPageUrl` resolve to `undefined`
+ * unless the consumer overrides their paths via `IPaginationConfig`. The
+ * traversal algorithm (dot-notation resolution + computed `from`/`to`)
+ * is inherited from `AbstractDotPathResponseStrategy`; this class exists
+ * so `DriverEnum.STRAPI` resolves to a distinct identity at the DI
+ * layer even though the parsing logic is shared with JSON:API and
+ * NestJS.
+ *
+ * @see https://docs.strapi.io/dev-docs/api/rest/sort-pagination
+ */
+class StrapiResponseStrategy extends AbstractDotPathResponseStrategy {
 }
 
 /**
@@ -1455,6 +2236,11 @@ class SpatieResponseStrategy {
  * `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(),
@@ -1479,6 +2265,11 @@ const DRIVERS = {
         createRequestStrategy: () => new SpatieRequestStrategy(),
         createResponseStrategy: () => new SpatieResponseStrategy(),
         createResponseOptions: (config) => new ResponseOptions(config)
+    },
+    [DriverEnum.STRAPI]: {
+        createRequestStrategy: () => new StrapiRequestStrategy(),
+        createResponseStrategy: () => new StrapiResponseStrategy(),
+        createResponseOptions: (config) => new StrapiResponseOptions(config)
     }
 };
 
@@ -2011,19 +2802,6 @@ class UnsupportedFilterError extends Error {
     }
 }
 
-/**
- * Error thrown when filter operators are attempted with a driver that does not support them
- *
- * Filter operators are only supported by the NestJS driver.
- * Use `addFilter()` for Spatie implicit equality filters.
- */
-class UnsupportedFilterOperatorError extends Error {
-    constructor() {
-        super('Filter operators are only supported by the NestJS driver. Use addFilter() for Spatie.');
-        this.name = 'UnsupportedFilterOperatorError';
-    }
-}
-
 /**
  * Error thrown when includes are attempted with a driver that does not support them
  *
@@ -2848,5 +3626,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-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 { 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, StrapiRequestStrategy, StrapiResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, buildNgQubeeProviders, provideNgQubee, provideNgQubeeInstance, readHeader };
 //# sourceMappingURL=ng-qubee.mjs.map