From 908913118439610c80a23f88d5f6850e20950660 Mon Sep 17 00:00:00 2001 From: Loc Nguyen <113083148+thailoc-dev@users.noreply.github.com> Date: Fri, 2 Oct 2026 08:27:36 +0700 Subject: [PATCH] feat(completion): complete mongo aggregation field references --- apps/desktop/src/lib/mongo/mongoCompletion.ts | 142 ++++++++++++++++- .../src/lib/mongo/mongoCompletionTables.ts | 6 + packages/app-tests/mongoCompletion.test.ts | 147 ++++++++++++++++++ 3 files changed, 291 insertions(+), 4 deletions(-) diff --git a/apps/desktop/src/lib/mongo/mongoCompletion.ts b/apps/desktop/src/lib/mongo/mongoCompletion.ts index 1265d700c6..2a9587a24a 100644 --- a/apps/desktop/src/lib/mongo/mongoCompletion.ts +++ b/apps/desktop/src/lib/mongo/mongoCompletion.ts @@ -117,6 +117,8 @@ export interface MongoCompletionContext { operator?: string; /** Which fixed value set the cursor's value position accepts (`$type`, `explain`, `caseFirst`). */ enumKey?: string; + /** User variables in scope for aggregation expressions. */ + variables?: string[]; } export interface MongoCompletionInput { @@ -434,11 +436,13 @@ export function getMongoCompletionContext(text: string, cursor: number): MongoCo if (!scan) return isInsideCallArguments(beforeCursor) || isAfterUseKeyword(beforeCursor) || isAfterShowKeyword(beforeCursor) ? at("none") : at("root"); const classified = classifyCursorInCall(call.method, scan); + const variables = classified.mode === "fieldRef" || classified.mode === "expression" ? collectScopeVariables(scan) : undefined; return { ...at(classified.mode, classified.stage, classified.method, classified.bulkWriteOperation, classified.keyMap), ...(classified.operator ? { operator: classified.operator } : {}), ...(classified.enumKey ? { enumKey: classified.enumKey } : {}), ...(classified.pipelineKind ? { pipelineKind: classified.pipelineKind } : {}), + ...(variables ? { variables } : {}), collection: classified.collection ?? collection, }; } @@ -496,7 +500,7 @@ export function buildMongoCompletionItemsFromContext(context: MongoCompletionCon items = fieldPathItems(prefix, fields); break; case "fieldRef": - items = fieldRefItems(prefix, fields); + items = isVariablePrefix(prefix) ? variableItems(prefix, context.variables, context.stage) : fieldRefItems(prefix, fields); break; case "indexName": items = indexNameItems(prefix, input.indexes ?? [], context.method); @@ -522,7 +526,7 @@ export function buildMongoCompletionItemsFromContext(context: MongoCompletionCon items = specItems(PROJECTION_OPERATORS, prefix, "projection operator", 100); break; case "expression": - items = [...specItems(EXPRESSION_OPERATORS, prefix, "aggregation expression", 100), ...fieldRefItems(prefix, fields, 80)]; + items = isVariablePrefix(prefix) ? variableItems(prefix, context.variables, context.stage) : [...specItems(EXPRESSION_OPERATORS, prefix, "aggregation expression", 100), ...fieldRefItems(prefix, fields, 80)]; break; case "accumulator": items = specItems(ACCUMULATORS, prefix, "accumulator", 100); @@ -633,7 +637,8 @@ export function getMongoDocumentQueryCompletionContext(text: string, cursor: num if (classified.mode === "none") return nothing; const { prefix, from } = readMongoPropertyPrefix(text, safeCursor); - return { ...classified, prefix, from, replaceClosingQuote: closingQuoteAtCursor(prefix, text, safeCursor) }; + const variables = classified.mode === "fieldRef" || classified.mode === "expression" ? collectScopeVariables(scan) : undefined; + return { ...classified, prefix, from, replaceClosingQuote: closingQuoteAtCursor(prefix, text, safeCursor), ...(variables ? { variables } : {}) }; } /** @@ -755,6 +760,10 @@ interface MongoContainer { key: string | null; /** Closed string literal values in this object container, e.g. `{ from: "orders" }`. */ stringValues?: Record; + /** Property keys defined in this object container. */ + keys?: string[]; + /** Variables defined by an enclosing child `vars: { … }` or `let: { … }`. */ + letVars?: string[]; } interface MongoCallScan { @@ -778,6 +787,7 @@ interface MongoCursorClass { keyMap?: string; operator?: string; enumKey?: string; + variables?: string[]; } /** @@ -846,7 +856,13 @@ function scanMongoCallArguments(text: string, start: number, cursor: number): Mo } if (char === "}" || char === "]" || char === ")") { if (stack.length === 0) return null; - stack.pop(); + const popped = stack.pop(); + if (popped && popped.kind === "object" && (popped.key === "vars" || popped.key === "let")) { + const parent = stack[stack.length - 1]; + if (parent && parent.kind === "object") { + parent.letVars = [...(parent.letVars ?? []), ...(popped.keys ?? [])]; + } + } token = ""; valueKey = null; inValue = false; @@ -856,6 +872,16 @@ function scanMongoCallArguments(text: string, start: number, cursor: number): Mo valueKey = token.trim() || valueKey; token = ""; inValue = true; + if (valueKey) { + const inner = stack[stack.length - 1]; + if (inner && inner.kind === "object") { + const cleanKey = valueKey.replace(/^["']|["']$/g, ""); + inner.keys ??= []; + if (!inner.keys.includes(cleanKey)) { + inner.keys.push(cleanKey); + } + } + } continue; } if (char === ",") { @@ -871,6 +897,54 @@ function scanMongoCallArguments(text: string, start: number, cursor: number): Mo return { argIndex, stack, valueKey, inValue, inString: quote !== null }; } +function isExpressionArray(scan: MongoCallScan): boolean { + const inner = innermost(scan); + if (inner?.kind !== "array") return false; + if (inner.key?.startsWith("$")) return true; + for (let i = scan.stack.length - 1; i >= 0; i--) { + const container = scan.stack[i]; + if (container.key?.startsWith("$")) return true; + if (container.kind !== "array") break; + } + return false; +} + +function collectScopeVariables(scan: MongoCallScan): string[] { + const vars = new Set(); + + for (let i = scan.stack.length - 1; i >= 0; i--) { + const container = scan.stack[i]; + if (!container || container.kind !== "object") continue; + + const childKey = i === scan.stack.length - 1 ? scan.valueKey : scan.stack[i + 1]?.key; + + if (container.key === "$map") { + if (childKey === "in") { + vars.add(container.stringValues?.["as"] || "this"); + } + } else if (container.key === "$filter") { + if (childKey === "cond") { + vars.add(container.stringValues?.["as"] || "this"); + } + } else if (container.key === "$reduce") { + if (childKey === "in") { + vars.add("value"); + vars.add("this"); + } + } else if (container.key === "$let") { + if (childKey === "in" && container.letVars) { + for (const v of container.letVars) vars.add(v); + } + } else if (container.key === "$lookup") { + if (childKey === "pipeline" && container.letVars) { + for (const v of container.letVars) vars.add(v); + } + } + } + + return [...vars]; +} + function classifyCursorInCall(method: string, scan: MongoCallScan): MongoCursorClass { const role = METHOD_ARG_ROLES[method]?.[scan.argIndex]; if (!role) return { mode: "none" }; @@ -952,6 +1026,15 @@ function classifyFilter(scan: MongoCallScan, rootIndex: number): MongoCursorClas const schemaIndex = findContainerIndex(scan, rootIndex, "$jsonSchema"); if (schemaIndex >= 0) return classifyJsonSchema(scan, schemaIndex); + // Under `$expr` the vocabulary is aggregation expressions. + const exprIndex = findContainerIndex(scan, rootIndex, "$expr"); + if (exprIndex >= 0) { + if (isExpressionArray(scan)) return { mode: "fieldRef" }; + if (scan.inValue) return { mode: "fieldRef" }; + if (inner.kind === "object") return { mode: "expression" }; + return { mode: "none" }; + } + if (inner.kind === "array") { // `$type: ["string", "null"]` lists BSON types. if (inner.key === "$type") return { mode: "enumValue", enumKey: "$type" }; @@ -960,6 +1043,7 @@ function classifyFilter(scan: MongoCallScan, rootIndex: number): MongoCursorClas } if (inner.kind !== "object") return { mode: "none" }; if (scan.inValue) { + if (scan.valueKey === "$expr") return { mode: "fieldRef" }; if (scan.valueKey === "$size" || scan.valueKey === "$mod") return { mode: "none" }; const enumKey = filterValueEnum(inner.key, scan.valueKey); if (enumKey) return { mode: "enumValue", enumKey }; @@ -1331,6 +1415,7 @@ function classifyGroup(scan: MongoCallScan, bodyIndex: number): MongoCompletionM if (scan.inValue) return "fieldRef"; const inner = innermost(scan); + if (isExpressionArray(scan)) return "fieldRef"; if (inner?.kind !== "object") return "none"; // One level in: `_id: { … }` builds a compound key, anything else is an accumulator. if (depth === 1) return inner.key === "_id" ? "expression" : "accumulator"; @@ -1343,6 +1428,7 @@ function classifyProjection(scan: MongoCallScan, bodyIndex: number): MongoComple if (scan.inValue) return "fieldRef"; const inner = innermost(scan); + if (isExpressionArray(scan)) return "fieldRef"; if (inner?.kind !== "object") return "none"; return depth === 0 ? "field" : "expression"; } @@ -1397,6 +1483,7 @@ function classifyStageOptions(stage: string, scan: MongoCallScan, bodyIndex: num return { mode: "fieldRef", stage }; } if (scan.inValue) return { mode: "fieldRef", stage }; + if (isExpressionArray(scan)) return { mode: "fieldRef", stage }; return { mode: innermost(scan)?.kind === "object" ? "expression" : "none", stage }; } @@ -1430,6 +1517,7 @@ function classifyStageOptions(stage: string, scan: MongoCallScan, bodyIndex: num } if (scan.inValue) return { mode: "fieldRef", stage }; + if (isExpressionArray(scan)) return { mode: "fieldRef", stage }; return { mode: innermost(scan)?.kind === "object" ? "expression" : "none", stage }; } @@ -1646,6 +1734,52 @@ function fieldRefItems(prefix: string, fields: MongoCompletionField[], baseBoost ); } +const SYSTEM_VARIABLES: MongoOperatorSpec[] = [ + { label: "$$ROOT", detail: "Root document of the pipeline", apply: "$$ROOT" }, + { label: "$$CURRENT", detail: "Current document being processed", apply: "$$CURRENT" }, + { label: "$$NOW", detail: "Current date and time", apply: "$$NOW" }, + { label: "$$CLUSTER_TIME", detail: "Current cluster timestamp", apply: "$$CLUSTER_TIME" }, + { label: "$$REMOVE", detail: "Excludes a field from the document", apply: "$$REMOVE" }, + { label: "$$DESCEND", detail: "Descends to subdocuments in $redact", apply: "$$DESCEND" }, + { label: "$$PRUNE", detail: "Excludes all fields at current level in $redact", apply: "$$PRUNE" }, + { label: "$$KEEP", detail: "Includes all fields at current level in $redact", apply: "$$KEEP" }, +]; + +const REDACT_VARIABLES = new Set(["$$DESCEND", "$$PRUNE", "$$KEEP"]); + +function isVariablePrefix(prefix: string): boolean { + return normalizeMongoKeyPrefix(prefix).startsWith("$$"); +} + +function variableItems(prefix: string, userVariables: string[] = [], stage?: string): MongoCompletionItem[] { + const normalizedPrefix = normalizeMongoKeyPrefix(prefix); + + const userItems: MongoCompletionItem[] = userVariables + .map((name) => `$$${name}`) + .filter((label) => matchesFuzzyPrefix(label, normalizedPrefix)) + .map((label) => ({ + label, + type: "keyword" as const, + detail: "variable in scope", + apply: quoteMongoString(label, prefix), + boost: startsWithPrefix(label, normalizedPrefix) ? 140 : 110, + })); + + const systemItems: MongoCompletionItem[] = SYSTEM_VARIABLES.filter((v) => matchesFuzzyPrefix(v.label, normalizedPrefix)).map((v) => { + const isRedact = REDACT_VARIABLES.has(v.label); + const baseBoost = isRedact && stage !== "$redact" ? 60 : 100; + return { + label: v.label, + type: "keyword" as const, + detail: v.detail, + apply: quoteMongoString(v.label, prefix), + boost: startsWithPrefix(v.label, normalizedPrefix) ? baseBoost + 20 : baseBoost - 15, + }; + }); + + return dedupeAndSort([...userItems, ...systemItems]); +} + /** * Values from a fixed set, in or out of quotes: `$type: "` and `$type: ` both offer * `string`. Inside a quote the item supplies only the bare value and consumes the diff --git a/apps/desktop/src/lib/mongo/mongoCompletionTables.ts b/apps/desktop/src/lib/mongo/mongoCompletionTables.ts index 23e137fc35..49cd5f4df6 100644 --- a/apps/desktop/src/lib/mongo/mongoCompletionTables.ts +++ b/apps/desktop/src/lib/mongo/mongoCompletionTables.ts @@ -233,6 +233,12 @@ export const EXPRESSION_OPERATORS: MongoOperatorSpec[] = specs([ ["$multiply", "Multiplies numbers", "$multiply: [${}, ${}]"], ["$divide", "Divides two numbers", "$divide: [${}, ${}]"], ["$mod", "Returns the remainder of a division", "$mod: [${}, ${}]"], + ["$sum", "Sums values", "$sum: [${}, ${}]"], + ["$avg", "Averages values", "$avg: [${}, ${}]"], + ["$min", "Returns the lowest value", "$min: [${}, ${}]"], + ["$max", "Returns the highest value", "$max: [${}, ${}]"], + ["$stdDevPop", "Population standard deviation", "$stdDevPop: [${}, ${}]"], + ["$stdDevSamp", "Sample standard deviation", "$stdDevSamp: [${}, ${}]"], ["$abs", "Absolute value", "$abs: ${}"], ["$ceil", "Rounds up to the next integer", "$ceil: ${}"], ["$floor", "Rounds down to the previous integer", "$floor: ${}"], diff --git a/packages/app-tests/mongoCompletion.test.ts b/packages/app-tests/mongoCompletion.test.ts index b2d1f3da7c..f51b479c4a 100644 --- a/packages/app-tests/mongoCompletion.test.ts +++ b/packages/app-tests/mongoCompletion.test.ts @@ -542,6 +542,153 @@ test("suggests quoted field references in aggregation expression positions", () assert.equal(projection.find((item) => item.label === "$name")?.apply, '"$name"'); }); +test("suggests field references in elements of expression operator arrays across stages and $expr", () => { + // Elements of an expression operator's array argument get suggestions + // $project + const projectConcat = labels('db.users.aggregate([{ $project: { n: { $concat: ["$', { fields }); + assert.ok(projectConcat.includes("$name")); + assert.ok(projectConcat.includes("$profile.email")); + + // Bare element outside quotes offers field references (with quoted apply) + const projectAddBare = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $add: [", "db.users.aggregate([{ $project: { n: { $add: [".length, { fields }); + const nameItem = projectAddBare.find((item) => item.label === "$name"); + assert.equal(nameItem?.apply, '"$name"'); + + // Inside { within an array, offers expression operators + const projectAddObject = labels("db.users.aggregate([{ $project: { n: { $add: [ { $", { fields }); + assert.ok(projectAddObject.includes("$multiply")); + assert.ok(projectAddObject.includes("$sum")); + + // $expr in $match + const matchExpr = labels('db.users.aggregate([{ $match: { $expr: { $gt: ["$', { fields }); + assert.ok(matchExpr.includes("$name")); + assert.ok(matchExpr.includes("$profile.email")); + + // $expr in find() + const findExpr = labels('db.users.find({ $expr: { $eq: ["$', { fields }); + assert.ok(findExpr.includes("$name")); + assert.ok(findExpr.includes("$profile.email")); + + // $addFields + const addFieldsSum = labels("db.users.aggregate([{ $addFields: { n: { $sum: [", { fields }); + assert.ok(addFieldsSum.includes("$name")); + + // $set + const setMultiply = labels('db.users.aggregate([{ $set: { n: { $multiply: ["$', { fields }); + assert.ok(setMultiply.includes("$name")); + + // $group accumulators + const groupSum = labels('db.users.aggregate([{ $group: { _id: "$_id", total: { $sum: ["$', { fields }); + assert.ok(groupSum.includes("$name")); + const groupSumObject = labels('db.users.aggregate([{ $group: { _id: "$_id", total: { $sum: [ { $', { fields }); + assert.ok(groupSumObject.includes("$multiply")); + + // Update pipeline stages + const updatePipeline = labels('db.users.updateOne({}, [{ $set: { n: { $concat: ["$', { fields }); + assert.ok(updatePipeline.includes("$name")); + + // Plain filter $in / $nin / $all unchanged + const plainInQuoted = labels('db.users.find({ age: { $in: ["$', { fields }); + assert.equal(plainInQuoted.length, 0); + const plainInBare = labels("db.users.find({ age: { $in: [", { fields }); + assert.equal(plainInBare.includes("$name"), false); + assert.ok(plainInBare.includes("ObjectId")); +}); + +test("suggests accumulator operators as expressions in $project and other stages", () => { + const projectOps = labels("db.users.aggregate([{ $project: { n: { $ma"); + assert.ok(projectOps.includes("$max")); + + const maxItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $max", "db.users.aggregate([{ $project: { n: { $max".length).find((i) => i.label === "$max"); + assert.equal(maxItem?.apply, "$max: [${}, ${}]"); + + const sumItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $sum", "db.users.aggregate([{ $project: { n: { $sum".length).find((i) => i.label === "$sum"); + assert.equal(sumItem?.apply, "$sum: [${}, ${}]"); + + const avgItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $avg", "db.users.aggregate([{ $project: { n: { $avg".length).find((i) => i.label === "$avg"); + assert.equal(avgItem?.apply, "$avg: [${}, ${}]"); + + const minItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $min", "db.users.aggregate([{ $project: { n: { $min".length).find((i) => i.label === "$min"); + assert.equal(minItem?.apply, "$min: [${}, ${}]"); + + const stdDevPopItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $stdDevPop", "db.users.aggregate([{ $project: { n: { $stdDevPop".length).find((i) => i.label === "$stdDevPop"); + assert.equal(stdDevPopItem?.apply, "$stdDevPop: [${}, ${}]"); + + const stdDevSampItem = buildMongoCompletionItems("db.users.aggregate([{ $project: { n: { $stdDevSamp", "db.users.aggregate([{ $project: { n: { $stdDevSamp".length).find((i) => i.label === "$stdDevSamp"); + assert.equal(stdDevSampItem?.apply, "$stdDevSamp: [${}, ${}]"); +}); + +test("suggests system and scoped user variables when typing '$$'", () => { + // Single '$' offers fields, not variables + const singleDollar = labels('db.users.aggregate([{ $project: { n: "$', { fields }); + assert.ok(singleDollar.includes("$name")); + assert.equal(singleDollar.includes("$$ROOT"), false); + + // '$$' switches to variables + const varsInProject = labels('db.users.aggregate([{ $project: { n: "$$'); + assert.ok(varsInProject.includes("$$ROOT")); + assert.ok(varsInProject.includes("$$CURRENT")); + assert.ok(varsInProject.includes("$$NOW")); + assert.ok(varsInProject.includes("$$CLUSTER_TIME")); + assert.ok(varsInProject.includes("$$REMOVE")); + assert.ok(varsInProject.includes("$$DESCEND")); + assert.ok(varsInProject.includes("$$PRUNE")); + assert.ok(varsInProject.includes("$$KEEP")); + + // $redact ranks $$DESCEND / $$PRUNE / $$KEEP higher + const redactText = 'db.users.aggregate([{ $redact: { $cond: { if: 1, then: "$$'; + const projectText = 'db.users.aggregate([{ $project: { n: "$$'; + const redactVars = buildMongoCompletionItems(redactText, redactText.length); + const redactDescend = redactVars.find((i) => i.label === "$$DESCEND"); + const projectDescend = buildMongoCompletionItems(projectText, projectText.length).find((i) => i.label === "$$DESCEND"); + assert.ok((redactDescend?.boost ?? 0) > (projectDescend?.boost ?? 0)); + + // In expression array + const concatVars = labels('db.users.aggregate([{ $project: { n: { $concat: ["$$'); + assert.ok(concatVars.includes("$$ROOT")); + + // In find $expr + const findExprVars = labels('db.users.find({ $expr: { $eq: ["$$'); + assert.ok(findExprVars.includes("$$ROOT")); + + // $map scope: as: "item" offers $$item only inside in: + const mapIn = labels('db.users.aggregate([{ $project: { n: { $map: { input: "$arr", as: "item", in: "$$'); + assert.ok(mapIn.includes("$$item")); + assert.ok(mapIn.includes("$$ROOT")); + + const mapInNested = labels('db.users.aggregate([{ $project: { n: { $map: { input: "$arr", as: "item", in: { $concat: ["$$'); + assert.ok(mapInNested.includes("$$item")); + + const mapInput = labels('db.users.aggregate([{ $project: { n: { $map: { as: "item", input: "$$'); + assert.equal(mapInput.includes("$$item"), false); + + // $map without as defaults to $$this + const mapDefault = labels('db.users.aggregate([{ $project: { n: { $map: { input: "$arr", in: "$$'); + assert.ok(mapDefault.includes("$$this")); + + // $filter scope: as: "item" offers $$item inside cond, not input + const filterCond = labels('db.users.aggregate([{ $project: { n: { $filter: { input: "$arr", as: "item", cond: "$$'); + assert.ok(filterCond.includes("$$item")); + const filterInput = labels('db.users.aggregate([{ $project: { n: { $filter: { as: "item", input: "$$'); + assert.equal(filterInput.includes("$$item"), false); + + // $reduce scope: offers $$value and $$this inside in + const reduceIn = labels('db.users.aggregate([{ $project: { n: { $reduce: { input: "$arr", initialValue: 0, in: "$$'); + assert.ok(reduceIn.includes("$$value")); + assert.ok(reduceIn.includes("$$this")); + const reduceInit = labels('db.users.aggregate([{ $project: { n: { $reduce: { input: "$arr", in: "$$value", initialValue: "$$'); + assert.equal(reduceInit.includes("$$value"), false); + + // $let.vars scope + const letIn = labels('db.users.aggregate([{ $project: { n: { $let: { vars: { total: 10, discount: 2 }, in: "$$'); + assert.ok(letIn.includes("$$total")); + assert.ok(letIn.includes("$$discount")); + + // $lookup.let scope + const lookupLet = labels('db.users.aggregate([{ $lookup: { from: "orders", let: { order_id: "$_id" }, pipeline: [{ $project: { n: "$$'); + assert.ok(lookupLet.includes("$$order_id")); +}); + test("suggests $lookup option keys and collections for its from option", () => { assert.deepEqual(labels("db.users.aggregate([{ $lookup: { fr", { collections }), ["from"]);