ng-qubee 3.0.0 → 3.2.0

package/types/ng-qubee.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { ModuleWithProviders, EnvironmentProviders, Signal } from '@angular/core';
+import { ModuleWithProviders, Provider, EnvironmentProviders, Signal, InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 
 interface INormalized {
@@ -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"
@@ -153,6 +154,18 @@ declare class NgQubeeModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<NgQubeeModule>;
 }
 
+/**
+ * Build the core provider list shared by `provideNgQubee()` and
+ * `NgQubeeModule.forRoot()`
+ *
+ * Exposes the driver, strategies, and options via injection tokens so that
+ * consumers can request a component-scoped instance of the services through
+ * `provideNgQubeeInstance()`.
+ *
+ * @param config - Configuration object compliant to the IConfig interface
+ * @returns An array of Providers for the environment injector
+ */
+declare function buildNgQubeeProviders(config: IConfig): Provider[];
 /**
  * Sets up providers necessary to enable `NgQubee` functionality for the application.
  *
@@ -174,6 +187,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';
@@ -188,6 +210,34 @@ declare class NgQubeeModule {
  * @returns A set of providers to setup NgQubee
  */
 declare function provideNgQubee(config: IConfig): EnvironmentProviders;
+/**
+ * Providers for a component-scoped NgQubee instance
+ *
+ * Use this inside a standalone component's `providers: [...]` to get a
+ * dedicated `NgQubeeService` (and its `NestService` / `PaginationService`
+ * collaborators) whose query-builder and pagination state does not bleed
+ * with the app-wide shared instance provided by `provideNgQubee()`.
+ *
+ * @usageNotes
+ *
+ * ```
+ * @Component({
+ *   standalone: true,
+ *   providers: [...provideNgQubeeInstance()]
+ * })
+ * export class MyFeatureComponent {
+ *   constructor(private _qb: NgQubeeService) {}
+ * }
+ * ```
+ *
+ * The driver, strategies, and options are inherited from the environment
+ * injector (`provideNgQubee()` at root), so only the service instances are
+ * re-created at the component level.
+ *
+ * @publicApi
+ * @returns A provider array to spread into a component's `providers`
+ */
+declare function provideNgQubeeInstance(): Provider[];
 
 /**
  * Enum representing the available filter operators for the NestJS driver
@@ -270,6 +320,10 @@ interface IQueryBuilderState {
     filters: IFilters;
     /** Related models to include (Spatie only) */
     includes: string[];
+    /** Whether the last paginated response has synced `lastPage` into state */
+    isLastPageKnown: boolean;
+    /** Last page number known from the most recent paginated response; only meaningful when `isLastPageKnown` is true */
+    lastPage: number;
     /** Number of items per page (all drivers) */
     limit: number;
     /** Filters with explicit operators (NestJS only) */
@@ -321,6 +375,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 +412,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 +444,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
      *
@@ -544,6 +604,19 @@ declare class NestService {
      * service.setSearch('john doe');
      */
     setSearch(search: string): void;
+    /**
+     * Atomically record the `lastPage` value from a paginated response and
+     * flip `isLastPageKnown` to `true`
+     *
+     * Called exclusively by `PaginationService.paginate()` as part of the
+     * auto-sync contract; not intended to be invoked by consumers directly.
+     * Keeping the two fields under a single write guarantees they cannot
+     * drift out of sync.
+     *
+     * @param {number} lastPage - The last page number parsed from the most recent paginated response
+     * @return {void}
+     */
+    syncLastPage(lastPage: number): void;
     /**
      * Reset the query builder state to initial values
      * Clears all fields, filters, includes, sorts, and resets pagination
@@ -579,7 +652,7 @@ declare class NgQubeeService {
      * Observable that emits non-empty generated URIs
      */
     uri$: Observable<string>;
-    constructor(_nestService: NestService, requestStrategy: IRequestStrategy, driver: DriverEnum, options?: IQueryBuilderConfig);
+    constructor(_nestService: NestService, requestStrategy: IRequestStrategy, driver: DriverEnum, options?: QueryBuilderOptions);
     /**
      * Assert that the active driver is one of the allowed drivers
      *
@@ -589,7 +662,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 +671,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 +694,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 +712,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 +721,14 @@ declare class NgQubeeService {
      */
     addSort(field: string, order: SortEnum): this;
     /**
-     * Delete selected fields for the given models in the current query builder state (Spatie only)
+     * Get the current page number
+     *
+     * @remarks Always safe to call. Thin accessor over the internal state's `page` field.
+     * @returns The current page number
+     */
+    currentPage(): number;
+    /**
+     * Delete selected fields for the given models in the current query builder state (JSON:API and Spatie only)
      *
      * ```
      * ngQubeeService.deleteFields({
@@ -663,7 +743,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 +756,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 +764,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,19 +795,88 @@ 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}
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     deleteSorts(...sorts: string[]): this;
+    /**
+     * Navigate to the first page (page 1)
+     *
+     * @remarks Never throws. Idempotent when already on page 1.
+     * @returns {this}
+     */
+    firstPage(): this;
     /**
      * Generate a URI accordingly to the given data and active driver
      *
      * @returns {Observable<string>} An observable that emits the generated URI
      */
     generateUri(): Observable<string>;
+    /**
+     * Navigate directly to the specified page
+     *
+     * Validates integer/positive via the existing `setPage` path, and
+     * additionally rejects values that exceed `state.lastPage` when
+     * pagination bounds are known.
+     *
+     * @param n - Target page number
+     * @returns {this}
+     * @throws {InvalidPageNumberError} If `n` is not a positive integer, or if `n > state.lastPage` when `state.isLastPageKnown` is true
+     */
+    goToPage(n: number): this;
+    /**
+     * Check whether a next page exists
+     *
+     * @remarks Template-safe. Returns `true` when pagination bounds are unknown (conservative default — keeps a "Next" button enabled before the first `paginate()` call).
+     * @returns `true` if `state.page < state.lastPage` when bounds are known, or `true` when bounds are unknown
+     */
+    hasNextPage(): boolean;
+    /**
+     * Check whether a previous page exists
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page > 1`
+     */
+    hasPreviousPage(): boolean;
+    /**
+     * Check whether the current page is the first page
+     *
+     * @remarks Always safe. Does not require a synced paginated response.
+     * @returns `true` if `state.page === 1`
+     */
+    isFirstPage(): boolean;
+    /**
+     * Check whether the current page is the last page
+     *
+     * @remarks Template-safe. Returns `false` when pagination bounds are unknown (no paginated response has been synced yet) — keeps "Next" navigation unblocked until the first `paginate()` call syncs.
+     * @returns `true` only when `state.isLastPageKnown` and `state.page === state.lastPage`
+     */
+    isLastPage(): boolean;
+    /**
+     * Navigate to the last page known from the most recent paginated response
+     *
+     * @remarks Requires at least one `PaginationService.paginate()` call to have synced `state.lastPage`. Before that, the bound is unknown and this method throws.
+     * @returns {this}
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    lastPage(): this;
+    /**
+     * Navigate to the next page
+     *
+     * @remarks Never throws. Idempotent at the known last page (no-op). Pair with `hasNextPage()` for a disable-state binding.
+     * @returns {this}
+     */
+    nextPage(): this;
+    /**
+     * Navigate to the previous page
+     *
+     * @remarks Never throws. Idempotent at page 1 (floored). Pair with `hasPreviousPage()` for a disable-state binding.
+     * @returns {this}
+     */
+    previousPage(): this;
     /**
      * Clear the current state and reset the Query Builder to a fresh, clean condition
      *
@@ -744,8 +893,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,7 +927,15 @@ 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; }]>;
+    /**
+     * Get the total number of pages reported by the most recent paginated response
+     *
+     * @remarks Throws when called before any `paginate()` has synced a value. For a non-throwing read in a template, read `nest().isLastPageKnown` first as a guard.
+     * @returns The last page number
+     * @throws {PaginationNotSyncedError} If `state.isLastPageKnown` is false (no paginated response has been synced yet)
+     */
+    totalPages(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgQubeeService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NgQubeeService>;
 }
 
@@ -824,6 +987,12 @@ interface IResponseStrategy {
 }
 
 declare class PaginationService {
+    /**
+     * The NestService instance that owns the query-builder state for this
+     * PaginationService's scope (environment-level by default, or
+     * component-level when used via `provideNgQubeeInstance()`)
+     */
+    private _nestService;
     /**
      * Resolved response key name options
      */
@@ -832,11 +1001,19 @@ declare class PaginationService {
      * The response strategy that parses responses for the active driver
      */
     private _responseStrategy;
-    constructor(responseStrategy: IResponseStrategy, options?: IPaginationConfig);
+    constructor(nestService: NestService, responseStrategy: IResponseStrategy, options?: ResponseOptions);
     /**
      * Transform a raw API response into a typed PaginatedCollection
      *
-     * Delegates to the active driver's response strategy for parsing.
+     * Delegates to the active driver's response strategy for parsing, then
+     * auto-syncs the parsed `page` and `lastPage` back into `NestService`
+     * so pagination navigation helpers on `NgQubeeService` can operate
+     * against the live server-reported bounds without consumer bookkeeping.
+     *
+     * @remarks
+     * `lastPage` is only synced when the response yields a positive integer.
+     * Server-emitted `0` (empty collection edge case) and absent fields are
+     * treated as "no useful info" and leave `isLastPageKnown: false`.
      *
      * @param response - The raw API response object
      * @returns A typed PaginatedCollection instance
@@ -844,12 +1021,24 @@ declare class PaginationService {
     paginate<T extends IPaginatedObject>(response: {
         [key: string]: any;
     }): PaginatedCollection<T>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, [null, { optional: true; }]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, never>;
     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 {
@@ -869,6 +1058,24 @@ declare class KeyNotFoundError extends Error {
     constructor(key: string);
 }
 
+/**
+ * Thrown when a pagination helper that needs `state.lastPage` is called
+ * before `PaginationService.paginate()` has ever synced a value.
+ *
+ * Examples: `NgQubeeService.lastPage()`, `NgQubeeService.totalPages()`.
+ *
+ * Safe-for-templates predicates (`isLastPage`, `hasNextPage`, etc.) do not
+ * throw and return conservative defaults instead.
+ */
+declare class PaginationNotSyncedError extends Error {
+    /**
+     * @param action - Short imperative describing what the caller was trying
+     * to do (e.g. "navigate to last page", "read totalPages"). Surfaced in
+     * the error message so the cause is obvious at the call site.
+     */
+    constructor(action: string);
+}
+
 declare class UnselectableModelError extends Error {
     constructor(model: string);
 }
@@ -946,6 +1153,227 @@ interface INestState {
 interface IPage {
 }
 
+/**
+ * Injection token for the active pagination driver
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` from the
+ * user-supplied `IConfig.driver`. Services read it to gate driver-specific
+ * behavior (e.g. `NgQubeeService._assertDriver`).
+ */
+declare const NG_QUBEE_DRIVER: InjectionToken<DriverEnum>;
+/**
+ * Injection token for the resolved request URI strategy
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` based on the
+ * active driver. Used by `NgQubeeService` to build request URIs.
+ */
+declare const NG_QUBEE_REQUEST_STRATEGY: InjectionToken<IRequestStrategy>;
+/**
+ * Injection token for the resolved request query-parameter key options
+ *
+ * Provided as a fully-built `QueryBuilderOptions` instance. `provideNgQubee()`
+ * constructs it from `IConfig.request`; consumers don't interact with this
+ * token directly.
+ */
+declare const NG_QUBEE_REQUEST_OPTIONS: InjectionToken<QueryBuilderOptions>;
+/**
+ * Injection token for the resolved response parsing strategy
+ *
+ * Provided by `provideNgQubee()` / `NgQubeeModule.forRoot()` based on the
+ * active driver. Used by `PaginationService` to parse paginated responses.
+ */
+declare const NG_QUBEE_RESPONSE_STRATEGY: InjectionToken<IResponseStrategy>;
+/**
+ * Injection token for the resolved response field-key options
+ *
+ * Provided as a fully-built `ResponseOptions` instance (or a driver-specific
+ * subclass like `JsonApiResponseOptions` / `NestjsResponseOptions`).
+ * `provideNgQubee()` constructs the correct variant from `IConfig.response`.
+ */
+declare const NG_QUBEE_RESPONSE_OPTIONS: InjectionToken<ResponseOptions>;
+
+/**
+ * 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 +1392,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 +1458,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 +1646,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 +1756,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, NG_QUBEE_DRIVER, NG_QUBEE_REQUEST_OPTIONS, NG_QUBEE_REQUEST_STRATEGY, NG_QUBEE_RESPONSE_OPTIONS, NG_QUBEE_RESPONSE_STRATEGY, NestjsRequestStrategy, NestjsResponseStrategy, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationNotSyncedError, PaginationService, SortEnum, SpatieRequestStrategy, SpatieResponseStrategy, UnselectableModelError, UnsupportedFieldSelectionError, UnsupportedFilterError, UnsupportedFilterOperatorError, UnsupportedIncludesError, UnsupportedSearchError, UnsupportedSelectError, UnsupportedSortError, buildNgQubeeProviders, provideNgQubee, provideNgQubeeInstance };
 export type { IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };