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

package/generators/migrate-to-query-v3/schema.json

@@ -4,6 +4,18 @@
   "title": "Migrate to Query v3",
   "type": "object",
   "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace. Use this to adopt v3 one app or library at a time instead of rewriting the whole monorepo in one run - but keep a query client and the creators built from it in the same run, since they are migrated together.",
+      "alias": "project"
+    },
+    "include": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path prefixes to migrate, relative to the workspace root (e.g. 'libs/queries'). Unioned with `projects`. Defaults to the whole workspace.",
+      "alias": "includePath"
+    },
     "skipFormat": {
       "type": "boolean",
       "description": "Skip formatting files after migration",

package/generators/migrate-to-query-v3/shared.js

@@ -17,9 +17,13 @@ export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier })
     const sourceFile = createSourceFile(content);
     let importNode;
     ts.forEachChild(sourceFile, (node) => {
-        if (ts.isImportDeclaration(node) &&
+        if (!importNode &&
+            ts.isImportDeclaration(node) &&
             ts.isStringLiteral(node.moduleSpecifier) &&
-            node.moduleSpecifier.text === moduleSpecifier) {
+            node.moduleSpecifier.text === moduleSpecifier &&
+            !node.importClause?.isTypeOnly &&
+            node.importClause?.namedBindings &&
+            ts.isNamedImports(node.importClause.namedBindings)) {
             importNode = node;
         }
     });
@@ -55,6 +59,8 @@ export const ensureNamedImports = ({ content, importsNeeded, moduleSpecifier })
 };
 export const ensureImportFromQuery = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@ethlete/query' });
 export const ensureAngularCoreImports = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@angular/core' });
+/** `toProvideFn` / `toInjectFn` - the provider-definition extractors every generated ref pair needs. */
+export const ensureImportFromEthleteCore = (content, importsNeeded) => ensureNamedImports({ content, importsNeeded, moduleSpecifier: '@ethlete/core' });
 export const getVariableStatementEnd = (sourceFile, variableName, initializerName) => {
     let variableStatementEnd;
     const visit = (node) => {
@@ -94,4 +100,47 @@ export const getLineNumber = (node, sourceFile) => {
     return line + 1;
 };
 export const getLineNumberFromPosition = (content, position) => content.slice(0, position).split('\n').length;
+const MIGRATION_GUIDE_URL = 'https://ethlete-sdk-docs.web.app/query/migrating-from-v2';
+/**
+ * The tag every `createLegacyQueryCreator(…)` wrapper carries. The wrapper is a migration
+ * scaffold, so marking it is what turns "which call sites are still on v2" from a grep into
+ * strikethrough in the editor.
+ */
+export const legacyQueryDeprecationTag = (creatorName) => `@deprecated Legacy (v2) query wrapper. Migrate the call sites to ${creatorName ? `\`${creatorName}\`` : 'the query creator it wraps'} and delete this wrapper - see ${MIGRATION_GUIDE_URL}.`;
+/**
+ * Adds a tag to `node`'s JSDoc, creating the block when there is none. Returns `null` when the
+ * tag is already there, so a caller can tell "nothing to do" from "rewritten".
+ *
+ * Leading `//` comments stay glued to the node - an `eslint-disable-next-line` only works from
+ * the line directly above.
+ */
+export const addJsDocTag = (content, sourceFile, node, tag) => {
+    const jsDocs = node.jsDoc ?? [];
+    const existing = jsDocs[jsDocs.length - 1];
+    const tagName = /^@\w+/.exec(tag)?.[0];
+    if (existing && tagName && new RegExp(`${tagName}\\b`).test(existing.getText())) {
+        return null;
+    }
+    if (existing) {
+        const start = existing.getStart(sourceFile);
+        const indentation = ' '.repeat(sourceFile.getLineAndCharacterOfPosition(start).character);
+        const text = existing.getText();
+        const body = text.slice(0, text.lastIndexOf('*/')).replace(/\s+$/, '');
+        // A one-line `/** … */` has to become a block before a tag line can be appended to it.
+        const opened = body.includes('\n') ? body : `/**\n${indentation} * ${body.slice(3).trim()}`;
+        return (content.slice(0, start) +
+            `${opened}\n${indentation} *\n${indentation} * ${tag}\n${indentation} */` +
+            content.slice(existing.getEnd()));
+    }
+    let start = node.getStart(sourceFile, false);
+    for (const comment of (ts.getLeadingCommentRanges(content, node.getFullStart()) ?? []).reverse()) {
+        if (comment.kind !== ts.SyntaxKind.SingleLineCommentTrivia)
+            break;
+        if (!/^\n[ \t]*$/.test(content.slice(comment.end, start)))
+            break;
+        start = comment.pos;
+    }
+    const indentation = ' '.repeat(sourceFile.getLineAndCharacterOfPosition(start).character);
+    return (content.slice(0, start) + `/**\n${indentation} * ${tag}\n${indentation} */\n${indentation}` + content.slice(start));
+};
 //# sourceMappingURL=shared.js.map

package/generators/prep-for-query-v3/migration.js

@@ -58,7 +58,7 @@ function renameConflictingSymbols(tree) {
     // Log statistics
     if (updatedFiles.length > 0) {
         console.log(`\n📊 Renamed symbols in ${updatedFiles.length} files:`);
-        const hasRenames = Array.from(symbolUsageCounts.entries()).filter(([_, count]) => count > 0);
+        const hasRenames = Array.from(symbolUsageCounts.entries()).filter(([, count]) => count > 0);
         if (hasRenames.length > 0) {
             console.log('\n   Symbol usage counts:');
             hasRenames.forEach(([symbol, count]) => {
@@ -76,7 +76,18 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     const replacements = [];
     // Track which symbols are imported from @ethlete/query
     const importedSymbols = new Set();
+    const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
     function visit(node) {
+        const namespaceMember = getNamespaceMember(node, namespaceAliases)?.member;
+        const renamedMember = namespaceMember && (TYPE_RENAMES.get(namespaceMember.text) || FUNCTION_RENAMES.get(namespaceMember.text));
+        if (namespaceMember && renamedMember) {
+            replacements.push({
+                start: namespaceMember.getStart(sourceFile),
+                end: namespaceMember.getEnd(),
+                replacement: renamedMember,
+                oldName: namespaceMember.text,
+            });
+        }
         // Track imports from @ethlete/query
         if (ts.isImportDeclaration(node)) {
             const moduleSpecifier = node.moduleSpecifier;
@@ -107,7 +118,9 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
                 return;
             }
             // Skip if it's the imported name in an import specifier (we'll handle that separately)
-            if (ts.isImportSpecifier(parent) && (parent.propertyName === node || parent.name === node)) {
+            if ((ts.isImportSpecifier(parent) && (parent.propertyName === node || parent.name === node)) ||
+                (ts.isPropertyAccessExpression(parent) && parent.name === node) ||
+                (ts.isQualifiedName(parent) && parent.right === node)) {
                 ts.forEachChild(node, visit);
                 return;
             }
@@ -123,7 +136,7 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     }
     visit(sourceFile);
     // Update imports in @ethlete/query import declarations
-    const importReplacements = updateImports(sourceFile, content);
+    const importReplacements = updateImports(sourceFile);
     replacements.push(...importReplacements);
     // Count usages
     replacements.forEach((r) => {
@@ -138,7 +151,34 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     }
     return result;
 }
-function updateImports(sourceFile, content) {
+function collectQueryNamespaceAliases(sourceFile) {
+    const aliases = new Set();
+    sourceFile.statements.forEach((statement) => {
+        if (!ts.isImportDeclaration(statement)) {
+            return;
+        }
+        const namedBindings = statement.importClause?.namedBindings;
+        if (namedBindings &&
+            ts.isNamespaceImport(namedBindings) &&
+            ts.isStringLiteral(statement.moduleSpecifier) &&
+            statement.moduleSpecifier.text === '@ethlete/query') {
+            aliases.add(namedBindings.name.text);
+        }
+    });
+    return aliases;
+}
+function getNamespaceMember(node, namespaceAliases) {
+    const [namespace, member] = ts.isPropertyAccessExpression(node)
+        ? [node.expression, node.name]
+        : ts.isQualifiedName(node)
+            ? [node.left, node.right]
+            : [];
+    if (!namespace || !member || !ts.isIdentifier(namespace) || !ts.isIdentifier(member)) {
+        return undefined;
+    }
+    return namespaceAliases.has(namespace.text) ? { namespace, member } : undefined;
+}
+function updateImports(sourceFile) {
     const replacements = [];
     function visit(node) {
         if (ts.isImportDeclaration(node)) {
@@ -232,9 +272,11 @@ function replaceNamespaceInFile(content, filePath) {
         ts.forEachChild(node, collectImport);
     }
     collectImport(sourceFile);
+    const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
+    const namespaceReplacements = collectNamespacedExperimentalQueryReplacements(sourceFile, namespaceAliases);
     // If no ExperimentalQuery import found, return unchanged
     if (!hasExperimentalQueryImport || !experimentalQueryAlias) {
-        return { content, modified: false, replacementCount: 0 };
+        return applyReplacements(content, namespaceReplacements, namespaceReplacements.length);
     }
     // Second pass: collect used symbols
     function findUsages(node) {
@@ -313,17 +355,32 @@ function replaceNamespaceInFile(content, filePath) {
         ts.forEachChild(node, createReplacements);
     }
     createReplacements(sourceFile);
-    // Apply replacements in reverse order
+    // Subtract 1 for the import replacement
+    return applyReplacements(content, [...replacements, ...namespaceReplacements], replacements.length - 1 + namespaceReplacements.length);
+}
+function collectNamespacedExperimentalQueryReplacements(sourceFile, namespaceAliases) {
+    const replacements = [];
+    if (namespaceAliases.size === 0) {
+        return replacements;
+    }
+    function visit(node) {
+        const access = getNamespaceMember(node, namespaceAliases);
+        if (access?.member.text === 'ExperimentalQuery') {
+            replacements.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement: access.namespace.text });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return replacements;
+}
+function applyReplacements(content, replacements, replacementCount) {
     let result = content;
-    replacements.sort((a, b) => b.start - a.start);
-    for (const { start, end, replacement } of replacements) {
+    [...replacements]
+        .sort((a, b) => b.start - a.start)
+        .forEach(({ start, end, replacement }) => {
         result = result.slice(0, start) + replacement + result.slice(end);
-    }
-    return {
-        content: result,
-        modified: replacements.length > 0,
-        replacementCount: replacements.length - 1, // Subtract 1 for the import replacement
-    };
+    });
+    return { content: result, modified: replacements.length > 0, replacementCount };
 }
 //#endregion
 //# sourceMappingURL=migration.js.map

package/migrations.json

@@ -0,0 +1,44 @@
+{
+  "migrations": [
+    {
+      "name": "to-query-v3",
+      "version": "5.42.0",
+      "kind": "auto",
+      "description": "Move the legacy query system onto the new one through the interop layer.",
+      "generator": "@ethlete/query:migrate-to-query-v3",
+      "docs": "/query/migrating-from-v2"
+    },
+    {
+      "name": "prep-for-query-v3",
+      "version": "6.0.0-beta.8",
+      "kind": "auto",
+      "description": "Prepare the call sites the v3 query system changes, before the move itself.",
+      "generator": "@ethlete/query:prep-for-query-v3",
+      "docs": "/query/migrating-from-v2"
+    },
+    {
+      "name": "query-client-features",
+      "version": "6.0.0-next.23",
+      "kind": "auto",
+      "description": "Move the createQueryClient multiTabSync and persistence options onto opt-in features.",
+      "generator": "@ethlete/query:migrate-query-client-features",
+      "docs": "/query/features"
+    },
+    {
+      "name": "query-opt-in-features",
+      "version": "6.0.0-next.23",
+      "kind": "auto",
+      "description": "Move query clients onto the opt-in error pipeline, and bearer auth onto the opt-in multi-tab sync feature.",
+      "generator": "@ethlete/query:migrate-query-opt-in-features",
+      "docs": "/query/features"
+    },
+    {
+      "name": "deprecate-legacy-queries",
+      "version": "6.0.0-next.24",
+      "kind": "auto",
+      "description": "Mark the remaining createLegacyQueryCreator wrappers as deprecated, so their call sites surface as still on v2.",
+      "generator": "@ethlete/query:deprecate-legacy-queries",
+      "docs": "/query/legacy"
+    }
+  ]
+}

package/package.json

@@ -1,22 +1,37 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.5",
+  "version": "6.0.0-next.51",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
-    "@analogjs/vite-plugin-angular": "2.3.1",
-    "@angular/common": "21.2.1",
-    "@angular/core": "21.2.1",
-    "@angular/forms": "21.2.1",
-    "@angular/router": "21.2.1",
-    "@ethlete/core": "^5.0.0-next.0",
-    "@ethlete/types": "^2.0.0-next.0",
-    "@nx/devkit": "22.5.4",
-    "@nx/vite": "22.5.4",
+    "@analogjs/vite-plugin-angular": "2.6.3",
+    "@angular/common": "22.1.6",
+    "@angular/core": "22.1.6",
+    "@angular/forms": "22.1.6",
+    "@angular/router": "22.1.6",
+    "@ethlete/core": "^5.0.0-beta.11",
+    "@ethlete/types": "^2.0.0-beta.4",
+    "@nx/devkit": "23.1.0",
     "rxjs": "7.8.2",
-    "socket.io-client": "4.8.3",
-    "typescript": "5.9.3",
-    "vite": "^7.0.0"
+    "typescript": "6.0.3",
+    "vite": "8.1.5"
+  },
+  "peerDependenciesMeta": {
+    "@analogjs/vite-plugin-angular": {
+      "optional": true
+    },
+    "@nx/devkit": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "ethlete": {
+    "migrations": "./migrations.json"
   },
   "generators": "./generators/generators.json",
   "module": "fesm2022/ethlete-query.mjs",
@@ -34,6 +49,7 @@
       "default": "./fesm2022/ethlete-query-testing.mjs"
     }
   },
+  "type": "module",
   "dependencies": {
     "tslib": "^2.3.0"
   }

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;
@@ -15,6 +15,11 @@ type QueryTestSetup = {
     createPut: ReturnType<typeof createPutQuery>;
     createPatch: ReturnType<typeof createPatchQuery>;
     createDelete: ReturnType<typeof createDeleteQuery>;
+    /**
+     * Puts back the `console.warn` / `console.error` that were installed before the first
+     * {@link setupQueryTest} call. Idempotent, and safe to call from any of the setups a file created.
+     */
+    restoreConsole: () => void;
 };
 type QueryTestSetupConfig = {
     baseUrl?: string;
@@ -70,18 +75,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 +89,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 +155,114 @@ 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.
+ *
+ * `ifAvailable` is a try-lock: a request that cannot be granted straight away runs its callback with
+ * `null` instead of queueing, exactly as the real API does. `steal` releases the current holder -
+ * rejecting its request with an `AbortError` - and is granted ahead of everything queued.
+ *
+ * `mode: 'shared'` is not implemented; nothing in the library uses it.
+ */
+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 `count` removals reject. */
+    failNextRemoves: (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>;
+    /**
+     * Holds every subsequent `loadIndex` pending until {@link flushLoadIndex} is called, for testing
+     * what happens to the store while a client's startup is still reading its index (a real disk takes
+     * milliseconds). The snapshot each held load returns is the one it would have read when it started.
+     */
+    deferLoadIndex: () => void;
+    /** Settles the index loads held by {@link deferLoadIndex} and stops deferring. */
+    flushLoadIndex: () => Promise<void>;
+};
+declare const createFakeQueryPersistenceStore: () => FakeQueryPersistenceStoreHandle;
+
 declare const expectAndFlush: <T = unknown>(httpTesting: HttpTestingController, url: string, response: T, statusOpts?: {
     status: number;
     statusText: string;
@@ -163,5 +272,63 @@ 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;
+    /** The `withCredentials` the client asked the factory for, or `null` until it called it. */
+    withCredentials: () => boolean | null;
+    /** The auth payload of every handshake, oldest first - `null` for one made without `auth`. */
+    handshakes: () => (object | null)[];
+    /** Every message the client emitted, newest last - room joins and leaves included, buffered ones too. */
+    sent: () => {
+        event: string;
+        data: unknown;
+    }[];
+    /** Every message that reached the server, newest last. An emit buffered while offline lands here on the next connect. */
+    delivered: () => {
+        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: flush every buffered emit, then turn the client's `isConnected` true. Pass
+     * `recovered: true` for a connection-state-recovered reconnect, in which the server kept the rooms.
+     */
+    serverConnect: (options?: {
+        recovered?: boolean;
+    }) => void;
+    /** Drop the connection, so `isConnected` turns false. */
+    serverDisconnect: () => 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}.
+     */
+    serverPingExpire: () => 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 it was
+ * re-joined after a reconnect" 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 };