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

package/generators/migrate-query-opt-in-features/report.js

@@ -0,0 +1,143 @@
+export const QUERY_OPT_IN_FEATURES_REPORT_PATH = 'query-opt-in-features-migration-tasks.md';
+export const MIGRATION_TASK_KIND = {
+    WARNING: 'warning',
+    MANUAL_REVIEW: 'manual-review',
+    FOLLOW_UP: 'follow-up',
+};
+const renderTaskLocations = (locations) => {
+    if (locations.length === 0) {
+        return '- None recorded';
+    }
+    return locations.map((location) => `- ${location.filePath}${location.line ? `:${location.line}` : ''}`).join('\n');
+};
+export class QueryOptInFeaturesMigrationReport {
+    constructor() {
+        this.tasks = [];
+    }
+    addTask(input) {
+        const dedupeKey = input.dedupeKey ?? `${input.kind}:${input.title}:${input.summary}:${input.action}`;
+        const existing = this.tasks.find((task) => task.dedupeKey === dedupeKey);
+        if (existing) {
+            existing.locations.push(...(input.locations ?? []));
+            return;
+        }
+        this.tasks.push({
+            id: `QOF-${String(this.tasks.length + 1).padStart(3, '0')}`,
+            kind: input.kind,
+            title: input.title,
+            summary: input.summary,
+            action: input.action,
+            locations: input.locations ?? [],
+            source: input.source,
+            dedupeKey,
+        });
+    }
+    addWarning(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.WARNING });
+    }
+    addManualReview(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.MANUAL_REVIEW });
+    }
+    addFollowUp(input) {
+        this.addTask({ ...input, kind: MIGRATION_TASK_KIND.FOLLOW_UP });
+    }
+    printSummary() {
+        if (this.tasks.length === 0) {
+            return;
+        }
+        console.warn(`\n⚠️ Generated ${this.tasks.length} follow-up task${this.tasks.length === 1 ? '' : 's'}:`);
+        this.tasks.forEach((task) => {
+            const locations = task.locations
+                .map((location) => `${location.filePath}${location.line ? `:${location.line}` : ''}`)
+                .join(', ');
+            console.warn(` - ${task.id} [${task.kind}] ${task.title}${locations ? ` (${locations})` : ''}`);
+        });
+        console.warn(`\n📄 See ${QUERY_OPT_IN_FEATURES_REPORT_PATH} for the AI-ready follow-up list.`);
+    }
+    writeToTree(tree) {
+        tree.write(QUERY_OPT_IN_FEATURES_REPORT_PATH, renderMigrationReportMarkdown(this.tasks));
+    }
+}
+export const renderMigrationReportMarkdown = (tasks) => {
+    const header = [
+        '# Query Opt-In Features Migration Follow-Up',
+        '',
+        'This file is generated by the `migrate-query-opt-in-features` generator.',
+        '',
+        '## Context',
+        '',
+        'Two things that used to be on by default are now opt-in features:',
+        '',
+        '- error-response parsing (HTML error pages, Symfony / class-validator violation lists) and the',
+        '  default retry policy, now `withEthleteApiErrors()` on `createQueryClient`,',
+        '- bearer-auth multi-tab sync and leader election, now `withBearerAuthMultiTabSync()` on',
+        '  `createBearerAuthProvider` (the `multiTabSync` config option is gone).',
+        '',
+        'The codemod is **behavior preserving**: it adds the features every call site used to get for free.',
+        'That is rarely what an app wants long term — an API that never answers with an HTML error page, or',
+        'an app that is only ever open in one tab, ships that code for nothing. Review each added feature',
+        'and delete the ones you do not need; `withEthleteApiErrors()` in particular splits into',
+        '`withHtmlErrorParsing()`, `withSymfonyErrors()` and `withDefaultRetry()`.',
+        '',
+        '## AI Instructions',
+        '',
+        '1. Re-read the referenced files before changing anything. The migration output is only a starting point.',
+        '2. Prefer minimal fixes that align with the current runtime APIs in `@ethlete/query`.',
+        '3. Update or remove a task only after the code and tests confirm that it is resolved.',
+        '4. If a task is still ambiguous after inspection, keep it open and append a short note instead of guessing.',
+        '',
+        '## Task Format',
+        '',
+        '- `Status`: always treat generated tasks as `open` until verified manually or by tests.',
+        '- `Kind`: `warning`, `manual-review`, or `follow-up`.',
+        '- `Source`: which migration phase raised the task.',
+        '',
+    ].join('\n');
+    if (tasks.length === 0) {
+        return `${header}## Tasks\n\nNo open follow-up tasks were recorded during this migration run.\n`;
+    }
+    const tasksSection = tasks
+        .map((task) => [
+        `### ${task.id} - ${task.title}`,
+        '',
+        '- Status: open',
+        `- Kind: ${task.kind}`,
+        `- Source: ${task.source}`,
+        `- Summary: ${task.summary}`,
+        `- Suggested action: ${task.action}`,
+        '- Locations:',
+        renderTaskLocations(task.locations),
+        '',
+    ].join('\n'))
+        .join('');
+    const machineSection = [
+        '## Machine Summary',
+        '',
+        '```yaml',
+        'tasks:',
+        ...tasks.flatMap((task) => {
+            const nestedLocations = task.locations.flatMap((location) => {
+                const lines = [`      - filePath: ${location.filePath}`];
+                if (location.line) {
+                    lines.push(`        line: ${location.line}`);
+                }
+                return lines;
+            });
+            return [
+                `  - id: ${task.id}`,
+                `    status: open`,
+                `    kind: ${task.kind}`,
+                `    source: ${task.source}`,
+                `    title: ${task.title}`,
+                `    summary: ${task.summary}`,
+                `    action: ${task.action}`,
+                `    locations:`,
+                ...(nestedLocations.length > 0 ? nestedLocations : ['      []']),
+            ];
+        }),
+        '```',
+        '',
+    ].join('\n');
+    return `${header}## Tasks\n\n${tasksSection}${machineSection}`;
+};
+//# sourceMappingURL=report.js.map

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-prepare-migration.js

@@ -1,5 +1,12 @@
 import * as ts from 'typescript';
 import { createSourceFile, ensureAngularCoreImports, getIndentation, getLineNumber, getLineNumberFromPosition, } from './shared.js';
+/** Contexts that already have an injector of their own, so the call site needs no rewrite. */
+const CONTEXTS_WITH_INJECTOR = [
+    'queryComputed',
+    'injection-context',
+    'class-field',
+    'constructor',
+];
 export const migrateLegacyPrepareCalls = (tree, report, scope) => {
     console.log('\n🔍 Checking for legacy query creator usages...');
     const allUsages = [];
@@ -98,32 +105,88 @@ const findLegacyCreatorNames = (sourceFile) => {
     visit(sourceFile);
     return names;
 };
+/** Helpers that run their callback inside an injection context, so a `prepare()` in one needs nothing. */
+const CONTEXT_PROVIDING_CALLEES = new Set([
+    'runInInjectionContext',
+    'queryComputed',
+    'queryComputedTillTruthy',
+    'queryArrayComputed',
+]);
+/**
+ * Array methods, which call back synchronously in the caller's own context. Matched only on a property
+ * access (`items.map(…)`) - the bare-identifier form is an RxJS operator, whose callback runs later.
+ */
+const TRANSPARENT_ARRAY_METHODS = new Set([
+    'map',
+    'flatMap',
+    'filter',
+    'forEach',
+    'find',
+    'findLast',
+    'findIndex',
+    'some',
+    'every',
+    'reduce',
+    'reduceRight',
+    'sort',
+    'flat',
+]);
+const isCallbackFunction = (node) => ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node);
+/** The call a function literal is being passed to, if it is an argument rather than a value. */
+const getCallbackHost = (node) => {
+    const parent = node.parent;
+    if (!ts.isCallExpression(parent) || !parent.arguments.some((argument) => argument === node)) {
+        return undefined;
+    }
+    return parent;
+};
+const isContextProvidingCallback = (node) => {
+    const host = getCallbackHost(node);
+    if (!host) {
+        return false;
+    }
+    if (ts.isIdentifier(host.expression)) {
+        return CONTEXT_PROVIDING_CALLEES.has(host.expression.text);
+    }
+    return ts.isPropertyAccessExpression(host.expression) && host.expression.name.text === 'runInContext';
+};
+const isTransparentCallback = (node) => {
+    const host = getCallbackHost(node);
+    return (!!host && ts.isPropertyAccessExpression(host.expression) && TRANSPARENT_ARRAY_METHODS.has(host.expression.name.text));
+};
+/**
+ * Classifies the **innermost** function boundary the call sits behind, not the first structural ancestor.
+ * The difference is the whole point: `effect(() => prepare())` in a constructor and
+ * `computed(() => prepare())` at a class field both run long after the context that created them, so they
+ * need an injector just like a plain method does - reading the constructor or the field as the answer
+ * skipped exactly the call sites that go on to throw ET950.
+ */
 const determineUsageContext = (node) => {
     let current = node;
     while (current) {
-        if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) {
-            const parent = current.parent;
-            if (ts.isCallExpression(parent) &&
-                ts.isIdentifier(parent.expression) &&
-                parent.expression.text === 'queryComputed') {
-                return 'queryComputed';
+        if (isCallbackFunction(current)) {
+            if (isContextProvidingCallback(current)) {
+                const host = getCallbackHost(current);
+                const callee = host && ts.isIdentifier(host.expression) ? host.expression.text : undefined;
+                return callee?.startsWith('query') ? 'queryComputed' : 'injection-context';
+            }
+            if (!isTransparentCallback(current)) {
+                return isInsideClass(current) ? 'method' : 'function';
             }
         }
+        // Reached without crossing a callback: the call really does run while the class is being built, which
+        // is an injection context.
         if (ts.isConstructorDeclaration(current)) {
             return 'constructor';
         }
-        if (ts.isMethodDeclaration(current)) {
+        if (ts.isMethodDeclaration(current) ||
+            ts.isGetAccessorDeclaration(current) ||
+            ts.isSetAccessorDeclaration(current)) {
             return 'method';
         }
         if (ts.isPropertyDeclaration(current)) {
             return 'class-field';
         }
-        if (ts.isFunctionDeclaration(current)) {
-            return 'function';
-        }
-        if ((ts.isArrowFunction(current) || ts.isFunctionExpression(current)) && !isInsideClass(current)) {
-            return 'function';
-        }
         current = current.parent;
     }
     return 'unknown';
@@ -177,7 +240,7 @@ const findOrCreateInjectorMembers = (tree, usages) => {
     const classInjectors = new Map();
     const usagesByFile = new Map();
     usages.forEach((usage) => {
-        if (['queryComputed', 'class-field', 'constructor'].includes(usage.context)) {
+        if (CONTEXTS_WITH_INJECTOR.includes(usage.context)) {
             return;
         }
         if (!usagesByFile.has(usage.filePath)) {
@@ -342,7 +405,7 @@ const transformPrepareCallsInFile = (content, classes, pollingInfo) => {
                     return;
                 }
                 const context = determineUsageContext(node);
-                if (['queryComputed', 'constructor', 'class-field'].includes(context)) {
+                if (CONTEXTS_WITH_INJECTOR.includes(context)) {
                     ts.forEachChild(node, visit);
                     return;
                 }
@@ -535,7 +598,7 @@ const transformSinglePrepareCall = (callNode, injectorReference, sourceFile, pol
     }
     nextArgumentProperties.push(`injector: ${injectorReference}`);
     const queryVariableName = findQueryVariableNameForPrepareCall(callNode, sourceFile);
-    const addDestroyOnResponse = shouldAddDestroyOnResponse(queryVariableName, pollingInfo);
+    const addDestroyOnResponse = shouldAddDestroyOnResponse(queryVariableName, pollingInfo, isDiscardedPrepareCall(callNode));
     if (existingConfig && ts.isObjectLiteralExpression(existingConfig.initializer)) {
         const configProperties = [];
         existingConfig.initializer.properties.forEach((property) => {
@@ -763,9 +826,39 @@ const detectPollingInTemplate = (content, filePath, pollingInfo) => {
         }
     }
 };
-const shouldAddDestroyOnResponse = (queryVariableName, pollingInfo) => {
+/**
+ * Whether the prepared query is thrown away - `legacyGetUsers.prepare().execute()` as a statement, with
+ * nothing holding on to it. Chained `.poll()` disqualifies it: that query is meant to keep running.
+ */
+const isDiscardedPrepareCall = (callNode) => {
+    let current = callNode;
+    while (current.parent) {
+        const parent = current.parent;
+        if (ts.isParenthesizedExpression(parent) || ts.isAwaitExpression(parent) || ts.isNonNullExpression(parent)) {
+            current = parent;
+            continue;
+        }
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === current) {
+            if (parent.name.text === 'poll') {
+                return false;
+            }
+            current = parent;
+            continue;
+        }
+        // Only a chained call keeps it discarded; being an *argument* means something else receives the query.
+        if (ts.isCallExpression(parent) && parent.expression === current) {
+            current = parent;
+            continue;
+        }
+        return ts.isExpressionStatement(parent);
+    }
+    return false;
+};
+const shouldAddDestroyOnResponse = (queryVariableName, pollingInfo, isDiscarded) => {
     if (!queryVariableName) {
-        return false;
+        // A discarded query is the one case where nothing else can clean it up: no variable for a container
+        // to hold, no caller to destroy it. That is exactly what `destroyOnResponse` is for.
+        return isDiscarded;
     }
     return !pollingInfo.get(queryVariableName)?.hasPolling;
 };

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, legacyQueryDeprecationTag, } from './shared.js';
 const LEGACY_HTTP_METHOD = {
     GET: 'get',
     POST: 'post',
@@ -443,7 +443,7 @@ const getTypeParameter = (creator) => {
 const generateLegacyWrapper = (creator) => {
     // `name` is what lets a `prepare()` called outside an injection context name itself in the error
     // instead of surfacing as a bare NG0203.
-    return `export const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ name: '${toLegacyName(creator.name)}', creator: ${creator.name} });`;
+    return `/**\n * ${legacyQueryDeprecationTag(creator.name)}\n */\nexport const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ name: '${toLegacyName(creator.name)}', creator: ${creator.name} });`;
 };
 const createAuthProviders = ({ tree, authProvidersNeeded, report, v2Configs, creatorToClient, }) => {
     const createdProviders = [];
@@ -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) => {
@@ -94,4 +96,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.22",
+  "version": "6.0.0-next.24",
   "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",