ng-qubee 3.3.0 → 3.4.0

package/package.json

@@ -4,7 +4,7 @@
     "name": "Andrea Tantimonaco",
     "url": "https://andreatantimonaco.me"
   },
-  "version": "3.3.0",
+  "version": "3.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,20 +13,27 @@
   "bugs": {
     "url": "https://github.com/AndreaAlhena/ng-qubee/issues"
   },
-  "homepage": "https://github.com/AndreaAlhena/ng-qubee#readme",
+  "homepage": "https://ng-qubee.andreatantimonaco.me",
   "keywords": [
     "angular",
-    "query-builder",
     "api",
-    "pagination",
-    "rxjs",
+    "builder",
     "filter",
+    "headless-cms",
+    "json-api",
+    "laravel",
+    "nestjs",
+    "nestjs-paginate",
+    "pagination",
+    "postgrest",
     "query",
-    "builder",
-    "typescript",
+    "query-builder",
+    "rxjs",
     "signals",
-    "postgrest",
-    "supabase"
+    "spatie",
+    "strapi",
+    "supabase",
+    "typescript"
   ],
   "allowedNonPeerDependencies": [
     "qs"

package/types/ng-qubee.d.ts

@@ -50,7 +50,8 @@ declare enum DriverEnum {
     LARAVEL = "laravel",
     NESTJS = "nestjs",
     POSTGREST = "postgrest",
-    SPATIE = "spatie"
+    SPATIE = "spatie",
+    STRAPI = "strapi"
 }
 
 /**
@@ -2110,5 +2111,173 @@ declare class SpatieResponseStrategy implements IResponseStrategy {
     paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
 }
 
-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 };
+/**
+ * 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
+ */
+declare 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)
+     */
+    readonly capabilities: IStrategyCapabilities;
+    /**
+     * 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.
+     */
+    private static readonly _fieldsKey;
+    private static readonly _paginationKey;
+    private static readonly _populateKey;
+    private static readonly _sortKey;
+    /**
+     * 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
+     */
+    protected parts(state: IQueryBuilderState, _options: QueryBuilderOptions): string[];
+    /**
+     * 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
+     */
+    private _appendFields;
+    /**
+     * 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
+     */
+    private _appendFilters;
+    /**
+     * 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
+     */
+    private _appendPagination;
+    /**
+     * 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
+     */
+    private _appendPopulate;
+    /**
+     * Append the `sort[N]=field:dir` array
+     *
+     * @param state - The current query builder state
+     * @param out - The accumulator the caller joins into the URI
+     */
+    private _appendSort;
+    /**
+     * 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
+     */
+    private _formatOperatorPayload;
+}
+
+/**
+ * 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
+ */
+declare class StrapiResponseStrategy extends AbstractDotPathResponseStrategy {
+}
+
+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 };
 export type { HeaderBag, IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };