@ethlete/query 6.0.0-next.3 → 6.0.0-next.31

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

@@ -1,10 +1,10 @@
-import { AnyCreateQueryClientResult, QueryClientRef, createGetQuery, createPostQuery, createPutQuery, createPatchQuery, createDeleteQuery, BearerAuthProviderFeatureContext, AnyQueryBuilder, BearerAuthProvider, AuthQueryBuilder, TokenRefreshQueryBuilder, TokenRefreshQueryConfig } from '@ethlete/query';
+import { AnyCreateQueryClientResult, QueryClientRef, createGetQuery, createPostQuery, createPutQuery, createPatchQuery, createDeleteQuery, BearerAuthProviderFeatureContext, AnyQueryBuilder, BearerAuthProvider, AuthQueryBuilder, TokenRefreshQueryBuilder, TokenRefreshQueryConfig, QueryPersistenceAdapter, PersistedQueryEntry, WebSocketClientIo, SocketMessageView } from '@ethlete/query';
 import { HttpClient } from '@angular/common/http';
 import { HttpTestingController } from '@angular/common/http/testing';
 import { Injector } from '@angular/core';
 
 type QueryTestSetup = {
-    queryClient: NonNullable<ReturnType<AnyCreateQueryClientResult[1]>>;
+    queryClient: NonNullable<ReturnType<AnyCreateQueryClientResult['inject']>>;
     queryClientRef: QueryClientRef;
     httpClient: HttpClient;
     httpTesting: HttpTestingController;
@@ -70,18 +70,12 @@ type AuthTestSetupConfig<TLoginArgs extends {
         accessToken: string;
         refreshToken: string;
     };
+    /** Builds the refresh request from the refresh token. See TokenRefreshQueryConfig for details */
+    buildRefreshArgs?: TokenRefreshQueryConfig<TRefreshArgs>['buildArgs'];
     /** Feature builders for additional auth functionality */
     features?: [...TFeatures];
     /** Custom bearer decrypt function for testing */
     bearerDecryptFn?: (token: string) => TBearerData;
-    /** Whether to disable multi-tab sync. Default: false */
-    multiTabSync?: false | {
-        enabled?: boolean;
-        channelName?: string;
-        syncTokens?: boolean;
-        syncLogout?: boolean;
-        leaderElection?: boolean;
-    };
     /** Refresh strategy configuration. See TokenRefreshQueryConfig for details */
     refreshStrategy?: TokenRefreshQueryConfig<TRefreshArgs>['refreshStrategy'];
     /** Minimum refresh interval in milliseconds */
@@ -90,6 +84,8 @@ type AuthTestSetupConfig<TLoginArgs extends {
     refreshIfExpired?: boolean;
     /** Property name for expiration in JWT */
     expiresInPropertyName?: string;
+    /** What to do when the refresh query fails for good. Defaults to the provider's own policy */
+    onRefreshFailure?: TokenRefreshQueryConfig<TRefreshArgs>['onRefreshFailure'];
 };
 type AuthTestSetup<TLoginArgs extends {
     body: Record<string, unknown>;
@@ -154,6 +150,100 @@ declare const setupAuthTest: <TLoginArgs extends {
     };
 }, TFeatures extends readonly AnyFeatureBuilder[] = readonly AnyFeatureBuilder[], TBearerData = unknown>(config: AuthTestSetupConfig<TLoginArgs, TRefreshArgs, TFeatures, TBearerData>) => AuthTestSetup<TLoginArgs, TRefreshArgs, TFeatures, TBearerData>;
 
+/**
+ * Test doubles for the two browser APIs the query client's multi-tab sync is built on:
+ * `BroadcastChannel` and the Web Locks API (`navigator.locks`).
+ *
+ * Both fakes are process-wide and shared between every consumer created while they are installed,
+ * which is exactly what makes "two tabs" testable: create two query clients in one test and they
+ * talk to each other over the fake bus and contend for the same fake locks, going through the real
+ * production code path on both sides.
+ *
+ * Neither jsdom nor happy-dom can stand in here - jsdom ships a `BroadcastChannel` that never
+ * delivers to other instances, and no `navigator.locks` at all.
+ */
+/** Something posted on the fake bus, as seen by a receiver. */
+type FakeBroadcastMessage = {
+    /** The channel name it was posted on. */
+    channel: string;
+    /** The structured-cloned payload. */
+    data: unknown;
+};
+type FakeBroadcastChannelHandle = {
+    /** Every message posted on the bus, in order, across all channel names. */
+    posted: FakeBroadcastMessage[];
+    /** Uninstalls the fake and restores whatever `BroadcastChannel` was there before. */
+    restore: () => void;
+};
+/**
+ * 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.
+ */
+declare const installFakeBroadcastChannel: () => FakeBroadcastChannelHandle;
+type FakeWebLocksHandle = {
+    /** The names currently held, in no particular order. */
+    heldNames: () => string[];
+    /** The names with at least one request queued behind the holder. */
+    pendingNames: () => string[];
+    /** Uninstalls the fake and restores whatever `navigator.locks` was there before. */
+    restore: () => void;
+};
+/**
+ * Installs an in-memory `navigator.locks` implementing exclusive locks: one holder per name, the
+ * rest queued FIFO, granted on a microtask (never synchronously), released when the callback's
+ * promise settles. `signal` is honored for queued requests and - as in the real API - ignored once a
+ * request has been granted.
+ *
+ * `mode: 'shared'`, `ifAvailable` and `steal` are not implemented; nothing in the library uses them.
+ */
+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.
+ */
+declare const flushMultiTabSync: () => Promise<void>;
+
+/**
+ * An in-memory stand-in for the query client's persisted response store.
+ *
+ * jsdom has no IndexedDB at all, so this is how persistence is tested - and because the storage
+ * adapter is a documented seam rather than a mock of one, a spec running against this exercises the
+ * real engine, repository and request code on both the write and the read side.
+ *
+ * Everything resolves on a microtask, never synchronously, matching the real thing: `await
+ * Promise.resolve()` (or `flushMicrotasks`) is what lets a hydration land in a spec.
+ */
+type FakeQueryPersistenceStoreHandle = {
+    /** Pass this as `persistence: { adapter }`. Two clients sharing one handle share one store. */
+    adapter: QueryPersistenceAdapter;
+    /** Pre-populates the store, as if a previous session had written these entries. */
+    seed: (entries: PersistedQueryEntry[]) => void;
+    /** Every entry currently held, in insertion order. */
+    entries: () => PersistedQueryEntry[];
+    /** The entry held under `key`, or `undefined`. */
+    entry: (key: string) => PersistedQueryEntry | undefined;
+    /** How often each adapter method has been called. */
+    calls: () => Record<'loadIndex' | 'read' | 'write' | 'remove' | 'clear', number>;
+    /** Makes the next `count` writes reject - a full disk, by default. */
+    failNextWrites: (count: number, error?: unknown) => void;
+    /** Makes the next `loadIndex` reject. */
+    failNextLoadIndex: (error?: unknown) => void;
+    /**
+     * 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).
+     */
+    deferReads: () => void;
+    /** Settles the reads held by {@link deferReads} and stops deferring. */
+    flushReads: () => Promise<void>;
+};
+declare const createFakeQueryPersistenceStore: () => FakeQueryPersistenceStoreHandle;
+
 declare const expectAndFlush: <T = unknown>(httpTesting: HttpTestingController, url: string, response: T, statusOpts?: {
     status: number;
     statusText: string;
@@ -163,5 +253,44 @@ declare const expectFlushAndWait: <T = unknown>(httpTesting: HttpTestingControll
     statusText: string;
 }) => void;
 
-export { expectAndFlush, expectFlushAndWait, setupAuthTest, setupQueryTest };
-export type { AnyFeatureBuilder, AuthTestSetup, AuthTestSetupConfig, QueryTestSetup, QueryTestSetupConfig };
+/** A scripted stand-in for `socket.io-client`'s `io`, driven from a spec. */
+type WebSocketTestDouble = {
+    /** Pass this as `createWebSocketClient({ io })`. */
+    io: WebSocketClientIo;
+    /** The url and options the client called the factory with, or `null` until it did. */
+    connection: () => {
+        url: string;
+        transports: string[] | undefined;
+    } | null;
+    /** Every message the client sent, newest last - room joins and leaves included. */
+    sent: () => {
+        event: string;
+        data: unknown;
+    }[];
+    /** Whether the client asked the socket to connect, and whether it has since disconnected it. */
+    state: () => {
+        connectRequested: boolean;
+        disconnected: boolean;
+    };
+    /** Complete the handshake, so the client's `isConnected` turns true and queued rooms re-join. */
+    serverConnect: () => void;
+    /** Drop the connection, so `isConnected` turns false. */
+    serverDisconnect: () => void;
+    /** Deliver a message the way the server would. */
+    serverSend: (message: SocketMessageView) => void;
+    /** Deliver a raw frame, for the malformed-payload path. */
+    serverSendRaw: (frame: string) => void;
+};
+/**
+ * A socket io test double, for specs around `createWebSocketClient` - which takes its `io` factory as
+ * an option precisely so a spec (or an app that never opens a socket) needs no `socket.io-client`.
+ *
+ * Nothing here connects on its own: the client's own `connect()` only flips
+ * {@link WebSocketTestDouble.state}, and it is {@link WebSocketTestDouble.serverConnect} that fires
+ * the `connect` listener. That split is what makes "joined a room while disconnected, and the join
+ * was re-sent on connect" testable.
+ */
+declare const createWebSocketTestDouble: () => WebSocketTestDouble;
+
+export { createFakeQueryPersistenceStore, createWebSocketTestDouble, expectAndFlush, expectFlushAndWait, flushMultiTabSync, installFakeBroadcastChannel, installFakeWebLocks, setupAuthTest, setupQueryTest };
+export type { AnyFeatureBuilder, AuthTestSetup, AuthTestSetupConfig, FakeBroadcastChannelHandle, FakeBroadcastMessage, FakeQueryPersistenceStoreHandle, FakeWebLocksHandle, QueryTestSetup, QueryTestSetupConfig, WebSocketTestDouble };