ng-qubee 3.1.0 → 3.2.0

package/package.json

@@ -2,10 +2,9 @@
   "name": "ng-qubee",
   "author": {
     "name": "Andrea Tantimonaco",
-    "email": "info@andreatantimonaco.me",
     "url": "https://andreatantimonaco.me"
   },
-  "version": "3.1.0",
+  "version": "3.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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 {
@@ -154,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.
  *
@@ -198,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
@@ -280,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) */
@@ -560,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
@@ -595,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
      *
@@ -663,6 +720,13 @@ declare class NgQubeeService {
      * @throws {UnsupportedSortError} If the active driver does not support sorts
      */
     addSort(field: string, order: SortEnum): this;
+    /**
+     * 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)
      *
@@ -738,12 +802,81 @@ declare class NgQubeeService {
      * @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
      *
@@ -794,6 +927,16 @@ declare class NgQubeeService {
      * @throws {UnsupportedSearchError} If the active driver does not support search
      */
     setSearch(search: string): this;
+    /**
+     * 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>;
 }
 
 /**
@@ -844,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
      */
@@ -852,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
@@ -864,6 +1021,8 @@ declare class PaginationService {
     paginate<T extends IPaginatedObject>(response: {
         [key: string]: any;
     }): PaginatedCollection<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PaginationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PaginationService>;
 }
 
 /**
@@ -899,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);
 }
@@ -976,6 +1153,45 @@ 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
  *
@@ -1540,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, JsonApiRequestStrategy, JsonApiResponseStrategy, 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 };