ng-qubee 3.3.0 → 3.5.0

package/package.json

@@ -4,7 +4,7 @@
     "name": "Andrea Tantimonaco",
     "url": "https://andreatantimonaco.me"
   },
-  "version": "3.3.0",
+  "version": "3.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,20 +13,29 @@
   "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",
+    "django",
+    "drf",
     "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

@@ -46,11 +46,13 @@ declare class PaginatedCollection<T extends IPaginatedObject> {
  * request building (URI generation) and response parsing.
  */
 declare enum DriverEnum {
+    DRF = "drf",
     JSON_API = "json-api",
     LARAVEL = "laravel",
     NESTJS = "nestjs",
     POSTGREST = "postgrest",
-    SPATIE = "spatie"
+    SPATIE = "spatie",
+    STRAPI = "strapi"
 }
 
 /**
@@ -1641,6 +1643,36 @@ declare class LaravelRequestStrategy extends AbstractRequestStrategy {
     protected parts(state: IQueryBuilderState, options: QueryBuilderOptions): string[];
 }
 
+/**
+ * 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.
+ */
+declare abstract class AbstractFlatResponseStrategy implements IResponseStrategy {
+    /**
+     * 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
+     */
+    paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
+}
+
 /**
  * Response strategy for the Laravel (pagination-only) driver
  *
@@ -1653,19 +1685,20 @@ declare 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.
  */
-declare class LaravelResponseStrategy implements IResponseStrategy {
-    /**
-     * 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
-     */
-    paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
+declare class LaravelResponseStrategy extends AbstractFlatResponseStrategy {
 }
 
 /**
@@ -2084,7 +2117,8 @@ declare 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": [...],
@@ -2097,18 +2131,183 @@ declare 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
  */
-declare class SpatieResponseStrategy implements IResponseStrategy {
+declare 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
+ */
+declare class StrapiRequestStrategy extends AbstractRequestStrategy {
     /**
-     * Parse a flat Laravel pagination response into a PaginatedCollection
+     * 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
      *
-     * @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.
      */
-    paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
+    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, 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 };
 export type { HeaderBag, IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };