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

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

@@ -1,9 +1,13 @@
-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);
+    reportWithArgsNullReturns(tree);
+    replaceClearQueryArgs(tree);
+    reportPrebuiltPackagesImportingRenamedSymbols(tree);
     if (!schema.skipFormat) {
         await formatFiles(tree);
     }
@@ -73,10 +77,19 @@ function renameConflictingSymbols(tree) {
 }
 function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const checker = createBindingChecker(sourceFile);
     const replacements = [];
-    // Track which symbols are imported from @ethlete/query
-    const importedSymbols = new Set();
     const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
+    const renamedImports = new Map();
+    sourceFile.statements.forEach((statement) => {
+        getQueryNamedImports(statement)?.elements.forEach((element) => {
+            const newName = TYPE_RENAMES.get(element.name.text) || FUNCTION_RENAMES.get(element.name.text);
+            const symbol = checker.getSymbolAtLocation(element.name);
+            if (!element.propertyName && newName && symbol) {
+                renamedImports.set(symbol, { oldName: element.name.text, newName });
+            }
+        });
+    });
     function visit(node) {
         const namespaceMember = getNamespaceMember(node, namespaceAliases)?.member;
         const renamedMember = namespaceMember && (TYPE_RENAMES.get(namespaceMember.text) || FUNCTION_RENAMES.get(namespaceMember.text));
@@ -88,62 +101,29 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
                 oldName: namespaceMember.text,
             });
         }
