ng-qubee 3.3.0 → 3.4.0

package/fesm2022/ng-qubee.mjs

@@ -79,6 +79,7 @@ var DriverEnum;
     DriverEnum["NESTJS"] = "nestjs";
     DriverEnum["POSTGREST"] = "postgrest";
     DriverEnum["SPATIE"] = "spatie";
+    DriverEnum["STRAPI"] = "strapi";
 })(DriverEnum || (DriverEnum = {}));
 
 /**
@@ -171,6 +172,32 @@ 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'
+        });
+    }
+}
 
 var SortEnum;
 (function (SortEnum) {
@@ -1444,6 +1471,288 @@ class SpatieResponseStrategy {
     }
 }
 
+/**
+ * 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';
+    }
+}
+
+/**
+ * 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
+    };
+    /**
+     * Strapi-native names of the four hardcoded query keys
+     *
+     * 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.
+     */
+    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 {
+}
+
 /**
  * Driver registry — single source of truth for what each `DriverEnum`
  * value resolves to
@@ -1479,6 +1788,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 +2325,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 +3149,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