@ethlete/query 6.0.0-next.50 → 6.0.0-next.52

package/generators/migrate-from-ngrx-toolkit/ts-edits.js

@@ -0,0 +1,128 @@
+import * as ts from 'typescript';
+import { pruneUnusedNamedImports } from '../migrate-to-query-v3/rename-symbols.js';
+import { createSourceFile } from '../migrate-to-query-v3/shared.js';
+/** Applies edits back to front. An edit nested inside an already applied one is dropped. */
+export const applyEdits = (content, edits) => {
+    const sorted = [...edits].sort((left, right) => right.start - left.start || right.end - left.end);
+    let result = content;
+    let floor = Number.POSITIVE_INFINITY;
+    for (const edit of sorted) {
+        if (edit.end > floor)
+            continue;
+        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+        floor = edit.start;
+    }
+    return result;
+};
+/** Removes `nodes[index]` from a comma separated list, together with the comma that belongs to it. */
+export const removeListElement = (nodes, index, sourceFile) => {
+    const node = nodes[index];
+    if (index < nodes.length - 1) {
+        return { start: node.getStart(sourceFile), end: nodes[index + 1].getStart(sourceFile), text: '' };
+    }
+    if (index > 0) {
+        return { start: nodes[index - 1].getEnd(), end: node.getEnd(), text: '' };
+    }
+    return { start: node.getStart(sourceFile), end: node.getEnd(), text: '' };
+};
+/** Removes a whole statement or class member, including its leading comments and the line break after it. */
+export const removeStatement = (node, content) => {
+    const comments = ts.getLeadingCommentRanges(content, node.getFullStart()) ?? [];
+    let start = comments[0]?.pos ?? node.getStart();
+    while (start > 0 && (content[start - 1] === ' ' || content[start - 1] === '\t'))
+        start -= 1;
+    let end = node.getEnd();
+    while (content[end] === ' ' || content[end] === '\t')
+        end += 1;
+    if (content[end] === '\r')
+        end += 1;
+    if (content[end] === '\n')
+        end += 1;
+    return { start, end, text: '' };
+};
+export const lineOf = (sourceFile, position) => sourceFile.getLineAndCharacterOfPosition(position).line + 1;
+export const collectUsedIdentifiers = (sourceFile) => {
+    const used = new Set();
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node))
+            return;
+        if (ts.isIdentifier(node))
+            used.add(node.text);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return used;
+};
+/** Collapses runs of blank lines left behind by removed statements, outside template literals. */
+export const collapseBlankLines = (content) => {
+    const sourceFile = createSourceFile(content);
+    const templates = [];
+    const visit = (node) => {
+        if (ts.isTemplateExpression(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+            templates.push([node.getStart(sourceFile), node.getEnd()]);
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return content.replace(/\n[ \t]*\n(?:[ \t]*\n)+/g, (match, offset) => templates.some(([start, end]) => offset >= start && offset < end) ? match : '\n\n');
+};
+/** Drops unused namespace, default and named imports. Side-effect imports stay. */
+export const pruneUnusedImports = (content) => {
+    const sourceFile = createSourceFile(content);
+    const used = collectUsedIdentifiers(sourceFile);
+    const edits = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause)
+            continue;
+        const { name, namedBindings } = statement.importClause;
+        if (namedBindings && ts.isNamespaceImport(namedBindings) && !used.has(namedBindings.name.text)) {
+            if (!name || !used.has(name.text))
+                edits.push(removeStatement(statement, content));
+            continue;
+        }
+        if (!namedBindings && name && !used.has(name.text)) {
+            edits.push(removeStatement(statement, content));
+        }
+    }
+    return pruneUnusedNamedImports(applyEdits(content, edits));
+};
+/** A relative module specifier from one workspace file to another, without the `.ts` extension. */
+export const relativeSpecifier = (fromFile, toFile) => {
+    const fromSegments = fromFile.split('/').slice(0, -1);
+    const toSegments = toFile.replace(/\.ts$/, '').split('/');
+    let shared = 0;
+    while (shared < fromSegments.length &&
+        shared < toSegments.length - 1 &&
+        fromSegments[shared] === toSegments[shared]) {
+        shared += 1;
+    }
+    const ups = fromSegments.length - shared;
+    const rest = toSegments.slice(shared).join('/');
+    return ups === 0 ? `./${rest}` : `${'../'.repeat(ups)}${rest}`;
+};
+export const hasExportModifier = (node) => ts.canHaveModifiers(node) &&
+    !!ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+/** The names a top-level statement declares. */
+export const declaredNames = (statement) => {
+    if (ts.isVariableStatement(statement)) {
+        return statement.declarationList.declarations.flatMap((declaration) => {
+            if (ts.isIdentifier(declaration.name))
+                return [declaration.name.text];
+            if (ts.isObjectBindingPattern(declaration.name)) {
+                return declaration.name.elements.flatMap((element) => ts.isIdentifier(element.name) ? [element.name.text] : []);
+            }
+            return [];
+        });
+    }
+    if ((ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement) ||
+        ts.isEnumDeclaration(statement)) &&
+        statement.name) {
+        return [statement.name.text];
+    }
+    return [];
+};
+//# sourceMappingURL=ts-edits.js.map

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

