@ethlete/query 6.0.0-next.19 → 6.0.0-next.20

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

@@ -1,10 +1,9 @@
-import { visitNotIgnoredFiles } from '@nx/devkit';
 import * as ts from 'typescript';
 import { capitalizeFirstLetter, createSourceFile, ensureConfigSuffix, ensureImportFromQuery, getVariableStatementEnd, } from './shared.js';
-export const migrateQueryClients = (tree, report) => {
+export const migrateQueryClients = (tree, report, scope) => {
     const queryClientFiles = new Map();
     const variableRenames = new Map();
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts')) {
             return;
         }
@@ -69,11 +68,11 @@ export const generateQueryCreators = (tree, queryClientFiles) => {
         generatedFiles.forEach((filePath) => console.log(`   - ${filePath}`));
     }
 };
-export const updateImportsAcrossWorkspace = (tree, renames) => {
+export const updateImportsAcrossWorkspace = (tree, renames, scope) => {
     if (renames.size === 0) {
         return;
     }
-    visitNotIgnoredFiles(tree, '', (filePath) => {
+    scope.visit(tree, (filePath) => {
         if (!filePath.endsWith('.ts')) {
             return;
         }
@@ -143,6 +142,7 @@ const migrateQueryClientToConfig = ({ content, filePath, renamesOut, report }) =
                         renamesOut.set(oldVariableName, newVariableName);
                     }
                 }
+                reportDroppedClientOptions({ configArgument, sourceFile, filePath, report });
                 replacements.push({
                     start: node.getStart(sourceFile),
                     end: node.getEnd(),
@@ -241,6 +241,54 @@ const renameVariables = (content, renames) => {
     });
     return result;
 };
+/**
+ * What each v2 client option turns into, or why it has nowhere to go.
+ *
+ * Silently dropping these is how two apps here lost their default headers without a single warning.
+ * A dropped option that shows up in the report is a five-minute fix; one that doesn't is a bug
+ * 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.',
+    '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()`.',
+};
+const reportDroppedClientOptions = ({ configArgument, sourceFile, filePath, report, }) => {
+    const migrated = new Set(['baseRoute', 'queryParams', 'cacheAdapter', 'retryFn', 'request', 'logging']);
+    const raise = (optionPath, node) => {
+        report.addWarning({
+            title: `Reconfigure dropped query client option "${optionPath}"`,
+            summary: `The v2 client option \`${optionPath}\` has no place in \`createQueryClient\` and was dropped by the migration.`,
+            action: DROPPED_CLIENT_OPTIONS[optionPath] ?? 'Check whether the behaviour is still needed and reimplement it.',
+            locations: [{ filePath, line: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 }],
+            source: 'query-client-migration',
+            dedupeKey: `dropped-client-option:${filePath}:${optionPath}`,
+        });
+    };
+    configArgument.properties.forEach((property) => {
+        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
+            return;
+        }
+        const name = property.name.text;
+        if ((name === 'request' || name === 'logging') && ts.isObjectLiteralExpression(property.initializer)) {
+            property.initializer.properties.forEach((nested) => {
+                if (!ts.isPropertyAssignment(nested) || !ts.isIdentifier(nested.name)) {
+                    return;
+                }
+                if (name === 'request' && ['queryParams', 'cacheAdapter', 'retryFn'].includes(nested.name.text)) {
+                    return;
+                }
+                raise(`${name}.${nested.name.text}`, nested);
+            });
+            return;
+        }
+        if (!migrated.has(name)) {
+            raise(name, property);
+        }
+    });
+};
 const migrateConfigObject = (configArgument, node, sourceFile) => {
     const variableName = getVariableNameForQueryClient(node);
     const nextConfig = [];

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

@@ -0,0 +1,193 @@
+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
+ * 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.
+ */
+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.
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node)
+        return true;
+    if (ts.isQualifiedName(parent) && parent.right === node)
+        return true;
+    // Object literal / type member keys, enum members, JSX-ish attribute names.
+    if (ts.isPropertyAssignment(parent) && parent.name === node)
+        return true;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === node)
+        return true;
+    if (ts.isPropertySignature(parent) && parent.name === node)
+        return true;
+    if (ts.isMethodSignature(parent) && parent.name === node)
+        return true;
+    if (ts.isEnumMember(parent) && parent.name === node)
+        return true;
+    if (ts.isBindingElement(parent) && parent.propertyName === node)
+        return true;
+    // Declarations of any kind.
+    if (ts.isVariableDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isFunctionDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isClassDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isInterfaceDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isTypeAliasDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isEnumDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isModuleDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isMethodDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isPropertyDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isGetAccessorDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isSetAccessorDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isParameter(parent) && parent.name === node)
+        return true;
+    if (ts.isTypeParameterDeclaration(parent) && parent.name === node)
+        return true;
+    if (ts.isLabeledStatement(parent) && parent.label === node)
+        return true;
+    // Import / export clauses are rewritten by the caller, never by the reference pass.
+    if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent))
+        return true;
+    if (ts.isImportClause(parent) || ts.isNamespaceImport(parent))
+        return true;
+    return false;
+};
+/** 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) => {
+        if (name && ts.isIdentifier(name))
+            declared.add(name.text);
+    };
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node))
+            add(node.name);
+        if (ts.isFunctionDeclaration(node))
+            add(node.name);
+        if (ts.isClassDeclaration(node))
+            add(node.name);
+        if (ts.isInterfaceDeclaration(node))
+            add(node.name);
+        if (ts.isTypeAliasDeclaration(node))
+            add(node.name);
+        if (ts.isEnumDeclaration(node))
+            add(node.name);
+        if (ts.isParameter(node))
+            add(node.name);
+        if (ts.isBindingElement(node))
+            add(node.name);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return declared;
+};
+/**
+ * Renames references to imported bindings, and only those.
+ *
+ * `renames` maps a *local binding name* to its new name. The caller is responsible for having
+ * verified that the binding really is the symbol being migrated (see `ModuleGraph`); this pass only
+ * makes sure the rewrite lands on references rather than on same-named properties, declarations or
+ * type members. A name the file also declares locally is skipped entirely and reported back, since
+ * a rename there would silently change which value the code reads.
+ */
+export const renameImportedReferences = (content, renames) => {
+    if (renames.size === 0)
+        return { content, shadowed: [] };
+    const sourceFile = createSourceFile(content);
+    const declaredLocally = collectLocalDeclarations(sourceFile);
+    const shadowed = Array.from(renames.keys()).filter((name) => declaredLocally.has(name));
+    const applicable = new Map(Array.from(renames.entries()).filter(([name]) => !declaredLocally.has(name)));
+    if (applicable.size === 0)
+        return { content, shadowed };
+    const replacements = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node)) {
+            const nextName = applicable.get(node.text);
+            if (nextName && !isNamePosition(node)) {
+                replacements.push({ start: node.getStart(sourceFile), end: node.getEnd(), replacement: nextName });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    let result = content;
+    replacements.sort((left, right) => right.start - left.start);
+    replacements.forEach(({ start, end, replacement }) => {
+        result = result.slice(0, start) + replacement + result.slice(end);
+    });
+    return { content: result, shadowed };
+};
+/**
+ * Drops named imports whose local name no longer appears anywhere else in the file.
+ *
+ * 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.
+ */
+export const pruneUnusedNamedImports = (content, moduleSpecifiers) => {
+    const sourceFile = createSourceFile(content);
+    const used = new Set();
+    const addWordsFrom = (text) => {
+        for (const word of text.match(/[A-Za-z_$][\w$]*/g) ?? []) {
+            used.add(word);
+        }
+    };
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && !ts.isImportSpecifier(node.parent) && !ts.isImportClause(node.parent)) {
+            used.add(node.text);
+        }
+        // A symbol referenced only from an inline template or a `styleUrl`-style string is still used.
+        if (ts.isStringLiteralLike(node) && !ts.isImportDeclaration(node.parent)) {
+            addWordsFrom(node.text);
+        }
+        if (ts.isTemplateLiteralToken(node)) {
+            addWordsFrom(node.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const replacements = [];
+    for (const node of sourceFile.statements) {
+        if (!ts.isImportDeclaration(node) ||
+            !ts.isStringLiteral(node.moduleSpecifier) ||
+            (moduleSpecifiers !== 'all' && !moduleSpecifiers.includes(node.moduleSpecifier.text)) ||
+            !node.importClause?.namedBindings ||
+            !ts.isNamedImports(node.importClause.namedBindings)) {
+            continue;
+        }
+        const kept = node.importClause.namedBindings.elements.filter((element) => used.has(element.name.text));
+        if (kept.length === node.importClause.namedBindings.elements.length)
+            continue;
+        const hasDefaultImport = !!node.importClause.name;
+        if (kept.length === 0 && !hasDefaultImport) {
+            const end = content[node.getEnd()] === '\n' ? node.getEnd() + 1 : node.getEnd();
+            replacements.push({ start: node.getStart(sourceFile), end, replacement: '' });
+            continue;
+        }
+        const defaultPart = hasDefaultImport ? `${node.importClause.name.text}, ` : '';
+        replacements.push({
+            start: node.getStart(sourceFile),
+            end: node.getEnd(),
+            replacement: `import ${defaultPart}{ ${kept.map((element) => element.getText(sourceFile)).join(', ')} } from '${node.moduleSpecifier.text}';`,
+        });
+    }
+    let result = content;
+    replacements.sort((left, right) => right.start - left.start);
+    replacements.forEach(({ start, end, replacement }) => {
+        result = result.slice(0, start) + replacement + result.slice(end);
+    });
+    return result;
+};
+//# sourceMappingURL=rename-symbols.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.19",
+  "version": "6.0.0-next.20",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {