ng-qubee 3.0.0 → 3.1.0

package/package.json

@@ -5,7 +5,7 @@
     "email": "info@andreatantimonaco.me",
     "url": "https://andreatantimonaco.me"
   },
-  "version": "3.0.0",
+  "version": "3.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/types/ng-qubee.d.ts

@@ -46,6 +46,7 @@ declare class PaginatedCollection<T extends IPaginatedObject> {
  * request building (URI generation) and response parsing.
  */
 declare enum DriverEnum {
+    JSON_API = "json-api",
     LARAVEL = "laravel",
     NESTJS = "nestjs",
     SPATIE = "spatie"
@@ -174,6 +175,15 @@ declare class NgQubeeModule {
  * });
  * ```
  *
+ * JSON:API driver example:
+ * ```
+ * import { DriverEnum } from 'ng-qubee';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideNgQubee({ driver: DriverEnum.JSON_API })]
+ * });
+ * ```
+ *
  * NestJS driver example:
  * ```
  * import { DriverEnum } from 'ng-qubee';
@@ -321,6 +331,17 @@ interface IRequestStrategy {
      * @returns The composed URI string
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Assert that the given limit value is valid for this driver
+     *
+     * Validation is driver-scoped because the accepted range differs by
+     * backend: nestjs-paginate treats `-1` as a "fetch all" sentinel, while
+     * other backends (Laravel, Spatie, JSON:API) require a positive integer.
+     *
+     * @param limit - The limit value to validate
+     * @throws {import('../errors/invalid-limit.error').InvalidLimitError} If the value is not accepted by the driver
+     */
+    validateLimit(limit: number): void;
 }
 
 declare class NestService {
@@ -347,10 +368,13 @@ declare class NestService {
     set baseUrl(baseUrl: string);
     /**
      * Set the limit for paginated results
-     * Must be a positive integer greater than 0
+     *
+     * This setter performs a raw state write. Validation of the value is the
+     * responsibility of the active request strategy and is enforced upstream
+     * by `NgQubeeService.setLimit()`, because the accepted range depends on
+     * the driver (e.g. nestjs-paginate accepts `-1` for "fetch all").
      *
      * @param {number} limit - The number of items per page
-     * @throws {InvalidLimitError} If limit is not a positive integer
      * @example
      * service.limit = 25;
      */
@@ -376,14 +400,6 @@ declare class NestService {
      */
     set resource(resource: string);
     private _clone;
-    /**
-     * Validates that the limit is a positive integer
-     *
-     * @param {number} limit - The limit value to validate
-     * @throws {InvalidLimitError} If limit is not a positive integer
-     * @private
-     */
-    private _validateLimit;
     /**
      * Validates that the page number is a positive integer
      *
@@ -589,7 +605,7 @@ declare class NgQubeeService {
      */
     private _assertDriver;
     /**
-     * Add fields to the select statement for the given model (Spatie only)
+     * Add fields to the select statement for the given model (JSON:API and Spatie only)
      *
      * @param model - Model that holds the fields
      * @param fields - Fields to select
@@ -598,9 +614,9 @@ declare class NgQubeeService {
      */
     addFields(model: string, fields: string[]): this;
     /**
-     * Add a filter with the given value(s) (Spatie and NestJS only)
+     * Add a filter with the given value(s) (JSON:API, NestJS, and Spatie)
      *
-     * Produces: `filter[field]=value` (Spatie) or `filter.field=value` (NestJS)
+     * Produces: `filter[field]=value` (JSON:API / Spatie) or `filter.field=value` (NestJS)
      *
      * @param {string} field - Name of the field to filter
      * @param {(string | number | boolean)[]} values - The needle(s)
@@ -621,7 +637,7 @@ declare class NgQubeeService {
      */
     addFilterOperator(field: string, operator: FilterOperatorEnum, ...values: (string | number | boolean)[]): this;
     /**
-     * Add related entities to include in the request (Spatie only)
+     * Add related entities to include in the request (JSON:API and Spatie only)
      *
      * @param {string[]} models - Models to include
      * @returns {this}
@@ -639,7 +655,7 @@ declare class NgQubeeService {
      */
     addSelect(...fields: string[]): this;
     /**
-     * Add a field with a sort criteria (Spatie and NestJS only)
+     * Add a field with a sort criteria (JSON:API, NestJS, and Spatie)
      *
      * @param field - Field to use for sorting
      * @param {SortEnum} order - A value from the SortEnum enumeration
@@ -648,7 +664,7 @@ declare class NgQubeeService {
      */
     addSort(field: string, order: SortEnum): this;
     /**
-     * Delete selected fields for the given models in the current query builder state (Spatie only)
+     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
      * ```
      * ngQubeeService.deleteFields({
@@ -663,7 +679,7 @@ declare class NgQubeeService {
      */
     deleteFields(fields: IFields): this;
     /**
-     * Delete selected fields for the given model in the current query builder state (Spatie only)
+     * Delete selected fields for the given model in the current query builder state (JSON:API and Spatie only)
      *
      * ```
      * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
@@ -676,7 +692,7 @@ declare class NgQubeeService {
      */
     deleteFieldsByModel(model: string, ...fields: string[]): this;
     /**
-     * Remove given filters from the query builder state (Spatie and NestJS only)
+     * Remove given filters from the query builder state (JSON:API, NestJS, and Spatie)
      *
      * @param {string[]} filters - Filters to remove
      * @returns {this}
@@ -684,7 +700,7 @@ declare class NgQubeeService {
      */
     deleteFilters(...filters: string[]): this;
     /**
-     * Remove selected related models from the query builder state (Spatie only)
+     * Remove selected related models from the query builder state (JSON:API and Spatie only)
      *
      * @param {string[]} includes - Models to remove
      * @returns {this}
@@ -715,7 +731,7 @@ declare class NgQubeeService {
      */
     deleteSelect(...fields: string[]): this;
     /**
-     * Remove sort rules from the query builder state (Spatie and NestJS only)
+     * Remove sort rules from the query builder state (JSON:API, NestJS, and Spatie)
      *
      * @param sorts - Fields used for sorting to remove
      * @returns {this}
@@ -744,8 +760,14 @@ declare class NgQubeeService {
     /**
      * Set the items per page number
      *
-     * @param limit - Number of items per page
+     * Validation is delegated to the active request strategy because the
+     * accepted range is driver-specific: nestjs-paginate additionally accepts
+     * `-1` as a "fetch all" sentinel, while Laravel, Spatie, and JSON:API
+     * require a positive integer.
+     *
+     * @param limit - Number of items per page (or `-1` to fetch all, NestJS only)
      * @returns {this}
+     * @throws {import('../errors/invalid-limit.error').InvalidLimitError} If the value is not accepted by the active driver
      */
     setLimit(limit: number): this;
     /**
@@ -772,8 +794,6 @@ declare class NgQubeeService {
      * @throws {UnsupportedSearchError} If the active driver does not support search
      */
     setSearch(search: string): this;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NgQubeeService, [null, null, null, { optional: true; }]>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<NgQubeeService>;
 }
 
 /**
@@ -844,12 +864,22 @@ declare class PaginationService {
     paginate<T extends IPaginatedObject>(response: {
         [key: string]: any;
     }): PaginatedCollection<T>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, [null, { optional: true; }]>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<PaginationService>;
 }
 
+/**
+ * Thrown when a limit value does not satisfy the active driver's constraints
+ *
+ * Validation is driver-scoped: most drivers require an integer `>= 1`, while
+ * the NestJS driver additionally accepts `-1` as a "fetch all items" sentinel
+ * (as documented by nestjs-paginate). The message is tailored accordingly so
+ * the caller understands which values are permitted.
+ */
 declare class InvalidLimitError extends Error {
-    constructor(limit: number);
+    /**
+     * @param limit - The rejected limit value
+     * @param allowFetchAll - Whether the active driver accepts `-1` (fetch all)
+     */
+    constructor(limit: number, allowFetchAll?: boolean);
 }
 
 declare class InvalidPageNumberError extends Error {
@@ -946,6 +976,188 @@ interface INestState {
 interface IPage {
 }
 
+/**
+ * Request strategy for the JSON:API driver
+ *
+ * Generates URIs in the JSON:API format:
+ * - Fields: `fields[articles]=title,body&fields[people]=name`
+ * - Filters: `filter[status]=active`
+ * - Includes: `include=author,comments.author`
+ * - Pagination: `page[number]=1&page[size]=15`
+ * - Sort: `sort=-created_at,name` (- prefix = DESC)
+ *
+ * @see https://jsonapi.org/format/
+ */
+declare class JsonApiRequestStrategy implements IRequestStrategy {
+    /**
+     * Accumulator for composing the URI string
+     */
+    private _uri;
+    /**
+     * Build a URI string from the given state using the JSON:API format
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The composed URI string
+     * @throws Error if resource is not set
+     */
+    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Validate that the given limit is accepted by the JSON:API driver
+     *
+     * The JSON:API specification leaves pagination semantics to the server and
+     * does not define a "fetch all" sentinel, so only positive integers are
+     * accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit: number): void;
+    /**
+     * Parse and append field selection parameters
+     *
+     * Validates that each field model exists either as the main resource
+     * or in the includes list. Fields are grouped by type in bracket notation.
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated field selection parameter string
+     * @throws Error if resource is required but not set
+     * @throws UnselectableModelError if a field model is not in resource or includes
+     */
+    private _parseFields;
+    /**
+     * Parse and append filter parameters
+     *
+     * Generates filter parameters in bracket notation: `filter[key]=value1,value2`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated filter parameter string
+     */
+    private _parseFilters;
+    /**
+     * Parse and append include parameters
+     *
+     * Generates: `include=author,comments.author`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated include parameter string
+     */
+    private _parseIncludes;
+    /**
+     * Parse and append pagination parameters in JSON:API bracket notation
+     *
+     * Generates: `page[number]=1&page[size]=15`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated pagination parameter string
+     */
+    private _parsePagination;
+    /**
+     * Parse and append sort parameters
+     *
+     * Generates: `sort=-field1,field2` where `-` prefix indicates DESC order
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated sort parameter string
+     */
+    private _parseSort;
+    /**
+     * Determine the appropriate URI prefix based on the current accumulator state
+     *
+     * Returns the full base path with `?` for the first parameter,
+     * or `&` for subsequent parameters.
+     *
+     * @param state - The current query builder state
+     * @returns The prefix string to prepend to the next parameter
+     */
+    private _prepend;
+}
+
+/**
+ * Response strategy for the JSON:API driver
+ *
+ * Parses JSON:API pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "meta": {
+ *     "current-page": 1,
+ *     "per-page": 10,
+ *     "total": 100,
+ *     "page-count": 10,
+ *     "from": 1,
+ *     "to": 10
+ *   },
+ *   "links": {
+ *     "first": "url",
+ *     "prev": "url",
+ *     "next": "url",
+ *     "last": "url"
+ *   }
+ * }
+ * ```
+ *
+ * @see https://jsonapi.org/format/
+ */
+declare class JsonApiResponseStrategy implements IResponseStrategy {
+    /**
+     * Parse a JSON:API pagination response into a PaginatedCollection
+     *
+     * Supports dot-notation key paths for accessing nested values.
+     * Computes `from` and `to` from `currentPage` and `perPage` when
+     * they are not directly available in the response.
+     *
+     * @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>;
+    /**
+     * Resolve a value from a response object using a dot-notation path
+     *
+     * Supports both flat keys ('data') and nested paths ('meta.current-page').
+     *
+     * @param response - The raw response object
+     * @param path - The dot-notation path to resolve
+     * @returns The resolved value, or undefined if not found
+     */
+    private _resolve;
+    /**
+     * Resolve the "from" index value
+     *
+     * If the path resolves to a value in the response, use it.
+     * Otherwise, compute it from currentPage and perPage:
+     * `(currentPage - 1) * perPage + 1`
+     *
+     * @param response - The raw response object
+     * @param options - The response key name configuration
+     * @param currentPage - The current page number
+     * @param perPage - The number of items per page
+     * @returns The computed "from" index
+     */
+    private _resolveFrom;
+    /**
+     * Resolve the "to" index value
+     *
+     * If the path resolves to a value in the response, use it.
+     * Otherwise, compute it from currentPage, perPage, and total:
+     * `Math.min(currentPage * perPage, total)`
+     *
+     * @param response - The raw response object
+     * @param options - The response key name configuration
+     * @param currentPage - The current page number
+     * @param perPage - The number of items per page
+     * @param total - The total number of items
+     * @returns The computed "to" index
+     */
+    private _resolveTo;
+}
+
 /**
  * Request strategy for the Laravel (pagination-only) driver
  *
@@ -964,6 +1176,16 @@ declare class LaravelRequestStrategy implements IRequestStrategy {
      * @throws Error if resource is not set
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Validate that the given limit is accepted by the Laravel driver
+     *
+     * Laravel pagination does not recognize `-1` as a "fetch all" sentinel,
+     * so only positive integers are accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit: number): void;
 }
 
 /**
@@ -1020,6 +1242,16 @@ declare class NestjsRequestStrategy implements IRequestStrategy {
      * @throws Error if model is not set
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Validate that the given limit is accepted by nestjs-paginate
+     *
+     * Accepts any integer `>= 1` as a page size, plus `-1` which nestjs-paginate
+     * interprets as "fetch all items" (server must opt-in via `maxLimit: -1`).
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not an integer, or is 0, or is a negative number other than -1
+     */
+    validateLimit(limit: number): void;
     /**
      * Parse and append simple filter parameters
      *
@@ -1198,6 +1430,16 @@ declare class SpatieRequestStrategy implements IRequestStrategy {
      * @throws Error if resource is not set
      */
     buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Validate that the given limit is accepted by the Spatie driver
+     *
+     * Spatie query-builder does not recognize `-1` as a "fetch all" sentinel,
+     * so only positive integers are accepted.
+     *
+     * @param limit - The limit value to validate
+     * @throws {InvalidLimitError} If the value is not a positive integer
+     */
+    validateLimit(limit: number): void;
     /**
      * Parse and append field selection parameters
      *
@@ -1298,5 +1540,5 @@ declare class SpatieResponseStrategy implements IResponseStrategy {
     paginate<T extends IPaginatedObject>(response: Record<string, any>, options: ResponseOptions): PaginatedCollection<T>;
 }
 
-export { DriverEnum, FilterOperatorEnum, InvalidLimitError, InvalidPageNumberError, InvalidResourceNameError, KeyNotFoundError, LaravelRequestStrategy, LaravelResponseStrategy, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, provideNgQubee };
+export { DriverEnum, FilterOperatorEnum, InvalidLimitError, InvalidPageNumberError, InvalidResourceNameError, JsonApiRequestStrategy, JsonApiResponseStrategy, KeyNotFoundError, LaravelRequestStrategy, LaravelResponseStrategy, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, provideNgQubee };
 export type { IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };