@ethlete/query 6.0.0-next.51 → 6.0.0-next.53

package/types/ethlete-query-ngrx-toolkit.d.ts

@@ -0,0 +1,143 @@
+import * as i0 from '@angular/core';
+import { PipeTransform, Injector } from '@angular/core';
+import { Observable, Subject } from 'rxjs';
+import { AnyQueryCreator, QueryArgsOf, QueryHeaders, ResponseType } from '@ethlete/query';
+
+/** The call state of a toolkit handle, as `@tomtomb/ngrx-toolkit` names it. */
+declare const CallState: {
+    readonly INIT: "INIT";
+    readonly LOADING: "LOADING";
+    readonly SUCCESS: "SUCCESS";
+    readonly ERROR: "ERROR";
+};
+type CallState = (typeof CallState)[keyof typeof CallState];
+/** The error shape of `@tomtomb/ngrx-toolkit`: the HTTP status, the error message and the response body. */
+type ToolkitError<T = unknown> = {
+    status: number | string;
+    message: string;
+    data: T | null;
+};
+type ToolkitActionOptions = {
+    headers?: QueryHeaders;
+    extras?: {
+        skipCache?: boolean;
+    };
+};
+/**
+ * The toolkit-shaped args of a query creator: `queryParams` holds the path params, `params` the query string and
+ * `body` the body, the way `@tomtomb/ngrx-toolkit` action groups named them.
+ */
+type ActionCallArgs<TCreator extends AnyQueryCreator> = {
+    [K in keyof QueryArgsOf<TCreator> as K extends 'pathParams' ? 'queryParams' : K extends 'queryParams' ? 'params' : K extends 'body' ? 'body' : never]: QueryArgsOf<TCreator>[K];
+} & {
+    actionOptions?: ToolkitActionOptions;
+};
+type ToolkitPollingOptions = {
+    intervalDuration: number;
+    killSwitch: Subject<boolean>;
+};
+/** The handle `toolkitCall` returns, shaped like the `MappedEntityState` of `@tomtomb/ngrx-toolkit`. */
+type MappedEntityState<TCreator extends AnyQueryCreator> = {
+    response$: Observable<ResponseType<QueryArgsOf<TCreator>> | null>;
+    cachedResponse$: Observable<ResponseType<QueryArgsOf<TCreator>>>;
+    error$: Observable<ToolkitError | null>;
+    args$: Observable<ActionCallArgs<TCreator> | null>;
+    isInit$: Observable<boolean | null>;
+    isLoading$: Observable<boolean | null>;
+    isSuccess$: Observable<boolean | null>;
+    isError$: Observable<boolean | null>;
+    timestamp$: Observable<number | null>;
+    callState$: Observable<CallState | null>;
+    refresh: () => void;
+    remove: () => void;
+    startPolling: (options: ToolkitPollingOptions) => void;
+    stopPolling: () => void;
+};
+type AnyMappedEntityState = MappedEntityState<any>;
+
+type ExtractFrom<T> = T extends Observable<infer U> ? U : never;
+/** What `suspense` and `suspenseMulti` render for a handle: every stream's current value, plus the handle's methods. */
+type ToolkitSuspenseState<T extends AnyMappedEntityState | null | undefined> = T extends AnyMappedEntityState ? {
+    args: ExtractFrom<T['args$']>;
+    cachedResponse: ExtractFrom<T['cachedResponse$']> | null;
+    callState: ExtractFrom<T['callState$']>;
+    error: ExtractFrom<T['error$']>;
+    isError: ExtractFrom<T['isError$']>;
+    isInit: ExtractFrom<T['isInit$']>;
+    isLoading: ExtractFrom<T['isLoading$']>;
+    isSuccess: ExtractFrom<T['isSuccess$']>;
+    response: ExtractFrom<T['response$']>;
+    timestamp: ExtractFrom<T['timestamp$']>;
+    refresh: () => void;
+    remove: () => void;
+    startPolling: (options: ToolkitPollingOptions) => void;
+    stopPolling: () => void;
+} : T;
+/** Subscribes to a toolkit handle and renders its current state, like the `suspense` pipe of `@tomtomb/ngrx-toolkit`. */
+declare class SuspensePipe implements PipeTransform {
+    transform: <T extends AnyMappedEntityState>(value: T | null | undefined) => ToolkitSuspenseState<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspensePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SuspensePipe, "suspense", true>;
+}
+
+type AnyHandleRecord = Record<string, AnyMappedEntityState | null | undefined>;
+type ToolkitSuspenseMultiState<T extends AnyHandleRecord> = {
+    [K in keyof T]: ToolkitSuspenseState<T[K]>;
+};
+/**
+ * Subscribes to a record of toolkit handles and renders each one's current state, like the `suspenseMulti` pipe of
+ * `@tomtomb/ngrx-toolkit`. Nothing renders until every non-null handle has emitted.
+ */
+declare class SuspenseMultiPipe implements PipeTransform {
+    transform: <T extends AnyHandleRecord>(value: T | null | undefined) => ToolkitSuspenseMultiState<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SuspenseMultiPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SuspenseMultiPipe, "suspenseMulti", true>;
+}
+
+/** Exports the `suspense` and `suspenseMulti` pipes, like the `NgRxToolkitModule` of `@tomtomb/ngrx-toolkit`. */
+declare class NgRxToolkitModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgRxToolkitModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgRxToolkitModule, never, [typeof SuspensePipe, typeof SuspenseMultiPipe], [typeof SuspensePipe, typeof SuspenseMultiPipe]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgRxToolkitModule>;
+}
+
+type ToolkitCallOptions = {
+    /**
+     * The injector the handle's query lives in. Required outside an injection context, which is where a
+     * `providedIn: 'root'` facade calls from; pass the facade's `inject(Injector)`.
+     */
+    injector?: Injector;
+};
+/**
+ * Returns the handle for a creator and args without executing it - the `FacadeBase.select(group, actionId)` of
+ * `@tomtomb/ngrx-toolkit`. Args that build the same request (in any key order, other keys ignored) give the same
+ * handle `toolkitCall` returns, so `toolkitSelect(getTeam, args, { injector }).refresh()` re-runs a request another
+ * component started.
+ */
+declare const toolkitSelect: <TCreator extends AnyQueryCreator>(creator: TCreator, args: ActionCallArgs<TCreator>, options?: ToolkitCallOptions) => MappedEntityState<TCreator>;
+/**
+ * Executes a query creator with toolkit-shaped args and returns its handle - the `FacadeBase.call(group, args)` of
+ * `@tomtomb/ngrx-toolkit`. Every call sends the request again; equal args return the same handle, which lives as
+ * long as the injector.
+ *
+ * @example
+ * ```ts
+ * @Injectable({ providedIn: 'root' })
+ * export class TeamFacade {
+ *   private injector = inject(Injector);
+ *
+ *   getTeam(args: ActionCallArgs<typeof getTeam>) {
+ *     return toolkitCall(getTeam, args, { injector: this.injector });
+ *   }
+ * }
+ * ```
+ */
+declare const toolkitCall: <TCreator extends AnyQueryCreator>(creator: TCreator, args: ActionCallArgs<TCreator>, options?: ToolkitCallOptions) => MappedEntityState<TCreator>;
+
+/** Emits `true` while any of the given loading streams is `true`. Nullish entries are skipped. */
+declare const joinLoading: (observables: (Observable<boolean | null> | null | undefined)[]) => Observable<boolean>;
+/** Emits every non-null error of the given error streams, or `null` when there is none. Nullish entries are skipped. */
+declare const joinErrors: (observables: (Observable<ToolkitError | null> | null | undefined)[]) => Observable<ToolkitError[] | null>;
+
+export { CallState, NgRxToolkitModule, SuspenseMultiPipe, SuspensePipe, joinErrors, joinLoading, toolkitCall, toolkitSelect };
+export type { ActionCallArgs, AnyMappedEntityState, MappedEntityState, ToolkitActionOptions, ToolkitCallOptions, ToolkitError, ToolkitPollingOptions, ToolkitSuspenseMultiState, ToolkitSuspenseState };

package/types/ethlete-query-testing.d.ts

@@ -124,7 +124,7 @@ type AuthTestSetup<TLoginArgs extends {
     ], TFeatures, TBearerData>;
     /** Helper to login a user and flush the HTTP request */
     login: (credentials: TLoginArgs['body'], response: TLoginArgs['response']) => void;
-    /** Helper to trigger a refresh and flush the HTTP request */
+    /** Helper to trigger a refresh and flush the HTTP request. Sends `buildRefreshArgs(token)` when configured, else `{ body: { token } }` */
     refresh: (token: string, response: TRefreshArgs['response']) => void;
     /** Helper to make a secure request that requires authentication */
     makeSecureRequest: (route: string) => void;
@@ -184,9 +184,9 @@ type FakeBroadcastChannelHandle = {
  * Replaces `globalThis.BroadcastChannel` with an in-memory bus.
  *
  * Messages are structured-cloned at post time (so a non-cloneable payload throws exactly like the
- * real API does), delivered on a microtask (never synchronously), and never delivered back to the
- * channel that posted them - all three matching browser behavior. `await Promise.resolve()` in a
- * spec is enough to flush delivery.
+ * real API does), delivered as a task (never synchronously, and after every pending microtask), and
+ * never delivered back to the channel that posted them - all three matching browser behavior. Delivery
+ * does not depend on fake timers; `await flushMultiTabSync()` in a spec flushes it.
  */
 declare const installFakeBroadcastChannel: () => FakeBroadcastChannelHandle;
 type FakeWebLocksHandle = {
@@ -211,9 +211,9 @@ type FakeWebLocksHandle = {
  */
 declare const installFakeWebLocks: () => FakeWebLocksHandle;
 /**
- * Flushes the microtask queue, which is where both fakes schedule their work - message delivery and
- * lock grants. Awaiting it once is enough for a single hop; a grant that has to wait for another
- * tab's release needs one await per hop.
+ * Waits for the fakes' pending work - message delivery (a task) and lock grants (a microtask) - even
+ * under fake timers. Awaiting it once is enough for a single hop; a grant that has to wait for another
+ * tab's release, or a reply to a delivered message, needs one await per hop.
  */
 declare const flushMultiTabSync: () => Promise<void>;
 
@@ -247,7 +247,7 @@ type FakeQueryPersistenceStoreHandle = {
     /**
      * Holds every subsequent `read` pending until {@link flushReads} is called, for testing the window
      * between a cold mount and its hydration (a slow disk, or a mount that happened before startup
-     * finished).
+     * finished). Each held read returns what the store held when it started, as `loadIndex` does.
      */
     deferReads: () => void;
     /** Settles the reads held by {@link deferReads} and stops deferring. */
@@ -295,10 +295,16 @@ type WebSocketTestDouble = {
         event: string;
         data: unknown;
     }[];
-    /** Whether the client asked the socket to connect, and whether it has since disconnected it. */
+    /**
+     * Whether the client asked the socket to connect, and whether it has since disconnected it. `active` is
+     * socket.io's own flag - `false` after a server disconnect or a rejected handshake, until the next
+     * `connect()`; `connectCalls` counts every `connect()`.
+     */
     state: () => {
         connectRequested: boolean;
         disconnected: boolean;
+        active: boolean;
+        connectCalls: number;
     };
     /**
      * Complete the handshake: flush every buffered emit, then turn the client's `isConnected` true. Pass
@@ -307,8 +313,19 @@ type WebSocketTestDouble = {
     serverConnect: (options?: {
         recovered?: boolean;
     }) => void;
-    /** Drop the connection, so `isConnected` turns false. */
-    serverDisconnect: () => void;
+    /**
+     * Drop the connection, so `isConnected` turns false. The default reason, `'transport close'`, is one
+     * socket.io recovers from itself; `'io server disconnect'` is the server kicking the socket, after which
+     * socket.io only reconnects when `connect()` is called again.
+     */
+    serverDisconnect: (options?: {
+        reason?: 'transport close' | 'io server disconnect';
+    }) => void;
+    /**
+     * Reject the handshake the way a server middleware does: the `auth` payload is recorded in
+     * {@link handshakes}, `connect_error` fires and the socket stops reconnecting on its own.
+     */
+    serverRejectHandshake: (message?: string) => void;
     /**
      * Let the ping expire: the socket still reports itself connected, but buffers every emit like socket.io
      * does until it notices and closes. Follow it with {@link serverDisconnect}.