@@ -4,8 +4,16 @@ import { createMigrationScope } from '../migrate-to-query-v3/migration-scope.js'
 import { createSourceFile, ensureImportFromQuery, getLineNumber } from '../migrate-to-query-v3/shared.js';
 import { QueryOptInFeaturesMigrationReport } from './report.js';
 const SOURCE = 'query-opt-in-features';
-const CLIENT_FEATURE = 'withEthleteApiErrors';
+export const CLIENT_FEATURE = 'withEthleteApiErrors';
 const AUTH_FEATURE = 'withBearerAuthMultiTabSync';
+export const reportClientErrorPipelineAdded = (report, location, source, summary = `\`${CLIENT_FEATURE}()\` was added so error parsing and retrying keep working exactly as before.`) => report.addFollowUp({
+    title: 'Client kept the full error pipeline',
+    summary,
+    action: 'Narrow it: `withHtmlErrorParsing()` only for an API behind a proxy that answers HTML, `withSymfonyErrors()` only for violation-list responses, `withDefaultRetry()` only if failed requests should retry themselves.',
+    locations: [location],
+    source,
+    dedupeKey: 'client-error-pipeline',
+});
 const isMigratableFile = (filePath) => /\.(ts|mts|cts)$/.test(filePath) && !filePath.endsWith('.d.ts');
 const propertyNamed = (config, sourceFile, name) => config.properties.find((property) => ts.isPropertyAssignment(property) && property.name.getText(sourceFile) === name);
 const hasFeature = (config, sourceFile, feature) => {
@@ -87,14 +95,7 @@ const collectEdits = (filePath, sourceFile, report) => {
                 }
                 else if (isClient) {
                     const feature = `${CLIENT_FEATURE}()`;
-                    report.addFollowUp({
-                        title: 'Client kept the full error pipeline',
-                        summary: `\`${CLIENT_FEATURE}()\` was added so error parsing and retrying keep working exactly as before.`,
-                        action: 'Narrow it: `withHtmlErrorParsing()` only for an API behind a proxy that answers HTML, `withSymfonyErrors()` only for violation-list responses, `withDefaultRetry()` only if failed requests should retry themselves.',
-                        locations: [{ filePath, line }],
-                        source: SOURCE,
-                        dedupeKey: 'client-error-pipeline',
-                    });
+                    reportClientErrorPipelineAdded(report, { filePath, line }, SOURCE);
                     edits.push({
                         start: config.getStart(sourceFile),
                         end: config.getEnd(),

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

@@ -8,6 +8,10 @@ const REFRESH_CONFIG_KEYS = new Set([
     'cookieDomain',
     'cookieExpiresInDays',
     'expiresInPropertyName',
+    'cookiePath',
+    'cookieSameSite',
+    'cookieEnabled',
+    'refreshBuffer',
 ]);
 export const collectV2BearerAuthConfigs = (tree, scope) => {
     const configs = [];
@@ -77,12 +81,14 @@ const REFRESH_QUERY_KEY = 'tokenRefresh';
  * than presented as finished.
  */
 export const renderAuthProviderBody = (config) => {
+    const warnings = [];
     if (!config?.refreshCreatorName) {
         return {
             queries: '  queries: [],',
             features: '',
             importsNeeded: [],
             isScaffolded: false,
+            warnings,
         };
     }
     const refreshEntries = [`      queryCreator: ${config.refreshCreatorName},`];
@@ -95,6 +101,16 @@ export const renderAuthProviderBody = (config) => {
     if (config.expiresInPropertyName) {
         refreshEntries.push(`      expiresInPropertyName: ${config.expiresInPropertyName},`);
     }
+    if (config.refreshBuffer) {
+        refreshEntries.push(`      refreshStrategy: ${renderRefreshStrategy(config.refreshBuffer)},`);
+    }
+    if (config.cookieName && config.cookieEnabled && config.cookieEnabled !== 'true') {
+        warnings.push({
+            title: 'Replace the v2 cookieEnabled switch',
+            summary: `The v2 provider set \`cookieEnabled: ${config.cookieEnabled}\`. \`withPersistentAuth\` has no switch for it: it always keeps the refresh token in the cookie, and \`setRememberMe(false)\` only turns that cookie into a session cookie. v2's \`enableCookie()\` / \`disableCookie()\` have no v3 counterpart either.`,
+            action: 'If the cookie was only written after an opt-in (a "remember me" box), drive `setRememberMe()` from it. If it was never written, remove `withPersistentAuth` from the scaffold.',
+        });
+    }
     const queries = [
         '  queries: [',
         `    // Derived from the v2 BearerAuthProvider in ${config.filePath}:${config.line}. Verify before shipping.`,
@@ -106,13 +122,17 @@ export const renderAuthProviderBody = (config) => {
     ].join('\n');
     const importsNeeded = ['withRefreshQuery'];
     if (!config.cookieName) {
-        return { queries, features: '', importsNeeded, isScaffolded: true };
+        return { queries, features: '', importsNeeded, isScaffolded: true, warnings };
     }
     const cookieEntries = [`      name: ${config.cookieName},`];
     if (config.cookieDomain)
         cookieEntries.push(`      domain: ${config.cookieDomain},`);
     if (config.cookieExpiresInDays)
         cookieEntries.push(`      expiresInDays: ${config.cookieExpiresInDays},`);
+    if (config.cookiePath)
+        cookieEntries.push(`      path: ${config.cookiePath},`);
+    if (config.cookieSameSite)
+        cookieEntries.push(`      sameSite: ${config.cookieSameSite},`);
     const features = [
         '  features: [',
         '    withPersistentAuth({',
@@ -128,6 +148,13 @@ export const renderAuthProviderBody = (config) => {
         '  ],',
     ].join('\n');
     importsNeeded.push('withPersistentAuth');
-    return { queries, features, importsNeeded, isScaffolded: true };
+    return { queries, features, importsNeeded, isScaffolded: true, warnings };
+};
+// A v3 `refreshStrategy` number from 0 to 1 is a fraction of the token lifetime, not milliseconds.
+const renderRefreshStrategy = (refreshBuffer) => {
+    const value = Number(refreshBuffer.replace(/_/g, ''));
+    return Number.isFinite(value) && value > 1
+        ? refreshBuffer
+        : `{ minBufferMs: ${refreshBuffer}, maxBufferMs: ${refreshBuffer} }`;
 };
 //# sourceMappingURL=auth-provider-scaffold.js.map

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

@@ -1,5 +1,26 @@
 import * as ts from 'typescript';
-import { createSourceFile, ensureImportFromQuery, ensureNamedImports } from './shared.js';
+import { REMOVED_EXPERIMENTAL_QUERY_HELPERS, createSourceFile, ensureImportFromQuery, ensureNamedImports, findRemovedExperimentalQueryHelpers, } from './shared.js';
+export const reportRemovedExperimentalQueryHelpers = (tree, scope, report) => {
+    scope.visit(tree, (filePath) => {
+        if (!filePath.endsWith('.ts')) {
+            return;
+        }
+        const content = tree.read(filePath, 'utf-8');
+        if (!content?.includes('@ethlete/query')) {
+            return;
+        }
+        findRemovedExperimentalQueryHelpers(createSourceFile(content, filePath)).forEach(({ name, line }) => {
+            report.addWarning({
+                title: `Replace the removed helper ${name}`,
+                summary: `\`${name}\` came from the pre-v3 \`ExperimentalQuery\` namespace and is no longer exported by \`@ethlete/query\`, so this import does not compile. The migration does not rewrite it.`,
+                action: REMOVED_EXPERIMENTAL_QUERY_HELPERS[name],
+                locations: [{ filePath, line }],
+                source: 'cleanup-migration',
+                dedupeKey: `removed-experimental-helper:${filePath}:${name}`,
+            });
+        });
+    });
+};
 /**
  * Points existing devtools usage at the v3 components instead of deleting it.
  *

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

@@ -10,6 +10,7 @@ const LEGACY_HTTP_METHOD = {
     PATCH: 'patch',
     DELETE: 'delete',
 };
+const LEGACY_GQL_METHODS = ['gqlQuery', 'gqlMutate'];
 const HTTP_OPTION_NAMES = ['reportProgress', 'responseType', 'transferCache', 'withCredentials'];
 const isLegacyHttpMethod = (value) => {
     return Object.values(LEGACY_HTTP_METHOD).includes(value);
@@ -219,6 +220,16 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                 ts.forEachChild(node, visit);
                 return;
             }
+            if (oldClientNames.has(objectExpression.text) && LEGACY_GQL_METHODS.includes(methodExpression.text)) {
+                report.addManualReview({
+                    title: `Rewrite the GraphQL creator ${node.name.text} by hand`,
+                    summary: `${node.name.text} is built with \`${objectExpression.text}.${methodExpression.text}()\`. The migration only rewrites REST creators, so this one still calls a method the migrated client no longer has.`,
+                    action: `Rebuild it on the v3 client with \`${methodExpression.text === 'gqlQuery' ? 'createGqlQueryViaPost' : 'createGqlMutationViaPost'}\` (or the \`ViaGet\` variant) and a \`gql\` document, then wrap it in \`createLegacyQueryCreator\` if its call sites stay on v2. See https://ethlete-sdk-docs.web.app/query/gql.`,
+                    locations: [{ filePath, line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 }],
+                    source: 'legacy-query-creator-migration',
+                    dedupeKey: `gql-creator:${filePath}:${node.name.text}`,
+                });
+            }
             if (!oldClientNames.has(objectExpression.text) || !isLegacyHttpMethod(methodExpression.text)) {
                 ts.forEachChild(node, visit);
                 return;
@@ -270,7 +281,10 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                         if (HTTP_OPTION_NAMES.includes(property.name.text)) {
                             info.httpOptions.set(property.name.text, property.name.text);
                         }
-                        if (property.name.text !== 'route' && !HTTP_OPTION_NAMES.includes(property.name.text)) {
+                        if (property.name.text === 'entity') {
+                            info.entity = property.name.text;
+                        }
+                        if (!['route', 'entity'].includes(property.name.text) && !HTTP_OPTION_NAMES.includes(property.name.text)) {
                             warnUnreadableConfigValue(property, 'as a shorthand property');
                         }
                         return;
@@ -281,6 +295,9 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
                     if (property.name.text === 'route') {
                         info.route = property.initializer.getText(sourceFile);
                     }
+                    if (property.name.text === 'entity') {
+                        info.entity = property.initializer.getText(sourceFile);
+                    }
                     if (property.name.text === 'secure') {
                         if (property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
                             info.secure = true;
@@ -329,6 +346,18 @@ const analyzeLegacyQueryCreators = (content, queryClientFiles, filePath, report)
             }
             if (info.route) {
                 creators.push(info);
+                if (info.entity) {
+                    report.addFollowUp({
+                        title: `Check the entity config carried onto ${toLegacyName(creatorName)}`,
+                        summary: `${creatorName} had an \`entity\` config. It was moved onto the \`${toLegacyName(creatorName)}\` interop wrapper, which still writes to the EntityStore; the v3 creator \`${creatorName}\` does not, and v3 has no EntityStore.`,
+                        action: 'Keep the call sites that rely on the store on the legacy wrapper. `set` now only runs on a real response, never on `prepare()` or a failure.',
+                        locations: [
+                            { filePath, line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 },
+                        ],
+                        source: 'legacy-query-creator-migration',
+                        dedupeKey: `entity-config:${filePath}:${creatorName}`,
+                    });
+                }
             }
         }
         ts.forEachChild(node, visit);
@@ -509,7 +538,7 @@ const getTypeParameter = (creator) => {
 const generateLegacyWrapper = (creator, exportPrefix) => {
     // `name` is what lets a `prepare()` called outside an injection context name itself in the error
     // instead of surfacing as a bare NG0203.
-    return `/**\n * ${legacyQueryDeprecationTag(creator.name)}\n */\n${exportPrefix}const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ name: '${toLegacyName(creator.name)}', creator: ${creator.name} });`;
+    return `/**\n * ${legacyQueryDeprecationTag(creator.name)}\n */\n${exportPrefix}const ${toLegacyName(creator.name)} = createLegacyQueryCreator({ name: '${toLegacyName(creator.name)}', creator: ${creator.name}${creator.entity ? `, entity: ${creator.entity}` : ''} });`;
 };
 const createAuthProviders = ({ tree, authProvidersNeeded, report, v2Configs, creatorToClient, }) => {
     const createdProviders = [];
@@ -532,6 +561,14 @@ const createAuthProviders = ({ tree, authProvidersNeeded, report, v2Configs, cre
         }
         tree.write(filePath, nextContent);
         createdProviders.push(filePath);
+        body.warnings.forEach((warning) => {
+            report.addWarning({
+                ...warning,
+                locations: [{ filePath }, ...(v2Config ? [{ filePath: v2Config.filePath, line: v2Config.line }] : [])],
+                source: 'legacy-query-creator-migration',
+                dedupeKey: `auth-provider-warning:${filePath}:${authProviderName}:${warning.title}`,
+            });
+        });
         if (body.isScaffolded) {
             report.addFollowUp({
                 title: `Finish the scaffolded auth provider ${authProviderName}`,

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

@@ -1,5 +1,5 @@
 import { formatFiles } from '@nx/devkit';
-import { migrateDevtoolsUsage, migrateEmptyPrepareCalls, replaceAnyQueryWithLegacy } from './cleanup-migration.js';
+import { migrateDevtoolsUsage, migrateEmptyPrepareCalls, replaceAnyQueryWithLegacy, reportRemovedExperimentalQueryHelpers, } from './cleanup-migration.js';
 import { reportDefaultHeaderUsages, reportMissingHttpClientProviders } from './http-client-check.js';
 import { migrateLegacyPrepareCalls } from './legacy-prepare-migration.js';
 import { createNewQueryCreators, updateLegacyCreatorImportsAndUsages } from './legacy-query-creator-migration.js';
@@ -25,6 +25,7 @@ export default async function migrate(tree, schema) {
     migrateDevtoolsUsage(tree, scope, report);
     migrateEmptyPrepareCalls(tree, scope);
     migrateLegacyPrepareCalls(tree, report, scope);
+    reportRemovedExperimentalQueryHelpers(tree, scope, report);
     if (queryClientFiles.size > 0) {
         reportMissingHttpClientProviders(tree, report, scope);
         reportDefaultHeaderUsages(tree, report, scope);

package/generators/migrate-to-query-v3/module-graph.js

@@ -138,6 +138,8 @@ export const createModuleGraph = (tree) => {
         return null;
     };
     return {
+        resolveFile: resolveEntryFile,
+        pathAliases: () => [...tsConfigPaths.keys()],
         findDeclaringFile: (fromFile, specifier, symbolName) => {
             const cacheKey = `${fromFile}|${specifier}|${symbolName}`;
             const cached = declaringFileCache.get(cacheKey);

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

@@ -1,4 +1,5 @@
 import * as ts from 'typescript';
+import { CLIENT_FEATURE, reportClientErrorPipelineAdded } from '../migrate-query-opt-in-features/migration.js';
 import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromEthleteCore, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
 export const migrateQueryClients = (tree, report, scope) => {
     const queryClientFiles = new Map();
@@ -151,6 +152,7 @@ const migrateQueryClientToConfig = ({ content, filePath, renamesOut, report }) =
                     }
                 }
                 reportDroppedClientOptions({ configArgument, sourceFile, filePath, report });
+                reportChangedClientDefaults({ configArgument, sourceFile, filePath, report });
                 replacements.push({
                     start: node.getStart(sourceFile),
                     end: node.getEnd(),
@@ -190,6 +192,7 @@ const removeQueryClientImport = (content, keepLegacyClient) => {
         'createPostQuery',
         'createPutQuery',
         'createQueryClient',
+        CLIENT_FEATURE,
     ];
     if (!queryImportNode?.importClause?.namedBindings || !ts.isNamedImports(queryImportNode.importClause.namedBindings)) {
         return ensureImportFromQuery(content, requiredImports);
@@ -253,6 +256,12 @@ const renameVariables = (content, renames) => {
     });
     return result;
 };
+const WINDOW_FOCUS_REPLACEMENT = 'Opt in per query: `withPolling({ interval, refetchOnFocus: true })` on a polled query, `withAutoRefresh({ onSignalChanges: [windowFocusSignal] })` on any other, or `injectMyClient().refreshQueriesInUse()` from a focus listener.';
+const SMART_POLLING_REPLACEMENT = 'Opt in per query: `withPolling({ interval, pauseWhileHidden: true })`. Without it v3 keeps polling in a hidden tab.';
+const V2_ON_BY_DEFAULT_REQUEST_OPTIONS = {
+    autoRefreshQueriesOnWindowFocus: WINDOW_FOCUS_REPLACEMENT,
+    enableSmartPolling: SMART_POLLING_REPLACEMENT,
+};
 /**
  * What each v2 client option turns into, or why it has nowhere to go.
  *
@@ -261,8 +270,8 @@ 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.enableSmartPolling': 'No direct equivalent. `withPolling({ interval })` polls unconditionally; pause it yourself when the tab is hidden if that matters.',
+    'request.autoRefreshQueriesOnWindowFocus': WINDOW_FOCUS_REPLACEMENT,
+    'request.enableSmartPolling': SMART_POLLING_REPLACEMENT,
     '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.',
     'request.autoRefreshOn': 'No direct equivalent. Re-run the affected queries yourself with `withAutoRefresh` or `refreshQueriesInUse()`.',
@@ -315,6 +324,12 @@ const reportDroppedClientOptions = ({ configArgument, sourceFile, filePath, repo
                 if (name === 'request' && ['queryParams', 'cacheAdapter', 'retryFn'].includes(nested.name.text)) {
                     return;
                 }
+                if (name === 'request' &&
+                    nested.name.text in V2_ON_BY_DEFAULT_REQUEST_OPTIONS &&
+                    ts.isPropertyAssignment(nested) &&
+                    nested.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+                    return;
+                }
                 raise(`${name}.${nested.name.text}`, nested);
             });
             return;
@@ -324,6 +339,59 @@ const reportDroppedClientOptions = ({ configArgument, sourceFile, filePath, repo
         }
     });
 };
+const reportChangedClientDefaults = ({ configArgument, sourceFile, filePath, report, }) => {
+    const location = {
+        filePath,
+        line: sourceFile.getLineAndCharacterOfPosition(configArgument.getStart(sourceFile)).line + 1,
+    };
+    const requestProperty = findProperty(configArgument, 'request');
+    const requestConfig = requestProperty &&
+        ts.isPropertyAssignment(requestProperty) &&
+        ts.isObjectLiteralExpression(requestProperty.initializer)
+        ? requestProperty.initializer
+        : undefined;
+    const hasUnreadableRequestConfig = (!!requestProperty && !requestConfig) || !!requestConfig?.properties.some(ts.isSpreadAssignment);
+    reportClientErrorPipelineAdded(report, location, 'query-client-migration', `\`${CLIENT_FEATURE}()\` was added so failed requests still retry and Symfony / HTML error bodies are still parsed, as they were by default in v2.`);
+    if (!requestConfig || !findProperty(requestConfig, 'retryFn')) {
+        report.addWarning({
+            title: 'Check the retry behaviour of the migrated client',
+            summary: 'v2 retried every request method on a 5xx (500 included), 408, 425 and 429, up to four times with a linear delay. The v3 default policy that `withEthleteApiErrors()` installs retries three times with an exponential, jittered delay, never retries a `POST`, a `PATCH` or a plain `500`, and also retries a connection failure.',
+            action: 'Accept the v3 policy, or pass `withEthleteApiErrors({ retry: { maxAttempts, retryableStatusCodes, retryNonIdempotent } })` - only set `retryNonIdempotent` for endpoints that deduplicate on their own.',
+            locations: [location],
+            source: 'query-client-migration',
+            dedupeKey: `changed-retry-default:${filePath}`,
+        });
+    }
+    const cacheAdapter = requestConfig && findProperty(requestConfig, 'cacheAdapter');
+    if (cacheAdapter) {
+        report.addWarning({
+            title: 'Check the carried-over cacheAdapter',
+            summary: 'The v2 `cacheAdapter` was carried over as is and still sets the freshness TTL: a TTL of `0` means an `execute({ options: { allowCache: true } })` always hits the server, as a v2 `execute()` did. Two things differ: v3 passes Angular `HttpHeaders` (read them with `headers.get(name)`) where v2 passed a plain record, and v3 keeps an entry for `keepUnusedFor` (5 minutes) after its last consumer, rendering the old response on a remount while it refetches.',
+            action: 'Rewrite an adapter that reads headers for `HttpHeaders`. If the adapter was meant to switch caching off, also set `keepUnusedFor: 0` on the client.',
+            locations: [
+                { filePath, line: sourceFile.getLineAndCharacterOfPosition(cacheAdapter.getStart(sourceFile)).line + 1 },
+            ],
+            source: 'query-client-migration',
+            dedupeKey: `carried-cache-adapter:${filePath}`,
+        });
+    }
+    if (hasUnreadableRequestConfig) {
+        return;
+    }
+    Object.entries(V2_ON_BY_DEFAULT_REQUEST_OPTIONS).forEach(([option, action]) => {
+        if (requestConfig && findProperty(requestConfig, option)) {
+            return;
+        }
+        report.addWarning({
+            title: `Restore the v2 default "request.${option}"`,
+            summary: `The v2 client did not set \`request.${option}\`, so it ran with the v2 default \`true\`. v3 has no client-wide equivalent and the behaviour is off for every migrated query.`,
+            action,
+            locations: [location],
+            source: 'query-client-migration',
+            dedupeKey: `dropped-client-default:${filePath}:${option}`,
+        });
+    });
+};
 const getPropertyValueText = (property, sourceFile) => {
     if (ts.isShorthandPropertyAssignment(property)) {
         return property.name.text;
@@ -361,6 +429,7 @@ const migrateConfigObject = (configArgument, node, sourceFile) => {
             }
         }
     }
+    nextConfig.push(`features: [${CLIENT_FEATURE}()]`);
     return `createQueryClient({\n  ${nextConfig.join(',\n  ')}\n})`;
 };
 const getVariableNameForQueryClient = (node) => {

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

@@ -143,4 +143,31 @@ export const addJsDocTag = (content, sourceFile, node, tag) => {
     const indentation = ' '.repeat(sourceFile.getLineAndCharacterOfPosition(start).character);
     return (content.slice(0, start) + `/**\n${indentation} * ${tag}\n${indentation} */\n${indentation}` + content.slice(start));
 };
+const TUPLE_PROVIDER_ACTION = 'Delete the call: a v3 client, auth provider or socket is root-provided the moment something injects it. For a test or an override, provide it with `toProvideFn(ref)` from `@ethlete/core`.';
+export const REMOVED_EXPERIMENTAL_QUERY_HELPERS = {
+    createQueryClientConfig: 'Replace it with `createQueryClient({ name, baseUrl })`, which returns the provider tuple, and derive `toProvideFn` / `toInjectFn` from it.',
+    createBearerAuthProviderConfig: 'Replace it with `createBearerAuthProvider({ name, queryClientRef, queries, features })`, which returns the provider tuple, and derive `toProvideFn` / `toInjectFn` from it.',
+    provideQueryClient: TUPLE_PROVIDER_ACTION,
+    provideBearerAuthProvider: TUPLE_PROVIDER_ACTION,
+    provideWebSocketClient: `Build the socket with \`createWebSocketClient({ name, url, io })\`. ${TUPLE_PROVIDER_ACTION}`,
+};
+export const findRemovedExperimentalQueryHelpers = (sourceFile) => {
+    const found = [];
+    sourceFile.statements.forEach((statement) => {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== '@ethlete/query' ||
+            !statement.importClause?.namedBindings ||
+            !ts.isNamedImports(statement.importClause.namedBindings)) {
+            return;
+        }
+        statement.importClause.namedBindings.elements.forEach((element) => {
+            const name = (element.propertyName ?? element.name).text;
+            if (name in REMOVED_EXPERIMENTAL_QUERY_HELPERS) {
+                found.push({ name, line: getLineNumber(element, sourceFile) });
+            }
+        });
+    });
+    return found;
+};
 //# sourceMappingURL=shared.js.map

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

@@ -1,9 +1,11 @@
-import { formatFiles, visitNotIgnoredFiles } from '@nx/devkit';
+import { formatFiles, joinPathFragments, readJson, visitNotIgnoredFiles } from '@nx/devkit';
 import * as ts from 'typescript';
+import { REMOVED_EXPERIMENTAL_QUERY_HELPERS, createSourceFile, findRemovedExperimentalQueryHelpers, } from '../migrate-to-query-v3/shared.js';
 export default async function migrate(tree, schema) {
     console.log('\n🔄 Starting Query v3 symbol conflict migration...');
     renameConflictingSymbols(tree);
     replaceExperimentalQueryNamespace(tree);
+    reportPrebuiltPackagesImportingRenamedSymbols(tree);
     if (!schema.skipFormat) {
         await formatFiles(tree);
     }
@@ -224,6 +226,7 @@ function updateImports(sourceFile) {
 //#region ExperimentalQuery namespace replacement
 function replaceExperimentalQueryNamespace(tree) {
     const updatedFiles = [];
+    const removedHelpers = [];
     let totalReplacements = 0;
     visitNotIgnoredFiles(tree, '', (filePath) => {
         if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts'))
@@ -240,7 +243,13 @@ function replaceExperimentalQueryNamespace(tree) {
             updatedFiles.push(filePath);
             totalReplacements += result.replacementCount;
         }
+        findRemovedExperimentalQueryHelpers(createSourceFile(result.content, filePath)).forEach(({ name, line }) => {
+            removedHelpers.push(`   - ${filePath}:${line} ${name}: ${REMOVED_EXPERIMENTAL_QUERY_HELPERS[name]}`);
+        });
     });
+    if (removedHelpers.length > 0) {
+        console.warn(`\n⚠️ These ExperimentalQuery helpers no longer exist in v3 and were left for you to replace by hand (migrate-to-query-v3 lists them again in its report):\n${removedHelpers.join('\n')}`);
+    }
     if (updatedFiles.length > 0) {
         console.log(`\n📦 Replaced ExperimentalQuery namespace in ${updatedFiles.length} files (${totalReplacements} usages)`);
     }
@@ -382,5 +391,78 @@ function applyReplacements(content, replacements, replacementCount) {
     });
     return { content: result, modified: replacements.length > 0, replacementCount };
 }
+const isRenamedSymbol = (name) => TYPE_RENAMES.has(name) || FUNCTION_RENAMES.has(name);
+function reportPrebuiltPackagesImportingRenamedSymbols(tree) {
+    if (!tree.exists('package.json'))
+        return;
+    const packageJson = readJson(tree, 'package.json');
+    const packageNames = new Set([packageJson.dependencies, packageJson.devDependencies, packageJson.optionalDependencies].flatMap((deps) => Object.keys(deps ?? {})));
+    const hits = [];
+    [...packageNames]
+        .filter((name) => !name.startsWith('@ethlete/'))
+        .sort()
+        .forEach((packageName) => {
+        const importedNames = new Set();
+        collectDeclarationFiles(tree, joinPathFragments('node_modules', packageName)).forEach((filePath) => {
+            const content = tree.read(filePath, 'utf-8');
+            if (!content?.includes('@ethlete/query'))
+                return;
+            findRenamedSymbolsInDeclaration(createSourceFile(content, filePath)).forEach((name) => importedNames.add(name));
+        });
+        if (importedNames.size > 0) {
+            hits.push(`   - ${packageName}: ${[...importedNames].sort().join(', ')}`);
+        }
+    });
+    if (hits.length > 0) {
+        console.warn(`\n⚠️ These installed packages were built against @ethlete/query v2 and import names v3 no longer exports. No codemod can fix them here: run prep-for-query-v3 in each package's own repository and release a rebuild before upgrading this workspace:\n${hits.join('\n')}`);
+    }
+}
+function collectDeclarationFiles(tree, dir) {
+    if (!tree.exists(dir))
+        return [];
+    return tree.children(dir).flatMap((child) => {
+        if (child === 'node_modules')
+            return [];
+        const childPath = joinPathFragments(dir, child);
+        if (tree.isFile(childPath)) {
+            return /\.d\.(c|m)?ts$/.test(child) ? [childPath] : [];
+        }
+        return collectDeclarationFiles(tree, childPath);
+    });
+}
+function findRenamedSymbolsInDeclaration(sourceFile) {
+    const names = new Set();
+    const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
+    const isQueryModule = (node) => !!node && ts.isStringLiteral(node) && node.text === '@ethlete/query';
+    function visit(node) {
+        if (ts.isImportDeclaration(node) && isQueryModule(node.moduleSpecifier)) {
+            const namedBindings = node.importClause?.namedBindings;
+            if (namedBindings && ts.isNamedImports(namedBindings)) {
+                namedBindings.elements.forEach((element) => names.add((element.propertyName ?? element.name).text));
+            }
+        }
+        if (ts.isExportDeclaration(node) && isQueryModule(node.moduleSpecifier) && node.exportClause) {
+            if (ts.isNamedExports(node.exportClause)) {
+                node.exportClause.elements.forEach((element) => names.add((element.propertyName ?? element.name).text));
+            }
+        }
+        if (ts.isImportTypeNode(node) &&
+            ts.isLiteralTypeNode(node.argument) &&
+            isQueryModule(node.argument.literal) &&
+            node.qualifier) {
+            names.add(getLeftmostIdentifier(node.qualifier).text);
+        }
+        const namespaceMember = getNamespaceMember(node, namespaceAliases)?.member;
+        if (namespaceMember) {
+            names.add(namespaceMember.text);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return new Set([...names].filter(isRenamedSymbol));
+}
+function getLeftmostIdentifier(name) {
+    return ts.isIdentifier(name) ? name : getLeftmostIdentifier(name.left);
+}
 //#endregion
 //# sourceMappingURL=migration.js.map