@ethlete/query 6.0.0-next.22 → 6.0.0-next.23

package/generators/migrate-query-opt-in-features/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "migrate-query-opt-in-features",
+  "title": "Migrate query clients and auth providers to opt-in features",
+  "type": "object",
+  "properties": {
+    "projects": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Nx projects to migrate. Defaults to every project in the workspace.",
+      "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"
+    },
+    "reportOnly": {
+      "type": "boolean",
+      "description": "Only list the affected call sites in the report file, without changing any code.",
+      "default": false
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators/migrate-to-query-v3/auth-provider-scaffold.js

@@ -69,8 +69,8 @@ const REFRESH_QUERY_KEY = 'tokenRefresh';
 /**
  * Renders the `queries` / `features` arguments of a v3 provider from a v2 config.
  *
- * The mapping is close to 1:1 — `queryCreator` → `withRefreshQuery`, `responseAdapter` →
- * `extractTokens`, `cookieName` → `withPersistentAuth({ cookie })` — but the adapters are copied
+ * The mapping is close to 1:1 - `queryCreator` → `withRefreshQuery`, `responseAdapter` →
+ * `extractTokens`, `cookieName` → `withPersistentAuth({ cookie })` - but the adapters are copied
  * verbatim from v2 and their parameter shapes differ, so each one is emitted with a TODO rather
  * than presented as finished.
  */
@@ -85,7 +85,7 @@ export const renderAuthProviderBody = (config) => {
     }
     const refreshEntries = [`      queryCreator: ${config.refreshCreatorName},`];
     if (config.responseAdapter) {
-        refreshEntries.push(`      // TODO(query-v3): v2 responseAdapter. It must return { accessToken, refreshToken } — v2 returned { token, refreshToken }.`, `      extractTokens: ${config.responseAdapter},`);
+        refreshEntries.push(`      // TODO(query-v3): v2 responseAdapter. It must return { accessToken, refreshToken } - v2 returned { token, refreshToken }.`, `      extractTokens: ${config.responseAdapter},`);
     }
     if (config.requestArgsAdapter) {
         refreshEntries.push(`      // TODO(query-v3): v2 requestArgsAdapter took { token, refreshToken }; buildArgs takes the refresh token alone.`, `      buildArgs: ${config.requestArgsAdapter},`);

package/generators/migrate-to-query-v3/cleanup-migration.js

@@ -3,7 +3,7 @@ import { createSourceFile, ensureImportFromQuery, ensureNamedImports, getLineNum
 /**
  * Points existing devtools usage at the v3 components instead of deleting it.
  *
- * Both versions render `<et-query-devtools>`, so templates need no change at all — only the provider
+ * Both versions render `<et-query-devtools>`, so templates need no change at all - only the provider
  * call and the component's import move. Stripping the markup (as this phase used to) threw away
  * something that would have kept working, and left every migrated app without devtools until someone
  * noticed they were gone.
@@ -119,7 +119,7 @@ const importsFromQuery = (content, name) => {
  * `provideQueryDevtools()`.
  *
  * v3 registers every client and auth provider at once, so N per-client calls collapse to one. The
- * first call site keeps its position — it is already where the app wanted its devtools — and the
+ * first call site keeps its position - it is already where the app wanted its devtools - and the
  * rest are removed along with the comma that separated them.
  */
 const replaceDevtoolsProviderCalls = (content) => {

package/generators/migrate-to-query-v3/http-client-check.js

@@ -3,7 +3,7 @@ const APP_CONFIG_MARKERS = ['bootstrapApplication(', 'ApplicationConfig', 'provi
 /**
  * Flags the v2 default-header APIs, which the client migration drops on the floor.
  *
- * `setDefaultHeaders` is not cosmetic — an API token or a preview credential lives there, so losing
+ * `setDefaultHeaders` is not cosmetic - an API token or a preview credential lives there, so losing
  * it means every request goes out unauthenticated. v3 has a home for it (`headers` on
  * `createQueryClient`), but the call sites are imperative and scattered, so this is a pointer rather
  * than a rewrite.
@@ -31,7 +31,7 @@ export const reportDefaultHeaderUsages = (tree, report, scope) => {
     report.addWarning({
         title: 'Move default headers onto the query client',
         summary: 'This workspace sets client-wide headers through the v2 `setDefaultHeaders` / `globalHeaders` API, which `createQueryClient` does not have. Left as is, those headers are simply not sent.',
-        action: 'Pass `headers` to `createQueryClient` — a function form re-reads on every request, so a signal can drive it. `refreshQueriesInUse: true` becomes `injectMyClient().refreshQueriesInUse()` after the value changes.',
+        action: 'Pass `headers` to `createQueryClient` - a function form re-reads on every request, so a signal can drive it. `refreshQueriesInUse: true` becomes `injectMyClient().refreshQueriesInUse()` after the value changes.',
         locations,
         source: 'http-client-check',
         dedupeKey: 'default-headers',
@@ -41,7 +41,7 @@ export const reportDefaultHeaderUsages = (tree, report, scope) => {
  * Flags applications that will build cleanly and then fail on their first request.
  *
  * The v2 client shipped its own transport; v3 does `inject(HttpClient)`. An app that never needed
- * `provideHttpClient()` therefore keeps compiling after the migration and dies at runtime instead —
+ * `provideHttpClient()` therefore keeps compiling after the migration and dies at runtime instead -
  * the one failure mode a codemod should never leave behind silently.
  */
 export const reportMissingHttpClientProviders = (tree, report, scope) => {
@@ -71,8 +71,8 @@ export const reportMissingHttpClientProviders = (tree, report, scope) => {
     if (appConfigFiles.length > 0 && filesWithProvider.length === 0) {
         report.addWarning({
             title: 'Add provideHttpClient() to the application providers',
-            summary: 'v3 queries run on Angular’s `HttpClient`, but no `provideHttpClient()` was found. The app compiles and then throws on the first request — `@ethlete/query` never provides it, that is the application’s job.',
-            action: 'Add `provideHttpClient()` to every app config that uses a query client. If anything relies on upload progress, use `provideHttpClient(withXhr())` — on Angular ≥ 22 the default is fetch, which emits no upload progress events.',
+            summary: 'v3 queries run on Angular’s `HttpClient`, but no `provideHttpClient()` was found. The app compiles and then throws on the first request - `@ethlete/query` never provides it, that is the application’s job.',
+            action: 'Add `provideHttpClient()` to every app config that uses a query client. If anything relies on upload progress, use `provideHttpClient(withXhr())` - on Angular ≥ 22 the default is fetch, which emits no upload progress events.',
             locations: appConfigFiles,
             source: 'http-client-check',
             dedupeKey: 'missing-provide-http-client',

package/generators/migrate-to-query-v3/legacy-query-creator-migration.js

@@ -2,7 +2,7 @@ import * as ts from 'typescript';
 import { collectV2BearerAuthConfigs, renderAuthProviderBody } from './auth-provider-scaffold.js';
 import { createModuleGraph } from './module-graph.js';
 import { pruneUnusedNamedImports, renameImportedReferences } from './rename-symbols.js';
-import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromQuery } from './shared.js';
+import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromEthleteCore, ensureImportFromQuery, } from './shared.js';
 const LEGACY_HTTP_METHOD = {
     GET: 'get',
     POST: 'post',
@@ -504,7 +504,7 @@ const createAuthProviders = ({ tree, authProvidersNeeded, report, v2Configs, cre
     }
 };
 const addAuthProviderToFile = (content, clientName, body) => {
-    const nextContent = ensureImportFromQuery(content, ['createBearerAuthProvider', ...body.importsNeeded]);
+    const nextContent = ensureImportFromEthleteCore(ensureImportFromQuery(content, ['createBearerAuthProvider', ...body.importsNeeded]), ['toInjectFn', 'toProvideFn']);
     const sourceFile = createSourceFile(nextContent);
     const configName = ensureConfigSuffix(clientName);
     const configPosition = findVariableStatementEnd(sourceFile, configName, 'createQueryClient');
@@ -522,7 +522,8 @@ const addAuthProviderToFile = (content, clientName, body) => {
         ...(body.features ? [body.features] : []),
         '});',
         '',
-        `export const [provide${capitalizedClientName}AuthProvider, inject${capitalizedClientName}AuthProvider] = ${authProviderName};`,
+        `export const provide${capitalizedClientName}AuthProvider = toProvideFn(${authProviderName});`,
+        `export const inject${capitalizedClientName}AuthProvider = toInjectFn(${authProviderName});`,
     ].join('\n');
     return nextContent.slice(0, configPosition) + authProviderBlock + nextContent.slice(configPosition);
 };

package/generators/migrate-to-query-v3/query-client-migration.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
+import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromEthleteCore, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
 export const migrateQueryClients = (tree, report, scope) => {
     const queryClientFiles = new Map();
     const variableRenames = new Map();
@@ -249,7 +249,7 @@ const renameVariables = (content, renames) => {
  * report from production.
  */
 const DROPPED_CLIENT_OPTIONS = {
-    'request.autoRefreshQueriesOnWindowFocus': 'No direct equivalent. Re-run the affected queries yourself — `withAutoRefresh({ onSignalChanges: [windowFocusSignal] })` per query, or `injectMyClient().refreshQueriesInUse()` from a focus listener.',
+    'request.autoRefreshQueriesOnWindowFocus': 'No direct equivalent. Re-run the affected queries yourself - `withAutoRefresh({ onSignalChanges: [windowFocusSignal] })` per query, or `injectMyClient().refreshQueriesInUse()` from a focus listener.',
     'request.enableSmartPolling': 'No direct equivalent. `withPolling({ interval })` polls unconditionally; pause it yourself when the tab is hidden if that matters.',
     'logging.preparedQuerySubscriptions': 'Removed. Use the v3 devtools (`provideQueryDevtools()`) or `withLogging({ logFn })` on the queries you want to trace.',
     'logging.queryStateChanges': 'Removed. Use the v3 devtools (`provideQueryDevtools()`) or `withLogging({ logFn })` on the queries you want to trace.',
@@ -374,19 +374,20 @@ const addProviderAliasesToFile = (content, configNames) => {
             return;
         }
         const { injectName, provideName } = getProviderAliasNames(variableName);
-        if (result.includes(`export const [${provideName}, ${injectName}] = ${variableName};`)) {
+        if (result.includes(`export const ${injectName} = toInjectFn(${variableName});`)) {
             return;
         }
         insertions.push({
             position,
-            text: `\n\nexport const [${provideName}, ${injectName}] = ${variableName};`,
+            text: `\n\nexport const ${provideName} = toProvideFn(${variableName});` +
+                `\nexport const ${injectName} = toInjectFn(${variableName});`,
         });
     });
     insertions.sort((left, right) => right.position - left.position);
     insertions.forEach(({ position, text }) => {
         result = result.slice(0, position) + text + result.slice(position);
     });
-    return result;
+    return insertions.length > 0 ? ensureImportFromEthleteCore(result, ['toInjectFn', 'toProvideFn']) : result;
 };
 const getProviderAliasNames = (configVariableName) => {
     const baseName = configVariableName.replace(/Config$/, '');

package/generators/migrate-to-query-v3/rename-symbols.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { createSourceFile } from './shared.js';
 /**
- * Whether an identifier is a *name* rather than a *reference* — a declaration, a property key, the
+ * Whether an identifier is a *name* rather than a *reference* - a declaration, a property key, the
  * right-hand side of a member access. Renaming those is what turned `PeopleDetailDataSource.getPerson`
  * and the `postLogin` property of a config type into `legacy…` during the first migration run.
  */
@@ -9,7 +9,7 @@ const isNamePosition = (node) => {
     const parent = node.parent;
     if (!parent)
         return false;
-    // `foo.bar` / `Foo.Bar` — the part after the dot is never the imported binding.
+    // `foo.bar` / `Foo.Bar` - the part after the dot is never the imported binding.
     if (ts.isPropertyAccessExpression(parent) && parent.name === node)
         return true;
     if (ts.isQualifiedName(parent) && parent.right === node)
@@ -63,7 +63,7 @@ const isNamePosition = (node) => {
         return true;
     return false;
 };
-/** Every name the file declares itself — a local by the same name means the import is shadowed. */
+/** Every name the file declares itself - a local by the same name means the import is shadowed. */
 const collectLocalDeclarations = (sourceFile) => {
     const declared = new Set();
     const add = (name) => {
@@ -134,7 +134,7 @@ export const renameImportedReferences = (content, renames) => {
  * The migration rewrites away the constructs that needed `def`, `AnyLegacyQueryCreator` and friends;
  * leaving the imports behind turns every touched file into a lint error, and `formatFiles` runs in
  * the same generator invocation so they land that way. Identifiers inside template strings count as
- * usage too — a component referenced only from an inline template must not be pruned.
+ * usage too - a component referenced only from an inline template must not be pruned.
  */
 export const pruneUnusedNamedImports = (content, moduleSpecifiers) => {
     const sourceFile = createSourceFile(content);

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

@@ -7,7 +7,7 @@
     "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.",
+      "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": {

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

@@ -55,6 +55,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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.22",
+  "version": "6.0.0-next.23",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
@@ -17,6 +17,23 @@
     "typescript": "6.0.3",
     "vite": "8.1.5"
   },
+  "peerDependenciesMeta": {
+    "@analogjs/vite-plugin-angular": {
+      "optional": true
+    },
+    "@nx/devkit": {
+      "optional": true
+    },
+    "socket.io-client": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
   "generators": "./generators/generators.json",
   "module": "fesm2022/ethlete-query.mjs",
   "typings": "types/ethlete-query.d.ts",

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 } 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;
@@ -74,14 +74,6 @@ type AuthTestSetupConfig<TLoginArgs extends {
     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 */
@@ -154,6 +146,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 +249,5 @@ declare const expectFlushAndWait: <T = unknown>(httpTesting: HttpTestingControll
     statusText: string;
 }) => void;
 
-export { expectAndFlush, expectFlushAndWait, setupAuthTest, setupQueryTest };
-export type { AnyFeatureBuilder, AuthTestSetup, AuthTestSetupConfig, QueryTestSetup, QueryTestSetupConfig };
+export { createFakeQueryPersistenceStore, expectAndFlush, expectFlushAndWait, flushMultiTabSync, installFakeBroadcastChannel, installFakeWebLocks, setupAuthTest, setupQueryTest };
+export type { AnyFeatureBuilder, AuthTestSetup, AuthTestSetupConfig, FakeBroadcastChannelHandle, FakeBroadcastMessage, FakeQueryPersistenceStoreHandle, FakeWebLocksHandle, QueryTestSetup, QueryTestSetupConfig };