ng-qubee 2.1.0 → 3.0.0

package/types/ng-qubee.d.ts

@@ -0,0 +1,1302 @@
+import * as i0 from '@angular/core';
+import { ModuleWithProviders, EnvironmentProviders, Signal } from '@angular/core';
+import { Observable } from 'rxjs';
+
+interface INormalized {
+    [k: number | string]: number[] | string[];
+}
+
+interface IPaginatedObject {
+    [k: string]: any;
+}
+
+declare class PaginatedCollection<T extends IPaginatedObject> {
+    data: T[];
+    readonly page: number;
+    readonly from?: number | undefined;
+    readonly to?: number | undefined;
+    readonly total?: number | undefined;
+    readonly perPage?: number | undefined;
+    readonly prevPageUrl?: string | undefined;
+    readonly nextPageUrl?: string | undefined;
+    readonly lastPage?: number | undefined;
+    readonly firstPageUrl?: string | undefined;
+    readonly lastPageUrl?: string | undefined;
+    constructor(data: T[], page: number, from?: number | undefined, to?: number | undefined, total?: number | undefined, perPage?: number | undefined, prevPageUrl?: string | undefined, nextPageUrl?: string | undefined, lastPage?: number | undefined, firstPageUrl?: string | undefined, lastPageUrl?: string | undefined);
+    /**
+     * Normalize the collection to a paginated list of ids for state-managed applications.
+     *
+     * This method returns a single key object, where the key is the page number and the associated value is
+     * an array of ids. Each id is fetched by the collection items, looking up for the "id" key. If an id is supplied
+     * to this method, it will be used instead of the default "id" key.
+     *
+     * Please note that in case the key doesn't exist in the collection's item, a KeyNotFoundError is thrown
+     *
+     * @param k A key to use instead of the default "id": this will be searched inside each element of the collection
+     * @returns []
+     * @throws KeyNotFoundItem
+     */
+    normalize(id?: string): INormalized;
+}
+
+/**
+ * Enum representing the available pagination driver types
+ *
+ * Each driver encapsulates the full format knowledge for both
+ * request building (URI generation) and response parsing.
+ */
+declare enum DriverEnum {
+    LARAVEL = "laravel",
+    NESTJS = "nestjs",
+    SPATIE = "spatie"
+}
+
+/**
+ * Configuration interface for customizing response field key names
+ *
+ * Each property maps a logical pagination concept to the actual key name
+ * used in the API response. The defaults depend on the selected driver.
+ *
+ * For the NestJS driver, dot-notation paths are used to access nested values
+ * (e.g., 'meta.currentPage', 'links.next').
+ */
+interface IPaginationConfig {
+    /** Key for the current page number (Laravel: 'current_page', NestJS: 'meta.currentPage') */
+    currentPage?: string;
+    /** Key for the data array (default: 'data') */
+    data?: string;
+    /** Key for the first page URL (Laravel: 'first_page_url', NestJS: 'links.first') */
+    firstPageUrl?: string;
+    /** Key for the "from" item index (Laravel: 'from', NestJS: computed) */
+    from?: string;
+    /** Key for the last page number (Laravel: 'last_page', NestJS: 'meta.totalPages') */
+    lastPage?: string;
+    /** Key for the last page URL (Laravel: 'last_page_url', NestJS: 'links.last') */
+    lastPageUrl?: string;
+    /** Key for the next page URL (Laravel: 'next_page_url', NestJS: 'links.next') */
+    nextPageUrl?: string;
+    /** Key for the base path (Laravel only, default: 'path') */
+    path?: string;
+    /** Key for items per page (Laravel: 'per_page', NestJS: 'meta.itemsPerPage') */
+    perPage?: string;
+    /** Key for the previous page URL (Laravel: 'prev_page_url', NestJS: 'links.previous') */
+    prevPageUrl?: string;
+    /** Key for the "to" item index (Laravel: 'to', NestJS: computed) */
+    to?: string;
+    /** Key for the total item count (Laravel: 'total', NestJS: 'meta.totalItems') */
+    total?: string;
+}
+
+/**
+ * Configuration interface for customizing request query parameter key names
+ *
+ * Each property maps a logical query concept to the actual query parameter name
+ * used in the generated URI. The defaults depend on the selected driver.
+ */
+interface IQueryBuilderConfig {
+    /** Key for the appends parameter (Laravel only, default: 'append') */
+    appends?: string;
+    /** Key for the fields parameter (Laravel: 'fields', NestJS: 'select') */
+    fields?: string;
+    /** Key for the filters parameter (default: 'filter') */
+    filters?: string;
+    /** Key for the includes parameter (Laravel only, default: 'include') */
+    includes?: string;
+    /** Key for the limit parameter (default: 'limit') */
+    limit?: string;
+    /** Key for the page parameter (default: 'page') */
+    page?: string;
+    /** Key for the search parameter (NestJS only, default: 'search') */
+    search?: string;
+    /** Key for the select parameter (NestJS only, default: 'select') */
+    select?: string;
+    /** Key for the sort parameter (Laravel: 'sort', NestJS: 'sortBy') */
+    sort?: string;
+    /** Key for the sortBy parameter (NestJS only, default: 'sortBy') */
+    sortBy?: string;
+}
+
+/**
+ * Main configuration interface for ng-qubee
+ *
+ * Allows configuring the pagination driver and customizing
+ * both request query parameter keys and response field keys.
+ *
+ * @example
+ * ```typescript
+ * const config: IConfig = {
+ *   driver: DriverEnum.NESTJS,
+ *   request: { filters: 'filter', sort: 'sortBy' },
+ *   response: { data: 'data' }
+ * };
+ * ```
+ */
+interface IConfig {
+    /** The pagination driver to use */
+    driver: DriverEnum;
+    /** Custom key names for request query parameters */
+    request?: IQueryBuilderConfig;
+    /** Custom key names for response field mapping */
+    response?: IPaginationConfig;
+}
+
+declare class NgQubeeModule {
+    /**
+     * Configure NgQubee for the root module
+     *
+     * @param config - Configuration object with driver, and optional request and response settings
+     * @returns Module with providers configured for the specified driver
+     */
+    static forRoot(config: IConfig): ModuleWithProviders<NgQubeeModule>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgQubeeModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgQubeeModule, never, never, never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgQubeeModule>;
+}
+
+/**
+ * Sets up providers necessary to enable `NgQubee` functionality for the application.
+ *
+ * @usageNotes
+ *
+ * Basic example with the Laravel driver:
+ * ```
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideNgQubee({ driver: DriverEnum.LARAVEL })]
+ * });
+ * ```
+ *
+ * Spatie driver example:
+ * ```
+ * import { DriverEnum } from 'ng-qubee';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideNgQubee({ driver: DriverEnum.SPATIE })]
+ * });
+ * ```
+ *
+ * NestJS driver example:
+ * ```
+ * import { DriverEnum } from 'ng-qubee';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideNgQubee({ driver: DriverEnum.NESTJS })]
+ * });
+ * ```
+ *
+ * @publicApi
+ * @param config - Configuration object compliant to the IConfig interface
+ * @returns A set of providers to setup NgQubee
+ */
+declare function provideNgQubee(config: IConfig): EnvironmentProviders;
+
+/**
+ * Enum representing the available filter operators for the NestJS driver
+ *
+ * These operators map to the nestjs-paginate filter syntax:
+ * `filter.field=$operator:value`
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
+ */
+declare enum FilterOperatorEnum {
+    BTW = "$btw",
+    CONTAINS = "$contains",
+    EQ = "$eq",
+    GT = "$gt",
+    GTE = "$gte",
+    ILIKE = "$ilike",
+    IN = "$in",
+    LT = "$lt",
+    LTE = "$lte",
+    NOT = "$not",
+    NULL = "$null",
+    SW = "$sw"
+}
+
+declare enum SortEnum {
+    ASC = "asc",
+    DESC = "desc"
+}
+
+interface IFields {
+    [model: string]: string[];
+}
+
+interface IFilters {
+    [k: string]: (string | number | boolean)[];
+}
+
+/**
+ * Represents a filter with an explicit operator for the NestJS driver
+ *
+ * Operator filters produce query parameters in the format:
+ * `filter.field=$operator:value`
+ *
+ * @example
+ * ```typescript
+ * const filter: IOperatorFilter = {
+ *   field: 'age',
+ *   operator: FilterOperatorEnum.GTE,
+ *   values: [18]
+ * };
+ * // Produces: filter.age=$gte:18
+ * ```
+ */
+interface IOperatorFilter {
+    /** The field name to filter on */
+    field: string;
+    /** The filter operator to apply */
+    operator: FilterOperatorEnum;
+    /** The value(s) for the filter */
+    values: (string | number | boolean)[];
+}
+
+interface ISort {
+    field: string;
+    order: SortEnum;
+}
+
+/**
+ * Represents the complete query builder state
+ *
+ * This is a superset that covers the needs of all drivers.
+ * Each driver reads only the fields it needs from this state.
+ */
+interface IQueryBuilderState {
+    /** The base URL to prepend to generated URIs */
+    baseUrl: string;
+    /** Per-model field selection (Spatie only) */
+    fields: IFields;
+    /** Simple key-value filters (Spatie and NestJS) */
+    filters: IFilters;
+    /** Related models to include (Spatie only) */
+    includes: string[];
+    /** Number of items per page (all drivers) */
+    limit: number;
+    /** Filters with explicit operators (NestJS only) */
+    operatorFilters: IOperatorFilter[];
+    /** Current page number (all drivers) */
+    page: number;
+    /** The API resource name for URI generation (all drivers) */
+    resource: string;
+    /** Full-text search term (NestJS only) */
+    search: string;
+    /** Flat field selection (NestJS only) */
+    select: string[];
+    /** Sort configurations (Spatie and NestJS) */
+    sorts: ISort[];
+}
+
+/**
+ * Resolved query parameter key names with defaults applied
+ *
+ * Maps logical query concepts to the actual query parameter names
+ * used in the generated URI. Unset values fall back to defaults.
+ */
+declare class QueryBuilderOptions {
+    readonly appends: string;
+    readonly fields: string;
+    readonly filters: string;
+    readonly includes: string;
+    readonly limit: string;
+    readonly page: string;
+    readonly search: string;
+    readonly select: string;
+    readonly sort: string;
+    readonly sortBy: string;
+    constructor(options: IQueryBuilderConfig);
+}
+
+/**
+ * Strategy interface for building request URIs
+ *
+ * Each driver implements this interface to produce URIs
+ * in the format expected by the corresponding backend.
+ */
+interface IRequestStrategy {
+    /**
+     * Build a URI string from the given query builder state
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The composed URI string
+     */
+    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+}
+
+declare class NestService {
+    /**
+     * Private writable signal that holds the Query Builder state
+     *
+     * @type {IQueryBuilderState}
+     */
+    private _nest;
+    /**
+     * A computed signal that makes readonly the writable signal _nest
+     *
+     * @type {Signal<IQueryBuilderState>}
+     */
+    nest: Signal<IQueryBuilderState>;
+    constructor();
+    /**
+     * Set the base URL for the API
+     *
+     * @param {string} baseUrl - The base URL to prepend to generated URIs
+     * @example
+     * service.baseUrl = 'https://api.example.com';
+     */
+    set baseUrl(baseUrl: string);
+    /**
+     * Set the limit for paginated results
+     * Must be a positive integer greater than 0
+     *
+     * @param {number} limit - The number of items per page
+     * @throws {InvalidLimitError} If limit is not a positive integer
+     * @example
+     * service.limit = 25;
+     */
+    set limit(limit: number);
+    /**
+     * Set the page number for pagination
+     * Must be a positive integer greater than 0
+     *
+     * @param {number} page - The page number to fetch
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @example
+     * service.page = 2;
+     */
+    set page(page: number);
+    /**
+     * Set the resource name for the query
+     * Must be a non-empty string
+     *
+     * @param {string} resource - The API resource name (e.g., 'users', 'posts')
+     * @throws {InvalidResourceNameError} If resource is not a non-empty string
+     * @example
+     * service.resource = 'users';
+     */
+    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
+     *
+     * @param {number} page - The page number to validate
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @private
+     */
+    private _validatePageNumber;
+    /**
+     * Validates that the resource name is a non-empty string
+     *
+     * @param {string} resource - The resource name to validate
+     * @throws {InvalidResourceNameError} If resource is not a non-empty string
+     * @private
+     */
+    private _validateResourceName;
+    /**
+     * Add selectable fields for the given model to the request
+     * Automatically prevents duplicate fields for each model
+     *
+     * @param {IFields} fields - Object mapping model names to arrays of field names
+     * @return {void}
+     * @example
+     * service.addFields({ users: ['id', 'email', 'username'] });
+     * service.addFields({ posts: ['title', 'content'] });
+     */
+    addFields(fields: IFields): void;
+    /**
+     * Add filters to the request
+     * Automatically prevents duplicate filter values for each filter key
+     *
+     * @param {IFilters} filters - Object mapping filter keys to arrays of values
+     * @return {void}
+     * @example
+     * service.addFilters({ id: [1, 2, 3] });
+     * service.addFilters({ status: ['active', 'pending'] });
+     */
+    addFilters(filters: IFilters): void;
+    /**
+     * Add resources to include with the request
+     * Automatically prevents duplicate includes
+     *
+     * @param {string[]} includes - Array of resource names to include in the response
+     * @return {void}
+     * @example
+     * service.addIncludes(['profile', 'posts']);
+     * service.addIncludes(['comments']);
+     */
+    addIncludes(includes: string[]): void;
+    /**
+     * Add filters with explicit operators (NestJS only)
+     * Automatically prevents duplicate operator filters for the same field + operator combination
+     *
+     * @param {IOperatorFilter[]} filters - Array of operator filter configurations
+     * @return {void}
+     * @example
+     * import { FilterOperatorEnum } from 'ng-qubee';
+     * service.addOperatorFilters([{ field: 'age', operator: FilterOperatorEnum.GTE, values: [18] }]);
+     */
+    addOperatorFilters(filters: IOperatorFilter[]): void;
+    /**
+     * Add flat field selection columns (NestJS only)
+     * Automatically prevents duplicate select fields
+     *
+     * @param {string[]} fields - Array of column names to select
+     * @return {void}
+     * @example
+     * service.addSelect(['id', 'name', 'email']);
+     */
+    addSelect(fields: string[]): void;
+    /**
+     * Add a field that should be used for sorting data
+     *
+     * @param {ISort} sort - Sort configuration with field name and order (ASC/DESC)
+     * @return {void}
+     * @example
+     * import { SortEnum } from 'ng-qubee';
+     * service.addSort({ field: 'created_at', order: SortEnum.DESC });
+     * service.addSort({ field: 'name', order: SortEnum.ASC });
+     */
+    addSort(sort: ISort): void;
+    /**
+     * Remove fields for the given model
+     * Uses deep cloning to prevent mutations to the original state
+     *
+     * @param {IFields} fields - Object mapping model names to arrays of field names to remove
+     * @return {void}
+     * @example
+     * service.deleteFields({ users: ['email'] });
+     * service.deleteFields({ posts: ['content', 'body'] });
+     */
+    deleteFields(fields: IFields): void;
+    /**
+     * Remove filters from the request
+     * Uses deep cloning to prevent mutations to the original state
+     *
+     * @param {...string[]} filters - Filter keys to remove
+     * @return {void}
+     * @example
+     * service.deleteFilters('id');
+     * service.deleteFilters('status', 'type');
+     */
+    deleteFilters(...filters: string[]): void;
+    /**
+     * Remove includes from the request
+     *
+     * @param {...string[]} includes - Include names to remove
+     * @return {void}
+     * @example
+     * service.deleteIncludes('profile');
+     * service.deleteIncludes('posts', 'comments');
+     */
+    deleteIncludes(...includes: string[]): void;
+    /**
+     * Remove operator filters by field name (NestJS only)
+     *
+     * @param {...string[]} fields - Field names of operator filters to remove
+     * @return {void}
+     * @example
+     * service.deleteOperatorFilters('age');
+     * service.deleteOperatorFilters('price', 'quantity');
+     */
+    deleteOperatorFilters(...fields: string[]): void;
+    /**
+     * Remove the search term from the state (NestJS only)
+     *
+     * @return {void}
+     * @example
+     * service.deleteSearch();
+     */
+    deleteSearch(): void;
+    /**
+     * Remove flat field selections from the state (NestJS only)
+     *
+     * @param {...string[]} fields - Field names to remove from selection
+     * @return {void}
+     * @example
+     * service.deleteSelect('email');
+     * service.deleteSelect('name', 'email');
+     */
+    deleteSelect(...fields: string[]): void;
+    /**
+     * Remove sorts from the request by field name
+     *
+     * @param {...string[]} sorts - Field names of sorts to remove
+     * @return {void}
+     * @example
+     * service.deleteSorts('created_at');
+     * service.deleteSorts('name', 'created_at');
+     */
+    deleteSorts(...sorts: string[]): void;
+    /**
+     * Set the full-text search term (NestJS only)
+     *
+     * @param {string} search - The search term
+     * @return {void}
+     * @example
+     * service.setSearch('john doe');
+     */
+    setSearch(search: string): void;
+    /**
+     * Reset the query builder state to initial values
+     * Clears all fields, filters, includes, sorts, and resets pagination
+     *
+     * @return {void}
+     * @example
+     * service.reset();
+     */
+    reset(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NestService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NestService>;
+}
+
+declare class NgQubeeService {
+    private _nestService;
+    /**
+     * The active pagination driver
+     */
+    private _driver;
+    /**
+     * Resolved query parameter key name options
+     */
+    private _options;
+    /**
+     * The request strategy that builds URIs for the active driver
+     */
+    private _requestStrategy;
+    /**
+     * Internal BehaviorSubject that holds the latest generated URI
+     */
+    private _uri$;
+    /**
+     * Observable that emits non-empty generated URIs
+     */
+    uri$: Observable<string>;
+    constructor(_nestService: NestService, requestStrategy: IRequestStrategy, driver: DriverEnum, options?: IQueryBuilderConfig);
+    /**
+     * Assert that the active driver is one of the allowed drivers
+     *
+     * @param allowed - The allowed drivers
+     * @param error - The error to throw if the driver is not allowed
+     * @throws The provided error if the active driver is not in the allowed list
+     */
+    private _assertDriver;
+    /**
+     * Add fields to the select statement for the given model (Spatie only)
+     *
+     * @param model - Model that holds the fields
+     * @param fields - Fields to select
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    addFields(model: string, fields: string[]): this;
+    /**
+     * Add a filter with the given value(s) (Spatie and NestJS only)
+     *
+     * Produces: `filter[field]=value` (Spatie) or `filter.field=value` (NestJS)
+     *
+     * @param {string} field - Name of the field to filter
+     * @param {(string | number | boolean)[]} values - The needle(s)
+     * @returns {this}
+     * @throws {UnsupportedFilterError} If the active driver does not support filters
+     */
+    addFilter(field: string, ...values: (string | number | boolean)[]): this;
+    /**
+     * Add a filter with an explicit operator (NestJS only)
+     *
+     * Produces: `filter.field=$operator:value`
+     *
+     * @param {string} field - Name of the field to filter
+     * @param {FilterOperatorEnum} operator - The filter operator to apply
+     * @param {(string | number | boolean)[]} values - The value(s) for the filter
+     * @returns {this}
+     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
+     */
+    addFilterOperator(field: string, operator: FilterOperatorEnum, ...values: (string | number | boolean)[]): this;
+    /**
+     * Add related entities to include in the request (Spatie only)
+     *
+     * @param {string[]} models - Models to include
+     * @returns {this}
+     * @throws {UnsupportedIncludesError} If the active driver does not support includes
+     */
+    addIncludes(...models: string[]): this;
+    /**
+     * Add flat field selection (NestJS only)
+     *
+     * Produces: `select=col1,col2`
+     *
+     * @param {string[]} fields - Fields to select
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     */
+    addSelect(...fields: string[]): this;
+    /**
+     * Add a field with a sort criteria (Spatie and NestJS only)
+     *
+     * @param field - Field to use for sorting
+     * @param {SortEnum} order - A value from the SortEnum enumeration
+     * @returns {this}
+     * @throws {UnsupportedSortError} If the active driver does not support sorts
+     */
+    addSort(field: string, order: SortEnum): this;
+    /**
+     * Delete selected fields for the given models in the current query builder state (Spatie only)
+     *
+     * ```
+     * ngQubeeService.deleteFields({
+     *   users: ['email', 'password'],
+     *   address: ['zipcode']
+     * });
+     * ```
+     *
+     * @param {IFields} fields - Object mapping model names to field arrays to remove
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    deleteFields(fields: IFields): this;
+    /**
+     * Delete selected fields for the given model in the current query builder state (Spatie only)
+     *
+     * ```
+     * ngQubeeService.deleteFieldsByModel('users', 'email', 'password');
+     * ```
+     *
+     * @param model - Model that holds the fields
+     * @param {string[]} fields - Fields to delete from the state
+     * @returns {this}
+     * @throws {UnsupportedFieldSelectionError} If the active driver does not support per-model field selection
+     */
+    deleteFieldsByModel(model: string, ...fields: string[]): this;
+    /**
+     * Remove given filters from the query builder state (Spatie and NestJS only)
+     *
+     * @param {string[]} filters - Filters to remove
+     * @returns {this}
+     * @throws {UnsupportedFilterError} If the active driver does not support filters
+     */
+    deleteFilters(...filters: string[]): this;
+    /**
+     * Remove selected related models from the query builder state (Spatie only)
+     *
+     * @param {string[]} includes - Models to remove
+     * @returns {this}
+     * @throws {UnsupportedIncludesError} If the active driver does not support includes
+     */
+    deleteIncludes(...includes: string[]): this;
+    /**
+     * Remove operator filters by field name (NestJS only)
+     *
+     * @param {string[]} fields - Field names of operator filters to remove
+     * @returns {this}
+     * @throws {UnsupportedFilterOperatorError} If the active driver does not support filter operators
+     */
+    deleteOperatorFilters(...fields: string[]): this;
+    /**
+     * Remove search term from the query builder state (NestJS only)
+     *
+     * @returns {this}
+     * @throws {UnsupportedSearchError} If the active driver does not support search
+     */
+    deleteSearch(): this;
+    /**
+     * Remove flat field selections from the query builder state (NestJS only)
+     *
+     * @param {string[]} fields - Fields to remove from selection
+     * @returns {this}
+     * @throws {UnsupportedSelectError} If the active driver does not support flat field selection
+     */
+    deleteSelect(...fields: string[]): this;
+    /**
+     * Remove sort rules from the query builder state (Spatie and NestJS only)
+     *
+     * @param sorts - Fields used for sorting to remove
+     * @returns {this}
+     * @throws {UnsupportedSortError} If the active driver does not support sorts
+     */
+    deleteSorts(...sorts: string[]): 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>;
+    /**
+     * Clear the current state and reset the Query Builder to a fresh, clean condition
+     *
+     * @returns {this}
+     */
+    reset(): this;
+    /**
+     * Set the base URL to use for composing the address
+     *
+     * @param {string} baseUrl - The base URL
+     * @returns {this}
+     */
+    setBaseUrl(baseUrl: string): this;
+    /**
+     * Set the items per page number
+     *
+     * @param limit - Number of items per page
+     * @returns {this}
+     */
+    setLimit(limit: number): this;
+    /**
+     * Set the page that the backend will use to paginate the result set
+     *
+     * @param page - Page number
+     * @returns {this}
+     */
+    setPage(page: number): this;
+    /**
+     * Set the API resource to run the query against
+     *
+     * @param {string} resource - Resource name (e.g. 'users' produces /users)
+     * @returns {this}
+     */
+    setResource(resource: string): this;
+    /**
+     * Set the search term for full-text search (NestJS only)
+     *
+     * Produces: `search=term`
+     *
+     * @param {string} search - The search term
+     * @returns {this}
+     * @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>;
+}
+
+/**
+ * Resolved response field key names with defaults applied
+ *
+ * Maps logical pagination concepts to the actual key names
+ * used in the API response. Unset values fall back to Laravel defaults.
+ *
+ * For NestJS responses, use dot-notation paths:
+ * ```typescript
+ * new ResponseOptions({
+ *   currentPage: 'meta.currentPage',
+ *   total: 'meta.totalItems'
+ * });
+ * ```
+ */
+declare class ResponseOptions {
+    readonly currentPage: string;
+    readonly data: string;
+    readonly firstPageUrl: string;
+    readonly from: string;
+    readonly lastPage: string;
+    readonly lastPageUrl: string;
+    readonly nextPageUrl: string;
+    readonly path: string;
+    readonly perPage: string;
+    readonly prevPageUrl: string;
+    readonly to: string;
+    readonly total: string;
+    constructor(options: IPaginationConfig);
+}
+
+/**
+ * Strategy interface for parsing paginated API responses
+ *
+ * Each driver implements this interface to parse responses
+ * from the corresponding backend format into a PaginatedCollection.
+ */
+interface IResponseStrategy {
+    /**
+     * Parse a raw API response into a typed 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, unknown>, options: ResponseOptions): PaginatedCollection<T>;
+}
+
+declare class PaginationService {
+    /**
+     * Resolved response key name options
+     */
+    private _options;
+    /**
+     * The response strategy that parses responses for the active driver
+     */
+    private _responseStrategy;
+    constructor(responseStrategy: IResponseStrategy, options?: IPaginationConfig);
+    /**
+     * Transform a raw API response into a typed PaginatedCollection
+     *
+     * Delegates to the active driver's response strategy for parsing.
+     *
+     * @param response - The raw API response object
+     * @returns A typed PaginatedCollection instance
+     */
+    paginate<T extends IPaginatedObject>(response: {
+        [key: string]: any;
+    }): PaginatedCollection<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, [null, { optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PaginationService>;
+}
+
+declare class InvalidLimitError extends Error {
+    constructor(limit: number);
+}
+
+declare class InvalidPageNumberError extends Error {
+    constructor(page: number);
+}
+
+/**
+ * Error thrown when an invalid resource name is provided
+ *
+ * Resource name must be a non-empty string.
+ */
+declare class InvalidResourceNameError extends Error {
+    constructor(resource: string | null | undefined);
+}
+
+declare class KeyNotFoundError extends Error {
+    constructor(key: string);
+}
+
+declare class UnselectableModelError extends Error {
+    constructor(model: string);
+}
+
+/**
+ * Error thrown when per-model field selection is attempted with a driver that does not support it
+ *
+ * Per-model field selection is only supported by the Spatie driver.
+ * Use `addSelect()` for NestJS flat field selection.
+ */
+declare class UnsupportedFieldSelectionError extends Error {
+    constructor();
+}
+
+/**
+ * Error thrown when filters are attempted with a driver that does not support them
+ *
+ * Filters are only supported by the Spatie and NestJS drivers.
+ */
+declare class UnsupportedFilterError extends Error {
+    constructor();
+}
+
+/**
+ * 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.
+ */
+declare class UnsupportedFilterOperatorError extends Error {
+    constructor();
+}
+
+/**
+ * Error thrown when includes are attempted with a driver that does not support them
+ *
+ * Includes are only supported by the Spatie driver.
+ */
+declare class UnsupportedIncludesError extends Error {
+    constructor();
+}
+
+/**
+ * Error thrown when search is attempted with a driver that does not support it
+ *
+ * Search is only supported by the NestJS driver.
+ */
+declare class UnsupportedSearchError extends Error {
+    constructor();
+}
+
+/**
+ * Error thrown when flat field selection is attempted with a driver that does not support it
+ *
+ * Flat field selection is only supported by the NestJS driver.
+ * Use `addFields()` for Spatie per-model field selection.
+ */
+declare class UnsupportedSelectError extends Error {
+    constructor();
+}
+
+/**
+ * Error thrown when sorts are attempted with a driver that does not support them
+ *
+ * Sorts are only supported by the Spatie and NestJS drivers.
+ */
+declare class UnsupportedSortError extends Error {
+    constructor();
+}
+
+interface INestState {
+    nest: IQueryBuilderState;
+}
+
+interface IPage {
+}
+
+/**
+ * Request strategy for the Laravel (pagination-only) driver
+ *
+ * Generates simple pagination URIs:
+ * - `/{resource}?limit=N&page=N`
+ *
+ * Filters, sorts, fields, includes, search, and select in state are ignored.
+ */
+declare class LaravelRequestStrategy implements IRequestStrategy {
+    /**
+     * Build a pagination-only URI from the given state
+     *
+     * @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;
+}
+
+/**
+ * Response strategy for the Laravel (pagination-only) driver
+ *
+ * Parses flat Laravel pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "current_page": 1,
+ *   "total": 100,
+ *   "per_page": 15,
+ *   "from": 1,
+ *   "to": 15,
+ *   ...
+ * }
+ * ```
+ */
+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>;
+}
+
+/**
+ * Request strategy for the NestJS (nestjs-paginate) driver
+ *
+ * Generates URIs in the NestJS paginate format:
+ * - Simple filters: `filter.field=value`
+ * - Operator filters: `filter.field=$operator:value`
+ * - Sorts: `sortBy=field1:DESC,field2:ASC`
+ * - Select: `select=col1,col2`
+ * - Search: `search=term`
+ * - Pagination: `limit=N&page=N`
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
+ */
+declare class NestjsRequestStrategy implements IRequestStrategy {
+    /**
+     * Accumulator for composing the URI string
+     */
+    private _uri;
+    /**
+     * Build a URI string from the given state using the NestJS paginate format
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The composed URI string
+     * @throws Error if model is not set
+     */
+    buildUri(state: IQueryBuilderState, options: QueryBuilderOptions): string;
+    /**
+     * Parse and append simple filter parameters
+     *
+     * Generates: `filter.field=value1,value2` for each filter
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parseFilters;
+    /**
+     * Parse and append the limit parameter
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parseLimit;
+    /**
+     * Parse and append operator filter parameters
+     *
+     * Groups operator filters by field and generates:
+     * - Single value: `filter.field=$operator:value`
+     * - Multiple values ($in, $btw): `filter.field=$operator:val1,val2`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parseOperatorFilters;
+    /**
+     * Parse and append the page parameter
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parsePage;
+    /**
+     * Parse and append the search parameter
+     *
+     * Generates: `search=term`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parseSearch;
+    /**
+     * Parse and append the select parameter
+     *
+     * Generates: `select=col1,col2`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    private _parseSelect;
+    /**
+     * Parse and append sort parameters
+     *
+     * Generates: `sortBy=field1:DESC,field2:ASC`
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     */
+    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 NestJS (nestjs-paginate) driver
+ *
+ * Parses nested NestJS pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "meta": {
+ *     "currentPage": 1,
+ *     "totalItems": 100,
+ *     "itemsPerPage": 10,
+ *     "totalPages": 10
+ *   },
+ *   "links": {
+ *     "first": "url",
+ *     "previous": "url",
+ *     "next": "url",
+ *     "last": "url",
+ *     "current": "url"
+ *   }
+ * }
+ * ```
+ *
+ * @see https://github.com/ppetzold/nestjs-paginate
+ */
+declare class NestjsResponseStrategy implements IResponseStrategy {
+    /**
+     * Parse a nested NestJS pagination response into a PaginatedCollection
+     *
+     * Supports dot-notation key paths for accessing nested values.
+     * Computes `from` and `to` from `currentPage` and `itemsPerPage` 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.currentPage').
+     *
+     * @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 Spatie Query Builder driver
+ *
+ * Generates URIs in the Spatie format:
+ * - Fields: `fields[model]=col1,col2`
+ * - Filters: `filter[field]=value`
+ * - Includes: `include=model1,model2`
+ * - Sorts: `sort=-field1,field2` (- prefix = DESC)
+ * - Pagination: `limit=N&page=N`
+ *
+ * @see https://spatie.be/docs/laravel-query-builder
+ */
+declare class SpatieRequestStrategy implements IRequestStrategy {
+    /**
+     * Accumulator for composing the URI string
+     */
+    private _uri;
+    /**
+     * Build a URI string from the given state using the Spatie 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;
+    /**
+     * 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 model 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=model1,model2`
+     *
+     * @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 the limit parameter
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated limit parameter string
+     */
+    private _parseLimit;
+    /**
+     * Parse and append the page parameter
+     *
+     * @param state - The current query builder state
+     * @param options - The query parameter key name configuration
+     * @returns The generated page parameter string
+     */
+    private _parsePage;
+    /**
+     * 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 Spatie Query Builder driver
+ *
+ * Parses flat Laravel pagination responses:
+ * ```json
+ * {
+ *   "data": [...],
+ *   "current_page": 1,
+ *   "total": 100,
+ *   "per_page": 15,
+ *   "from": 1,
+ *   "to": 15,
+ *   ...
+ * }
+ * ```
+ *
+ * @see https://spatie.be/docs/laravel-query-builder
+ */
+declare class SpatieResponseStrategy 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>;
+}
+
+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 type { IConfig, IFields, IFilters, INestState, IOperatorFilter, IPage, IPaginatedObject, IPaginationConfig, IQueryBuilderConfig, IQueryBuilderState, IRequestStrategy, IResponseStrategy, ISort };