-        // Track imports from @ethlete/query
-        if (ts.isImportDeclaration(node)) {
-            const moduleSpecifier = node.moduleSpecifier;
-            if (ts.isStringLiteral(moduleSpecifier) && moduleSpecifier.text === '@ethlete/query') {
-                const namedBindings = node.importClause?.namedBindings;
-                if (namedBindings && ts.isNamedImports(namedBindings)) {
-                    namedBindings.elements.forEach((element) => {
-                        const importedName = element.propertyName?.text || element.name.text;
-                        if (TYPE_RENAMES.has(importedName) || FUNCTION_RENAMES.has(importedName)) {
-                            importedSymbols.add(importedName);
-                        }
-                    });
-                }
-            }
-        }
-        // Rename identifiers that match our rename maps
-        if (ts.isIdentifier(node)) {
-            const name = node.text;
-            const parent = node.parent;
-            // Only rename if this symbol was imported from @ethlete/query
-            if (!importedSymbols.has(name)) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            const newName = TYPE_RENAMES.get(name) || FUNCTION_RENAMES.get(name);
-            if (!newName) {
-                ts.forEachChild(node, visit);
-                return;
-            }
-            // Skip if it's the imported name in an import specifier (we'll handle that separately)
-            if ((ts.isImportSpecifier(parent) && (parent.propertyName === node || parent.name === node)) ||
-                (ts.isPropertyAccessExpression(parent) && parent.name === node) ||
-                (ts.isQualifiedName(parent) && parent.right === node)) {
-                ts.forEachChild(node, visit);
-                return;
+        if (ts.isIdentifier(node) && !ts.isImportSpecifier(node.parent)) {
+            const symbol = resolveReferenceSymbol(checker, node);
+            const rename = symbol && renamedImports.get(symbol);
+            if (rename) {
+                replacements.push({
+                    start: node.getStart(sourceFile),
+                    end: node.getEnd(),
+                    replacement: ts.isShorthandPropertyAssignment(node.parent)
+                        ? `${rename.oldName}: ${rename.newName}`
+                        : rename.newName,
+                    oldName: rename.oldName,
+                });
             }
-            // Rename the identifier
-            replacements.push({
-                start: node.getStart(sourceFile),
-                end: node.getEnd(),
-                replacement: newName,
-                oldName: name,
-            });
         }
         ts.forEachChild(node, visit);
     }
     visit(sourceFile);
-    // Update imports in @ethlete/query import declarations
     const importReplacements = updateImports(sourceFile);
     replacements.push(...importReplacements);
-    // Count usages
     replacements.forEach((r) => {
         const count = symbolUsageCounts.get(r.oldName) || 0;
         symbolUsageCounts.set(r.oldName, count + 1);
     });
-    // Apply replacements in reverse order
     let result = content;
     replacements.sort((a, b) => b.start - a.start);
     for (const { start, end, replacement } of replacements) {
@@ -151,6 +131,26 @@ function renameSymbolsInFile(content, filePath, symbolUsageCounts) {
     }
     return result;
 }
+function createBindingChecker(sourceFile) {
+    const options = { noLib: true, noResolve: true, types: [] };
+    const host = ts.createCompilerHost(options);
+    host.getSourceFile = (fileName) => (fileName === sourceFile.fileName ? sourceFile : undefined);
+    host.fileExists = (fileName) => fileName === sourceFile.fileName;
+    host.readFile = (fileName) => (fileName === sourceFile.fileName ? sourceFile.text : undefined);
+    return ts.createProgram([sourceFile.fileName], options, host).getTypeChecker();
+}
+function resolveReferenceSymbol(checker, identifier) {
+    const parent = identifier.parent;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === identifier) {
+        return checker.getShorthandAssignmentValueSymbol(parent);
+    }
+    if (ts.isExportSpecifier(parent)) {
+        return (parent.propertyName ?? parent.name) === identifier && !parent.parent.parent.moduleSpecifier
+            ? checker.getExportSpecifierLocalTargetSymbol(parent)
+            : undefined;
+    }
+    return checker.getSymbolAtLocation(identifier);
+}
 function collectQueryNamespaceAliases(sourceFile) {
     const aliases = new Set();
     sourceFile.statements.forEach((statement) => {
@@ -224,6 +224,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 +241,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)`);
     }
@@ -278,14 +285,13 @@ function replaceNamespaceInFile(content, filePath) {
     if (!hasExperimentalQueryImport || !experimentalQueryAlias) {
         return applyReplacements(content, namespaceReplacements, namespaceReplacements.length);
     }
+    const getAliasMember = (node) => getNamespaceMember(node, new Set([experimentalQueryAlias]))?.member;
     // Second pass: collect used symbols
     function findUsages(node) {
         // Find usages: ExperimentalQuery.someSymbol or E.someSymbol (if aliased)
-        if (ts.isPropertyAccessExpression(node) &&
-            ts.isIdentifier(node.expression) &&
-            node.expression.text === experimentalQueryAlias) {
-            const symbolName = node.name.text;
-            usedSymbols.add(symbolName);
+        const member = getAliasMember(node);
+        if (member) {
+            usedSymbols.add(member.text);
         }
         ts.forEachChild(node, findUsages);
     }
@@ -343,13 +349,12 @@ function replaceNamespaceInFile(content, filePath) {
             }
         }
         // Replace usages: ExperimentalQuery.someSymbol → someSymbol
-        if (ts.isPropertyAccessExpression(node) &&
-            ts.isIdentifier(node.expression) &&
-            node.expression.text === experimentalQueryAlias) {
+        const member = getAliasMember(node);
+        if (member) {
             replacements.push({
                 start: node.getStart(sourceFile),
                 end: node.getEnd(),
-                replacement: node.name.text,
+                replacement: member.text,
             });
         }
         ts.forEachChild(node, createReplacements);
@@ -383,4 +388,342 @@ function applyReplacements(content, replacements, replacementCount) {
     return { content: result, modified: replacements.length > 0, replacementCount };
 }
 //#endregion
+//#region withArgs null returns
+function reportWithArgsNullReturns(tree) {
+    const sites = [];
+    const uncheckedSites = [];
+    visitQueryFiles(tree, ['withArgs'], (filePath, content) => {
+        const { nullLines, uncheckedLines } = findWithArgsNullReturns(createSourceFile(content, filePath));
+        nullLines.forEach((line) => sites.push(`   - ${filePath}:${line}`));
+        uncheckedLines.forEach((line) => uncheckedSites.push(`   - ${filePath}:${line}`));
+    });
+    if (sites.length > 0) {
+        console.warn(`\n⚠️ These withArgs callbacks return null. Before v3, null kept the previous args; v3 parks the query instead (args, response and executionState become null, and polling pauses). Check each one: a null that should park the query is fine, one that relied on keeping the previous args must now return those args itself:\n${sites.join('\n')}`);
+    }
+    if (uncheckedSites.length > 0) {
+        console.warn(`\n⚠️ TODO: These withArgs callbacks are passed by reference from somewhere this file does not declare, so they could not be checked for a null return. Check each one by hand - v3 parks the query on null, where earlier versions kept the previous args:\n${uncheckedSites.join('\n')}`);
+    }
+}
+const isCheckableFunction = (node) => !!node &&
+    (ts.isArrowFunction(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node)) &&
+    !!node.body;
+function resolveCallbackReference(checker, source) {
+    const name = ts.isPropertyAccessExpression(source) ? source.name : source;
+    if (!ts.isIdentifier(name))
+        return undefined;
+    const declaration = checker.getSymbolAtLocation(name)?.valueDeclaration;
+    if (isCheckableFunction(declaration))
+        return declaration;
+    if (!declaration || !(ts.isVariableDeclaration(declaration) || ts.isPropertyDeclaration(declaration))) {
+        return undefined;
+    }
+    const initializer = declaration.initializer && skipOuterExpressions(declaration.initializer);
+    if (isCheckableFunction(initializer))
+        return initializer;
+    if (initializer &&
+        ts.isCallExpression(initializer) &&
+        ts.isIdentifier(initializer.expression) &&
+        initializer.expression.text === 'computed') {
+        const [computation] = initializer.arguments;
+        return isCheckableFunction(computation) ? computation : undefined;
+    }
+    return undefined;
+}
+function skipOuterExpressions(expression) {
+    return ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression)
+        ? skipOuterExpressions(expression.expression)
+        : expression;
+}
+function findWithArgsNullReturns(sourceFile) {
+    const checker = createBindingChecker(sourceFile);
+    const withArgsImports = new Set();
+    const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
+    const nullLines = [];
+    const uncheckedLines = [];
+    const lineOf = (node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+    sourceFile.statements.forEach((statement) => {
+        getQueryNamedImports(statement)?.elements.forEach((element) => {
+            const symbol = checker.getSymbolAtLocation(element.name);
+            if ((element.propertyName ?? element.name).text === 'withArgs' && symbol)
+                withArgsImports.add(symbol);
+        });
+    });
+    const isWithArgsCallee = (callee) => {
+        if (ts.isIdentifier(callee)) {
+            const symbol = checker.getSymbolAtLocation(callee);
+            return !!symbol && withArgsImports.has(symbol);
+        }
+        return getNamespaceMember(callee, namespaceAliases)?.member.text === 'withArgs';
+    };
+    function visit(node) {
+        if (ts.isCallExpression(node) && isWithArgsCallee(node.expression)) {
+            const [source] = node.arguments;
+            const callback = source && (isCheckableFunction(source) ? source : resolveCallbackReference(checker, source));
+            if (callback) {
+                collectNullReturns(callback).forEach((nullNode) => nullLines.push(lineOf(nullNode)));
+            }
+            else if (source) {
+                uncheckedLines.push(lineOf(source));
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return { nullLines: [...new Set(nullLines)].sort((a, b) => a - b), uncheckedLines };
+}
+function collectNullReturns(fn) {
+    if (!ts.isBlock(fn.body)) {
+        return findNullResults(fn.body);
+    }
+    const found = [];
+    function visit(node) {
+        if (ts.isFunctionLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression) {
+            found.push(...findNullResults(node.expression));
+        }
+        ts.forEachChild(node, visit);
+    }
+    ts.forEachChild(fn.body, visit);
+    return found;
+}
+function findNullResults(expression) {
+    if (expression.kind === ts.SyntaxKind.NullKeyword)
+        return [expression];
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isTypeAssertionExpression(expression)) {
+        return findNullResults(expression.expression);
+    }
+    if (ts.isConditionalExpression(expression)) {
+        return [...findNullResults(expression.whenTrue), ...findNullResults(expression.whenFalse)];
+    }
+    if (ts.isBinaryExpression(expression) &&
+        [ts.SyntaxKind.QuestionQuestionToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.AmpersandAmpersandToken].includes(expression.operatorToken.kind)) {
+        return findNullResults(expression.right);
+    }
+    return [];
+}
+//#endregion
+//#region CLEAR_QUERY_ARGS replacement
+const CLEAR_QUERY_ARGS_NAMES = new Set(['CLEAR_QUERY_ARGS', 'ClearQueryArgs']);
+function replaceClearQueryArgs(tree) {
+    const updatedFiles = [];
+    const reExports = [];
+    visitQueryFiles(tree, [...CLEAR_QUERY_ARGS_NAMES], (filePath, content) => {
+        const result = replaceClearQueryArgsInFile(content, filePath);
+        if (result.content !== content) {
+            tree.write(filePath, result.content);
+            updatedFiles.push(filePath);
+        }
+        result.reExportLines.forEach((line) => reExports.push(`   - ${filePath}:${line}`));
+    });
+    if (updatedFiles.length > 0) {
+        console.log(`\n🅿️ Replaced CLEAR_QUERY_ARGS with null (the v3 park value) in ${updatedFiles.length} files: ${updatedFiles.join(', ')}`);
+    }
+    if (reExports.length > 0) {
+        console.warn(`\n⚠️ These files re-exported CLEAR_QUERY_ARGS or ClearQueryArgs. They now export a local \`null\` under the same name, so their importers keep compiling. Replace each import of it with \`null\`, then delete the export:\n${reExports.join('\n')}`);
+    }
+}
+function replaceClearQueryArgsInFile(content, filePath) {
+    const sourceFile = createSourceFile(content, filePath);
+    const checker = createBindingChecker(sourceFile);
+    const namespaceAliases = collectQueryNamespaceAliases(sourceFile);
+    const clearImports = new Map();
+    const replacements = [];
+    const reExportLines = [];
+    const statementEnd = (statement) => content[statement.getEnd()] === '\n' ? statement.getEnd() + 1 : statement.getEnd();
+    sourceFile.statements.forEach((statement) => {
+        const namedBindings = getQueryNamedImports(statement);
+        if (!namedBindings)
+            return;
+        const kept = namedBindings.elements.filter((element) => {
+            const importedName = (element.propertyName ?? element.name).text;
+            if (!CLEAR_QUERY_ARGS_NAMES.has(importedName))
+                return true;
+            const symbol = checker.getSymbolAtLocation(element.name);
+            if (symbol)
+                clearImports.set(symbol, importedName);
+            return false;
+        });
+        if (kept.length === namedBindings.elements.length)
+            return;
+        const importClause = statement.importClause;
+        if (kept.length === 0 && !importClause?.name) {
+            replacements.push({ start: statement.getStart(sourceFile), end: statementEnd(statement), replacement: '' });
+            return;
+        }
+        replacements.push({
+            start: namedBindings.getStart(sourceFile),
+            end: namedBindings.getEnd(),
+            replacement: `{ ${kept.map((element) => element.getText(sourceFile)).join(', ')} }`,
+        });
+    });
+    sourceFile.statements.forEach((statement) => {
+        if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) {
+            return;
+        }
+        const fromQuery = isQueryModuleSpecifier(statement.moduleSpecifier);
+        if (statement.moduleSpecifier && !fromQuery)
+            return;
+        const clearedName = (element) => {
+            if (fromQuery) {
+                const exportedName = (element.propertyName ?? element.name).text;
+                return CLEAR_QUERY_ARGS_NAMES.has(exportedName) ? exportedName : undefined;
+            }
+            const symbol = checker.getExportSpecifierLocalTargetSymbol(element);
+            return symbol && clearImports.get(symbol);
+        };
+        const elements = statement.exportClause.elements;
+        const nullExports = elements.flatMap((element) => {
+            const name = clearedName(element);
+            if (!name)
+                return [];
+            return [`export ${name === 'ClearQueryArgs' ? 'type' : 'const'} ${element.name.text} = null;`];
+        });
+        if (nullExports.length === 0)
+            return;
+        reExportLines.push(sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile)).line + 1);
+        const kept = elements.filter((element) => !clearedName(element));
+        if (kept.length === 0) {
+            replacements.push({
+                start: statement.getStart(sourceFile),
+                end: statement.getEnd(),
+                replacement: nullExports.join('\n'),
+            });
+            return;
+        }
+        replacements.push({
+            start: statement.exportClause.getStart(sourceFile),
+            end: statement.exportClause.getEnd(),
+            replacement: `{ ${kept.map((element) => element.getText(sourceFile)).join(', ')} }`,
+        });
+        replacements.push({
+            start: statement.getEnd(),
+            end: statement.getEnd(),
+            replacement: `\n${nullExports.join('\n')}`,
+        });
+    });
+    function visit(node) {
+        const namespaceMember = getNamespaceMember(node, namespaceAliases)?.member;
+        const referencesImport = () => {
+            const symbol = ts.isIdentifier(node) ? resolveReferenceSymbol(checker, node) : undefined;
+            return !!symbol && clearImports.has(symbol);
+        };
+        if ((namespaceMember && CLEAR_QUERY_ARGS_NAMES.has(namespaceMember.text)) || referencesImport()) {
+            const target = ts.isTypeQueryNode(node.parent) ? node.parent : node;
+            const replacement = ts.isShorthandPropertyAssignment(node.parent) ? `${node.getText(sourceFile)}: null` : 'null';
+            replacements.push({ start: target.getStart(sourceFile), end: target.getEnd(), replacement });
+            return;
+        }
+        ts.forEachChild(node, visit);
+    }
+    sourceFile.statements.forEach((statement) => {
+        if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+            visit(statement);
+    });
+    return { content: applyReplacements(content, replacements, replacements.length).content, reExportLines };
+}
+function isQueryModuleSpecifier(node) {
+    return !!node && ts.isStringLiteral(node) && node.text === '@ethlete/query';
+}
+function visitQueryFiles(tree, markers, visitor) {
+    visitNotIgnoredFiles(tree, '', (filePath) => {
+        if (!filePath.endsWith('.ts') || filePath.endsWith('.spec.ts'))
+            return;
+        const content = tree.read(filePath, 'utf-8');
+        if (!content?.includes('@ethlete/query') || !markers.some((marker) => content.includes(marker)))
+            return;
+        visitor(filePath, content);
+    });
+}
+function getQueryNamedImports(statement) {
+    if (!ts.isImportDeclaration(statement) ||
+        !ts.isStringLiteral(statement.moduleSpecifier) ||
+        statement.moduleSpecifier.text !== '@ethlete/query') {
+        return undefined;
+    }
+    const namedBindings = statement.importClause?.namedBindings;
+    return namedBindings && ts.isNamedImports(namedBindings) ? namedBindings : undefined;
+}
+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

package/migrations/query-field-default-types.md

@@ -0,0 +1,43 @@
+# `queryField<T>()` is typed by its default and reads the URL into that type
+
+`queryField<T>()` used to be typed `T | null` whatever its default, and guessed the type of a URL
+value: `?id=123` became the number `123` even in a `queryField<string>()`. Now:
+
+- A field with a non-null `defaultValue` is typed `T`, and a reset or an unreadable URL value falls
+  back to the default.
+- A URL value is read into the type of the default (number, boolean, string, string list). Without a
+  default it stays a string.
+- Any other `T` needs a `queryParamToValue`: `queryField<number>()` without a default, a `Date` or an
+  object default.
+- `searchQueryField()` and `sortQueryField()` no longer count in `activeFilterCount`, whatever their key.
+
+The type check finds every call site that has to change.
+
+## Find the call sites
+
+```bash
+grep -rnE '\bqueryField<' apps libs --include='*.ts'
+```
+
+## What to change
+
+1. `queryField<number>()` or `queryField<boolean>()` without a default: give it the `defaultValue` it
+   effectively had, or add `queryParamToValue: transformToNumber` (`transformToBoolean`, …) and keep
+   the `null` start. Both transforms are exported from `@ethlete/query`.
+2. A `Date` or object default without a `queryParamToValue`: add one (`transformToDate` for a date).
+3. A field that must hold `null` beside a non-null default - an explicit "none" - is declared
+   `queryField<T | null>({ defaultValue: … })`.
+4. Delete the `?? DEFAULT` on reads of a field that now has a non-null type, and any `!` or cast that
+   only existed to strip `null`.
+5. A field bound to a native `<input type="number">` is declared `number | null`: the input writes
+   `null` when cleared.
+6. A field that relied on the old guess - a `queryField<string>()` read as a number somewhere - gets
+   the type it was really used as.
+7. A UI that counted a search or sort field as a filter: pass `skipInFilterCount: false` to keep it.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed, and check in the
+browser that a reload restores each list.
+
+The query forms guide is at <https://ethlete-sdk-docs.web.app/query/query-forms>.

package/migrations/search-query-field-string.md

@@ -0,0 +1,43 @@
+# `searchQueryField()` is a `string` that starts at `''`
+
+`searchQueryField()` used to be typed `string | null` and start at `null`. It is typed `string` now and
+starts at `''`, so `[formField]` binds it to `<et-input>` under `strictTemplates`. An empty search still
+writes no URL param, so URLs do not change. The type check finds most call sites; a comparison with
+`null` compiles and silently stops matching.
+
+## Find the call sites
+
+```bash
+grep -rnE 'searchQueryField\(' apps libs --include='*.ts' -l
+```
+
+In each file found, and in each file that reads the form's value, look for the search field's key
+(`search`, `query`, `q`, …) next to `null`:
+
+```bash
+grep -rnE '(search|query|q)\b[^;]*(null|\?\?)' apps libs --include='*.ts'
+```
+
+## What to change
+
+1. A write of `null` - `setValue({ search: null, … })`, `patchValue({ search: null })`, a seed object,
+   a test fixture - writes `''` instead.
+2. A check for an empty search - `search === null`, `search !== null`, `search == null`,
+   `search ?? ''` - becomes `search === ''`, `search !== ''`, or just `search`. `?? ''` is dead code
+   now; delete it.
+3. A search that goes into a request body or GraphQL variables passes `search || null` where the API
+   expects `null` for "no search". Query params need nothing: the client drops an empty string.
+4. A type that restates the value, such as `search: string | null` in an interface built from the
+   form, becomes `string`. Prefer deriving it from `ReturnType<typeof qf.value>`.
+5. A test that expects `null` for an empty search expects `''`.
+
+## Leave these alone
+
+- `queryField<string>()` fields. They still start at `null`.
+- The legacy `SearchQueryField` class. It is unchanged.
+
+## When you are done
+
+Run the type check, the lint task and the tests of every project you changed.
+
+The query forms guide is at <https://ethlete-sdk-docs.web.app/query/query-forms>.

package/migrations.json

@@ -39,6 +39,22 @@
       "description": "Mark the remaining createLegacyQueryCreator wrappers as deprecated, so their call sites surface as still on v2.",
       "generator": "@ethlete/query:deprecate-legacy-queries",
       "docs": "/query/legacy"
+    },
+    {
+      "name": "search-query-field-string",
+      "version": "6.0.0-next.52",
+      "kind": "assisted",
+      "description": "searchQueryField() is typed string and starts at '' instead of null; writes and checks of null move to ''.",
+      "instructions": "./migrations/search-query-field-string.md",
+      "docs": "/query/query-forms"
+    },
+    {
+      "name": "query-field-default-types",
+      "version": "6.0.0-next.52",
+      "kind": "assisted",
+      "description": "queryField() is typed by its default and reads the URL into that type; fields without a default or with a non-primitive one need a queryParamToValue.",
+      "instructions": "./migrations/query-field-default-types.md",
+      "docs": "/query/query-forms"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/query",
-  "version": "6.0.0-next.51",
+  "version": "6.0.0-next.53",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
@@ -44,6 +44,10 @@
       "types": "./types/ethlete-query.d.ts",
       "default": "./fesm2022/ethlete-query.mjs"
     },
+    "./ngrx-toolkit": {
+      "types": "./types/ethlete-query-ngrx-toolkit.d.ts",
+      "default": "./fesm2022/ethlete-query-ngrx-toolkit.mjs"
+    },
     "./testing": {
       "types": "./types/ethlete-query-testing.d.ts",
       "default": "./fesm2022/ethlete-query-testing.mjs"