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

package/generators/deprecate-legacy-queries/migration.js

@@ -0,0 +1,77 @@
+import { formatFiles } from '@nx/devkit';
+import * as ts from 'typescript';
+import { createMigrationScope } from '../migrate-to-query-v3/migration-scope.js';
+import { addJsDocTag, createSourceFile, legacyQueryDeprecationTag } from '../migrate-to-query-v3/shared.js';
+const CREATOR_FN = 'createLegacyQueryCreator';
+const isMigratableFile = (filePath) => /\.(ts|mts|cts)$/.test(filePath) && !filePath.endsWith('.d.ts');
+const creatorNameOf = (call, sourceFile) => {
+    const [options] = call.arguments;
+    if (!options || !ts.isObjectLiteralExpression(options)) {
+        return undefined;
+    }
+    const property = options.properties.find((candidate) => ts.isPropertyAssignment(candidate) && candidate.name.getText(sourceFile) === 'creator');
+    if (!property || !ts.isIdentifier(property.initializer)) {
+        return undefined;
+    }
+    return property.initializer.text;
+};
+const collectWrappers = (sourceFile) => {
+    const wrappers = [];
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            ts.isIdentifier(node.initializer.expression) &&
+            node.initializer.expression.text === CREATOR_FN) {
+            const statement = node.parent.parent;
+            // A wrapper declared inside a function body has no importable call sites to strike through.
+            if (ts.isVariableStatement(statement) && ts.isSourceFile(statement.parent)) {
+                wrappers.push({ statement, creatorName: creatorNameOf(node.initializer, sourceFile) });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return wrappers;
+};
+export const deprecateLegacyQueries = (tree, scope) => {
+    let deprecatedWrappers = 0;
+    let touchedFiles = 0;
+    scope.visit(tree, (filePath) => {
+        if (!isMigratableFile(filePath))
+            return;
+        const content = tree.read(filePath, 'utf-8');
+        if (!content?.includes(CREATOR_FN))
+            return;
+        const sourceFile = createSourceFile(content, filePath);
+        const wrappers = collectWrappers(sourceFile);
+        let nextContent = content;
+        let tagged = 0;
+        // Back to front, so an insertion never shifts the position the next wrapper was parsed at.
+        for (const wrapper of wrappers.sort((a, b) => b.statement.getStart(sourceFile) - a.statement.getStart(sourceFile))) {
+            const updated = addJsDocTag(nextContent, sourceFile, wrapper.statement, legacyQueryDeprecationTag(wrapper.creatorName));
+            if (updated === null)
+                continue;
+            nextContent = updated;
+            tagged += 1;
+        }
+        if (tagged === 0)
+            return;
+        tree.write(filePath, nextContent);
+        deprecatedWrappers += tagged;
+        touchedFiles += 1;
+    });
+    return { deprecatedWrappers, touchedFiles };
+};
+export default async function migrate(tree, schema) {
+    console.log('\n🔄 Deprecating legacy query wrappers...');
+    const scope = createMigrationScope(tree, schema);
+    console.log(`   Scope: ${scope.describe()}`);
+    const { deprecatedWrappers, touchedFiles } = deprecateLegacyQueries(tree, scope);
+    console.log(`   Tagged ${deprecatedWrappers} wrapper${deprecatedWrappers === 1 ? '' : 's'} in ${touchedFiles} file${touchedFiles === 1 ? '' : 's'}.`);
+    if (!schema.skipFormat) {
+        await formatFiles(tree);
+    }
+    console.log('\n✅ Legacy query wrappers deprecated successfully!');
+}
+//# sourceMappingURL=migration.js.map

package/generators/deprecate-legacy-queries/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "deprecate-legacy-queries",
+  "title": "Deprecate legacy query wrappers",
+  "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"
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after migration",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators/generators.json

@@ -15,6 +15,11 @@
       "schema": "./prep-for-query-v3/schema.json",
       "description": "Update code to prepare for migration to query v3"
     },
+    "deprecate-legacy-queries": {
+      "factory": "./deprecate-legacy-queries/migration",
+      "schema": "./deprecate-legacy-queries/schema.json",
+      "description": "Mark existing createLegacyQueryCreator wrappers as @deprecated so their call sites surface as still on v2"
+    },
     "migrate-query-opt-in-features": {
       "factory": "./migrate-query-opt-in-features/migration",
       "schema": "./migrate-query-opt-in-features/schema.json",

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, ensureImportFromEthleteCore, 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 = [];

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

@@ -96,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.23",
+  "version": "6.0.0-next.24",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {