flowquery 1.0.68 → 1.0.70

package/dist/parsing/parser.js

@@ -58,6 +58,7 @@ const key_value_pair_1 = __importDefault(require("./data_structures/key_value_pa
 const list_comprehension_1 = __importDefault(require("./data_structures/list_comprehension"));
 const lookup_1 = __importDefault(require("./data_structures/lookup"));
 const range_lookup_1 = __importDefault(require("./data_structures/range_lookup"));
+const binding_reference_1 = __importDefault(require("./expressions/binding_reference"));
 const expression_1 = __importDefault(require("./expressions/expression"));
 const f_string_1 = __importDefault(require("./expressions/f_string"));
 const identifier_1 = __importDefault(require("./expressions/identifier"));
@@ -80,14 +81,22 @@ const create_node_1 = __importDefault(require("./operations/create_node"));
 const create_relationship_1 = __importDefault(require("./operations/create_relationship"));
 const delete_node_1 = __importDefault(require("./operations/delete_node"));
 const delete_relationship_1 = __importDefault(require("./operations/delete_relationship"));
+const drop_binding_1 = __importDefault(require("./operations/drop_binding"));
+const let_1 = __importDefault(require("./operations/let"));
 const limit_1 = __importDefault(require("./operations/limit"));
 const load_1 = __importDefault(require("./operations/load"));
 const match_1 = __importDefault(require("./operations/match"));
+const merge_1 = __importStar(require("./operations/merge"));
 const order_by_1 = __importDefault(require("./operations/order_by"));
+const refresh_binding_1 = __importDefault(require("./operations/refresh_binding"));
+const refresh_node_1 = __importDefault(require("./operations/refresh_node"));
+const refresh_relationship_1 = __importDefault(require("./operations/refresh_relationship"));
 const return_1 = __importDefault(require("./operations/return"));
 const union_1 = __importDefault(require("./operations/union"));
 const union_all_1 = __importDefault(require("./operations/union_all"));
 const unwind_1 = __importDefault(require("./operations/unwind"));
+const update_1 = __importDefault(require("./operations/update"));
+const update_delete_1 = __importDefault(require("./operations/update_delete"));
 const where_1 = __importDefault(require("./operations/where"));
 const with_1 = __importDefault(require("./operations/with"));
 const parser_state_1 = __importDefault(require("./parser_state"));
@@ -175,7 +184,9 @@ class Parser extends base_parser_1.default {
         }
     }
     /**
-     * Validates that all operations in a statement are CREATE or DELETE.
+     * Validates that all operations in a statement are CREATE, DELETE,
+     * REFRESH, LET, or UPDATE — the declaration kinds that may precede the
+     * terminal statement in a multi-statement query.
      */
     validateIsCreateOrDelete(root) {
         let op = root.firstChild();
@@ -183,8 +194,16 @@ class Parser extends base_parser_1.default {
             if (!(op instanceof create_node_1.default) &&
                 !(op instanceof create_relationship_1.default) &&
                 !(op instanceof delete_node_1.default) &&
-                !(op instanceof delete_relationship_1.default)) {
-                throw new Error("Only CREATE and DELETE statements can appear before the last statement in a multi-statement query");
+                !(op instanceof delete_relationship_1.default) &&
+                !(op instanceof drop_binding_1.default) &&
+                !(op instanceof refresh_node_1.default) &&
+                !(op instanceof refresh_relationship_1.default) &&
+                !(op instanceof refresh_binding_1.default) &&
+                !(op instanceof let_1.default) &&
+                !(op instanceof update_1.default) &&
+                !(op instanceof update_delete_1.default) &&
+                !(op instanceof merge_1.default)) {
+                throw new Error("Only CREATE, DELETE, DROP, REFRESH, LET, UPDATE, and MERGE statements can appear before the last statement in a multi-statement query");
             }
             op = op.next;
         }
@@ -198,6 +217,9 @@ class Parser extends base_parser_1.default {
                 if (this.token.isSemicolon()) {
                     break;
                 }
+                if (isSubQuery && this.token.isClosingBrace()) {
+                    return root;
+                }
                 this.expectAndSkipWhitespaceAndComments();
             }
             else {
@@ -292,8 +314,16 @@ class Parser extends base_parser_1.default {
             !(operation instanceof create_node_1.default) &&
             !(operation instanceof create_relationship_1.default) &&
             !(operation instanceof delete_node_1.default) &&
-            !(operation instanceof delete_relationship_1.default)) {
-            throw new Error("Last statement must be a RETURN, WHERE, CALL, CREATE, or DELETE statement");
+            !(operation instanceof delete_relationship_1.default) &&
+            !(operation instanceof drop_binding_1.default) &&
+            !(operation instanceof refresh_node_1.default) &&
+            !(operation instanceof refresh_relationship_1.default) &&
+            !(operation instanceof refresh_binding_1.default) &&
+            !(operation instanceof let_1.default) &&
+            !(operation instanceof update_1.default) &&
+            !(operation instanceof update_delete_1.default) &&
+            !(operation instanceof merge_1.default)) {
+            throw new Error("Last statement must be a RETURN, WHERE, CALL, CREATE, DELETE, DROP, REFRESH, LET, UPDATE, or MERGE statement");
         }
         return root;
     }
@@ -305,6 +335,10 @@ class Parser extends base_parser_1.default {
             this.parseCall() ||
             this.parseCreate() ||
             this.parseDelete() ||
+            this.parseRefresh() ||
+            this.parseLet() ||
+            this.parseUpdate() ||
+            this.parseMerge() ||
             this.parseMatch());
     }
     parseWith() {
@@ -434,6 +468,15 @@ class Parser extends base_parser_1.default {
             if (expression === null) {
                 throw new Error("Expected expression or async function");
             }
+            // A bare unresolved identifier in `LOAD JSON FROM <name>` is
+            // treated as a reference to a LET-bound value, resolved at
+            // execution time against the global Bindings store.
+            const inner = expression.firstChild();
+            if (inner instanceof reference_1.default &&
+                inner.referred === undefined &&
+                !inner.identifier.startsWith("$")) {
+                expression.replaceChild(inner, new binding_reference_1.default(inner.identifier));
+            }
             from.addChild(expression);
         }
         this.expectAndSkipWhitespaceAndComments();
@@ -503,6 +546,12 @@ class Parser extends base_parser_1.default {
         }
         this.setNextToken();
         this.expectAndSkipWhitespaceAndComments();
+        let isStatic = false;
+        if (this.token.isStatic()) {
+            isStatic = true;
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+        }
         if (!this.token.isVirtual()) {
             throw new Error("Expected VIRTUAL");
         }
@@ -554,24 +603,91 @@ class Parser extends base_parser_1.default {
         if (query === null) {
             throw new Error("Expected sub-query");
         }
+        // Optional trailing REFRESH EVERY <n> <unit> clause.  Only allowed
+        // for STATIC virtual entities (caching must be enabled to refresh).
+        // We deliberately peek past REFRESH to confirm EVERY follows: a bare
+        // `REFRESH VIRTUAL ...` is a separate top-level statement.
+        let refreshEveryMs = null;
+        const savedIndex = this.tokenIndex;
+        this.skipWhitespaceAndComments();
+        let consumedRefreshClause = false;
+        if (this.token.isRefresh()) {
+            // Look ahead past whitespace for EVERY.
+            const afterRefreshIndex = this.tokenIndex;
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+            if (this.token.isEvery()) {
+                if (!isStatic) {
+                    throw new Error("REFRESH EVERY requires STATIC (caching must be enabled)");
+                }
+                this.setNextToken();
+                this.expectAndSkipWhitespaceAndComments();
+                if (!this.token.isNumber()) {
+                    throw new Error("Expected number after REFRESH EVERY");
+                }
+                const amount = Number(this.token.value);
+                if (!Number.isFinite(amount) || amount <= 0) {
+                    throw new Error("REFRESH EVERY interval must be a positive number");
+                }
+                this.setNextToken();
+                this.expectAndSkipWhitespaceAndComments();
+                const unit = (this.token.value || "").toUpperCase();
+                const unitMs = {
+                    SECOND: 1000,
+                    SECONDS: 1000,
+                    MINUTE: 60000,
+                    MINUTES: 60000,
+                    HOUR: 3600000,
+                    HOURS: 3600000,
+                    DAY: 86400000,
+                    DAYS: 86400000,
+                };
+                if (!(unit in unitMs)) {
+                    throw new Error("Expected time unit (SECOND[S], MINUTE[S], HOUR[S], DAY[S]) after REFRESH EVERY interval");
+                }
+                refreshEveryMs = amount * unitMs[unit];
+                this.setNextToken();
+                consumedRefreshClause = true;
+            }
+            else {
+                // Not REFRESH EVERY — must be the start of a separate
+                // REFRESH VIRTUAL statement.  Rewind to before REFRESH.
+                this.tokenIndex = afterRefreshIndex;
+            }
+        }
+        if (!consumedRefreshClause) {
+            // No REFRESH clause present; restore token position so the
+            // outer loop sees the original whitespace/next-clause boundary.
+            this.tokenIndex = savedIndex;
+        }
         let create;
         if (relationship !== null) {
-            create = new create_relationship_1.default(relationship, query);
+            create = new create_relationship_1.default(relationship, query, isStatic, refreshEveryMs);
         }
         else {
-            create = new create_node_1.default(node, query);
+            create = new create_node_1.default(node, query, isStatic, refreshEveryMs);
         }
         return create;
     }
     parseDelete() {
         var _a;
-        if (!this.token.isDelete()) {
+        if (!this.token.isDelete() && !this.token.isDrop()) {
             return null;
         }
         this.setNextToken();
         this.expectAndSkipWhitespaceAndComments();
+        if (this.token.isBinding()) {
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            if (!this.token.isIdentifierOrKeyword()) {
+                throw new Error("Expected binding name");
+            }
+            const name = this.token.value || "";
+            this.setNextToken();
+            return new drop_binding_1.default(name);
+        }
         if (!this.token.isVirtual()) {
-            throw new Error("Expected VIRTUAL");
+            throw new Error("Expected VIRTUAL or BINDING");
         }
         this.setNextToken();
         this.expectAndSkipWhitespaceAndComments();
@@ -618,6 +734,584 @@ class Parser extends base_parser_1.default {
         }
         return result;
     }
+    parseRefresh() {
+        var _a;
+        if (!this.token.isRefresh()) {
+            return null;
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (this.token.isBinding()) {
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            if (!this.token.isIdentifierOrKeyword()) {
+                throw new Error("Expected binding name");
+            }
+            const name = this.token.value || "";
+            this.setNextToken();
+            return new refresh_binding_1.default(name);
+        }
+        if (!this.token.isVirtual()) {
+            throw new Error("Expected VIRTUAL or BINDING");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        const node = this.parseNode();
+        if (node === null) {
+            throw new Error("Expected node definition");
+        }
+        let relationship = null;
+        if (this.token.isSubtract() && ((_a = this.peek()) === null || _a === void 0 ? void 0 : _a.isOpeningBracket())) {
+            this.setNextToken();
+            this.setNextToken();
+            if (!this.token.isColon()) {
+                throw new Error("Expected ':' for relationship type");
+            }
+            this.setNextToken();
+            if (!this.token.isIdentifierOrKeyword()) {
+                throw new Error("Expected relationship type identifier");
+            }
+            const type = this.token.value || "";
+            this.setNextToken();
+            if (!this.token.isClosingBracket()) {
+                throw new Error("Expected closing bracket for relationship definition");
+            }
+            this.setNextToken();
+            if (!this.token.isSubtract()) {
+                throw new Error("Expected '-' for relationship definition");
+            }
+            this.setNextToken();
+            const target = this.parseNode();
+            if (target === null) {
+                throw new Error("Expected target node definition");
+            }
+            relationship = new relationship_1.default();
+            relationship.type = type;
+            relationship.source = node;
+            relationship.target = target;
+        }
+        if (relationship !== null) {
+            return new refresh_relationship_1.default(relationship);
+        }
+        return new refresh_node_1.default(node);
+    }
+    /**
+     * Returns true when the current token is a clause keyword that
+     * starts a query pipeline (the right-hand side of a `LET name =`
+     * or `UPDATE name =`).  Used to disambiguate between binding a
+     * plain expression and binding the rows produced by a sub-query.
+     */
+    looksLikePipelineStart() {
+        return (this.token.isWith() ||
+            this.token.isUnwind() ||
+            this.token.isLoad() ||
+            this.token.isCall() ||
+            this.token.isMatch() ||
+            this.token.isOptional() ||
+            this.token.isReturn());
+    }
+    /**
+     * Peeks past `{` to decide whether the brace opens a sub-query
+     * (first significant token is a clause keyword) or a map literal
+     * (anything else, e.g. identifier+colon or string key).
+     */
+    braceOpensSubQuery() {
+        if (!this.token.isOpeningBrace()) {
+            return false;
+        }
+        const savedIndex = this.tokenIndex;
+        this.setNextToken();
+        this.skipWhitespaceAndComments();
+        const result = this.token.isWith() ||
+            this.token.isUnwind() ||
+            this.token.isLoad() ||
+            this.token.isCall() ||
+            this.token.isMatch() ||
+            this.token.isOptional() ||
+            this.token.isReturn();
+        this.tokenIndex = savedIndex;
+        return result;
+    }
+    /**
+     * Parses the right-hand side of a `LET` / `UPDATE`.  Returns the
+     * expression *or* the sub-query AST that was parsed.
+     */
+    parseLetUpdateRhs() {
+        this.expectAndSkipWhitespaceAndComments();
+        // Explicit braces wrap a sub-query only when followed by a
+        // clause keyword; otherwise `{ ... }` is a map literal.
+        if (this.braceOpensSubQuery()) {
+            const subQuery = this.parseSubQuery();
+            if (subQuery === null) {
+                throw new Error("Expected sub-query");
+            }
+            return { expression: null, subQuery };
+        }
+        if (this.looksLikePipelineStart()) {
+            // Inline sub-query: parse a pipeline up to ; / EOF.
+            const savedState = this._state;
+            this._state = new parser_state_1.default();
+            const subQuery = this._parseTokenized(true);
+            this._state = savedState;
+            if (subQuery.firstChild() === null) {
+                throw new Error("Expected expression or sub-query");
+            }
+            return { expression: null, subQuery };
+        }
+        const expression = this.parseExpression();
+        if (expression === null) {
+            throw new Error("Expected expression or sub-query");
+        }
+        return { expression, subQuery: null };
+    }
+    parseLet() {
+        if (!this.token.isLet()) {
+            return null;
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+            throw new Error("Expected identifier after LET");
+        }
+        const name = this.token.value;
+        this.setNextToken();
+        this.skipWhitespaceAndComments();
+        if (!this.token.isEquals()) {
+            throw new Error("Expected '=' after LET identifier");
+        }
+        this.setNextToken();
+        const { expression, subQuery } = this.parseLetUpdateRhs();
+        // Optional trailing REFRESH EVERY <n> <unit> clause turns the
+        // binding into a refreshable one.  Requires a sub-query RHS
+        // (there is nothing to re-evaluate for a literal expression).
+        // Peek past REFRESH to confirm EVERY follows: a bare
+        // `REFRESH BINDING` is a separate top-level statement.
+        let refreshEveryMs = null;
+        const savedIndex = this.tokenIndex;
+        this.skipWhitespaceAndComments();
+        let consumedRefreshClause = false;
+        if (this.token.isRefresh()) {
+            const afterRefreshIndex = this.tokenIndex;
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+            if (this.token.isEvery()) {
+                if (subQuery === null) {
+                    throw new Error("LET REFRESH EVERY requires a sub-query right-hand side");
+                }
+                this.setNextToken();
+                this.expectAndSkipWhitespaceAndComments();
+                if (!this.token.isNumber()) {
+                    throw new Error("Expected number after REFRESH EVERY");
+                }
+                const amount = Number(this.token.value);
+                if (!Number.isFinite(amount) || amount <= 0) {
+                    throw new Error("REFRESH EVERY interval must be a positive number");
+                }
+                this.setNextToken();
+                this.expectAndSkipWhitespaceAndComments();
+                const unit = (this.token.value || "").toUpperCase();
+                const unitMs = {
+                    SECOND: 1000,
+                    SECONDS: 1000,
+                    MINUTE: 60000,
+                    MINUTES: 60000,
+                    HOUR: 3600000,
+                    HOURS: 3600000,
+                    DAY: 86400000,
+                    DAYS: 86400000,
+                };
+                if (!(unit in unitMs)) {
+                    throw new Error("Expected time unit (SECOND[S], MINUTE[S], HOUR[S], DAY[S]) after REFRESH EVERY interval");
+                }
+                refreshEveryMs = amount * unitMs[unit];
+                this.setNextToken();
+                consumedRefreshClause = true;
+            }
+            else {
+                // Not REFRESH EVERY; must be the start of a separate
+                // REFRESH statement.  Rewind to before REFRESH.
+                this.tokenIndex = afterRefreshIndex;
+            }
+        }
+        if (!consumedRefreshClause) {
+            this.tokenIndex = savedIndex;
+        }
+        return new let_1.default(name, expression, subQuery, refreshEveryMs);
+    }
+    parseUpdate() {
+        if (!this.token.isUpdate()) {
+            return null;
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+            throw new Error("Expected identifier after UPDATE");
+        }
+        const name = this.token.value;
+        this.setNextToken();
+        this.skipWhitespaceAndComments();
+        // `UPDATE name AS alias DELETE WHERE <pred>` — row-filtering branch.
+        if (this.token.isAs()) {
+            return this.parseUpdateDeleteTail(name);
+        }
+        // `UPDATE name = <rhs>` — assign branch.
+        if (!this.token.isEquals()) {
+            throw new Error("Expected '=' in UPDATE");
+        }
+        this.setNextToken();
+        const { expression, subQuery } = this.parseLetUpdateRhs();
+        return new update_1.default(name, expression, subQuery);
+    }
+    /**
+     * Parses a `MERGE INTO <name> [AS <target>] USING <rhs>
+     * [AS <source>] ON <on-clause> <when-clauses>` statement.
+     */
+    parseMerge() {
+        if (!this.token.isMerge()) {
+            return null;
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isInto()) {
+            throw new Error("Expected INTO after MERGE");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+            throw new Error("Expected binding name after MERGE INTO");
+        }
+        const name = this.token.value;
+        this.setNextToken();
+        this.skipWhitespaceAndComments();
+        // Optional `AS <target-alias>`.
+        let targetAlias = null;
+        if (this.token.isAs()) {
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+                throw new Error("Expected alias after AS in MERGE INTO");
+            }
+            targetAlias = this.token.value;
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+        }
+        if (!this.token.isUsing()) {
+            throw new Error("Expected USING after MERGE INTO target");
+        }
+        this.setNextToken();
+        const { expression: sourceExpression, subQuery: sourceSubQuery } = this.parseLetUpdateRhs();
+        if (sourceExpression !== null) {
+            // The source RHS lives outside the LET / UPDATE binding-RHS
+            // scope, so a bare identifier here refers to an existing
+            // binding (e.g. `USING incoming AS s`) rather than a
+            // declaration-site name.  Convert unresolved references so
+            // they resolve against the global Bindings store at runtime.
+            this.convertUnresolvedReferencesToBindings(sourceExpression);
+        }
+        this.skipWhitespaceAndComments();
+        // Optional `AS <source-alias>`.
+        let sourceAlias = null;
+        if (this.token.isAs()) {
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+                throw new Error("Expected alias after AS in MERGE INTO … USING");
+            }
+            sourceAlias = this.token.value;
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+        }
+        if (!this.token.isOn()) {
+            throw new Error("Expected ON in MERGE INTO");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        // Pre-create the Merge with placeholders so that aliases can
+        // resolve to the per-row context while we parse the ON clause
+        // and the WHEN expressions.  The proxy aliases delegate to
+        // `targetValue()` / `sourceValue()` on this instance.
+        const placeholderOn = { type: "keys", keys: [] };
+        const merge = new merge_1.default(name, targetAlias, sourceAlias, sourceExpression, sourceSubQuery, placeholderOn, null, null);
+        if (targetAlias !== null) {
+            this._state.variables.set(targetAlias, new merge_1.MergeTargetAlias(merge));
+        }
+        if (sourceAlias !== null) {
+            this._state.variables.set(sourceAlias, new merge_1.MergeSourceAlias(merge));
+        }
+        let onClause;
+        try {
+            onClause = this.parseMergeOn();
+            this.skipWhitespaceAndComments();
+            // Build the matched / not-matched actions from one or more
+            // WHEN clauses.  Track whether we've already seen each kind
+            // to forbid duplicates.
+            let matched = null;
+            let notMatched = null;
+            while (this.token.isWhen()) {
+                const parsed = this.parseMergeWhenClause();
+                if (parsed.kind === "matched") {
+                    if (matched !== null) {
+                        throw new Error("Duplicate WHEN MATCHED clause in MERGE INTO");
+                    }
+                    matched = parsed.action;
+                }
+                else {
+                    if (notMatched !== null) {
+                        throw new Error("Duplicate WHEN NOT MATCHED clause in MERGE INTO");
+                    }
+                    notMatched = parsed.action;
+                }
+                this.skipWhitespaceAndComments();
+            }
+            if (matched === null && notMatched === null) {
+                throw new Error("MERGE INTO requires at least one WHEN clause");
+            }
+            merge.setClauses(onClause, matched, notMatched);
+        }
+        finally {
+            if (targetAlias !== null) {
+                this._state.variables.delete(targetAlias);
+            }
+            if (sourceAlias !== null) {
+                this._state.variables.delete(sourceAlias);
+            }
+        }
+        return merge;
+    }
+    /**
+     * Parses the body of the `ON` clause.  Distinguishes a short-form
+     * key list (`ON id`, `ON (a, b, c)`) from a full predicate
+     * expression by looking ahead: a bare identifier (or parenthesised
+     * list of identifiers) followed by `WHEN` is the key form;
+     * anything else is parsed as an expression.
+     */
+    parseMergeOn() {
+        // Snapshot tokenizer position so we can rewind after a failed
+        // key-list probe.
+        const savedIndex = this.tokenIndex;
+        const keys = this.tryParseMergeKeyList();
+        if (keys !== null) {
+            return { type: "keys", keys };
+        }
+        // Not a key list — rewind and parse as a predicate expression.
+        this.tokenIndex = savedIndex;
+        const predicate = this.parseExpression();
+        if (predicate === null) {
+            throw new Error("Expected predicate or key list after MERGE INTO … ON");
+        }
+        this.convertUnresolvedReferencesToBindings(predicate);
+        return { type: "predicate", predicate };
+    }
+    /**
+     * Speculatively parses `<id>` or `(<id> [, <id>]*)` followed by
+     * `WHEN`.  Returns the key list on success, or `null` if the
+     * lookahead doesn't match (leaving the caller to rewind and try
+     * an expression).
+     */
+    tryParseMergeKeyList() {
+        const keys = [];
+        if (this.token.isLeftParenthesis()) {
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+            while (!this.token.isRightParenthesis()) {
+                if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+                    return null;
+                }
+                keys.push(this.token.value);
+                this.setNextToken();
+                this.skipWhitespaceAndComments();
+                if (this.token.isComma()) {
+                    this.setNextToken();
+                    this.skipWhitespaceAndComments();
+                }
+                else if (!this.token.isRightParenthesis()) {
+                    return null;
+                }
+            }
+            this.setNextToken();
+        }
+        else {
+            if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+                return null;
+            }
+            keys.push(this.token.value);
+            this.setNextToken();
+        }
+        // Must be followed by `WHEN` (with any whitespace) to be a key list.
+        this.skipWhitespaceAndComments();
+        if (!this.token.isWhen()) {
+            return null;
+        }
+        if (keys.length === 0) {
+            return null;
+        }
+        return keys;
+    }
+    /**
+     * Parses a single `WHEN [NOT] MATCHED THEN UPDATE SET … | DELETE
+     * | INSERT [<expr>]` clause.  Caller is positioned on `WHEN`.
+     */
+    parseMergeWhenClause() {
+        this.setNextToken(); // consume WHEN
+        this.expectAndSkipWhitespaceAndComments();
+        let negated = false;
+        if (this.token.isNot()) {
+            negated = true;
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+        }
+        if (!this.token.isMatched()) {
+            throw new Error("Expected MATCHED after WHEN" + (negated ? " NOT" : ""));
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isThen()) {
+            throw new Error("Expected THEN after WHEN" + (negated ? " NOT" : "") + " MATCHED");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (negated) {
+            // WHEN NOT MATCHED — only INSERT is meaningful.
+            if (!this.token.isInsert()) {
+                throw new Error("Expected INSERT after WHEN NOT MATCHED THEN");
+            }
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+            // Optional expression: anything that isn't a WHEN / EOF /
+            // semicolon / closing brace is the row-builder expression.
+            let expression = null;
+            if (!this.token.isWhen() &&
+                !this.token.isEOF() &&
+                !this.token.isSemicolon() &&
+                !this.token.isClosingBrace()) {
+                expression = this.parseExpression();
+                if (expression === null) {
+                    throw new Error("Expected expression after WHEN NOT MATCHED THEN INSERT");
+                }
+                this.convertUnresolvedReferencesToBindings(expression);
+            }
+            return { kind: "notMatched", action: { type: "insert", expression } };
+        }
+        // WHEN MATCHED — accepts UPDATE SET … or DELETE.
+        if (this.token.isUpdate()) {
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            if (!this.token.isSet()) {
+                throw new Error("Expected SET after WHEN MATCHED THEN UPDATE");
+            }
+            this.setNextToken();
+            this.expectAndSkipWhitespaceAndComments();
+            const setItems = this.parseMergeSetList();
+            return { kind: "matched", action: { type: "update", setItems } };
+        }
+        if (this.token.isDelete()) {
+            this.setNextToken();
+            return { kind: "matched", action: { type: "delete" } };
+        }
+        throw new Error("Expected UPDATE or DELETE after WHEN MATCHED THEN");
+    }
+    /**
+     * Parses `.field [= <expr>] [, .field [= <expr>]]*` — the body of a
+     * `WHEN MATCHED THEN UPDATE SET` clause.  An item without an
+     * explicit `= <expr>` defaults to `source.<field>` at run time.
+     */
+    parseMergeSetList() {
+        const items = [];
+        while (true) {
+            if (!this.token.isDot()) {
+                throw new Error("Expected '.' before SET field name");
+            }
+            this.setNextToken();
+            if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+                throw new Error("Expected field name after '.'");
+            }
+            const field = this.token.value;
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+            let expression = null;
+            if (this.token.isEquals()) {
+                this.setNextToken();
+                this.expectAndSkipWhitespaceAndComments();
+                expression = this.parseExpression();
+                if (expression === null) {
+                    throw new Error(`Expected expression after SET .${field} =`);
+                }
+                this.convertUnresolvedReferencesToBindings(expression);
+                this.skipWhitespaceAndComments();
+            }
+            items.push({ field, expression });
+            if (!this.token.isComma()) {
+                break;
+            }
+            this.setNextToken();
+            this.skipWhitespaceAndComments();
+        }
+        if (items.length === 0) {
+            throw new Error("Expected at least one SET field");
+        }
+        return items;
+    }
+    /**
+     * Parses the tail of `UPDATE name AS alias DELETE WHERE <pred>`,
+     * with `AS` already consumed by the caller's lookahead.
+     */
+    parseUpdateDeleteTail(name) {
+        this.setNextToken(); // consume AS
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isIdentifierOrKeyword() || this.token.value === null) {
+            throw new Error("Expected alias after AS");
+        }
+        const alias = this.token.value;
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isDelete()) {
+            throw new Error("Expected DELETE after UPDATE alias");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        if (!this.token.isWhere()) {
+            throw new Error("Expected WHERE after UPDATE … DELETE");
+        }
+        this.setNextToken();
+        this.expectAndSkipWhitespaceAndComments();
+        // Inject the alias into the parser's variable scope while we
+        // parse the predicate so that `<alias>` / `<alias>.field`
+        // references resolve to the UpdateDelete's per-row value.
+        const updateDelete = new update_delete_1.default(name, alias, new expression_1.default());
+        this._state.variables.set(alias, updateDelete);
+        const predicate = this.parseExpression();
+        this._state.variables.delete(alias);
+        if (predicate === null) {
+            throw new Error("Expected predicate expression after WHERE");
+        }
+        // Any other unresolved bare identifiers (e.g. `IN banned`) refer
+        // to LET-bound bindings, which are resolved at run-time against
+        // the global Bindings store.
+        this.convertUnresolvedReferencesToBindings(predicate);
+        updateDelete.setPredicate(predicate);
+        return updateDelete;
+    }
+    /**
+     * Recursively replaces any unresolved {@link Reference} node in
+     * the given subtree with a {@link BindingReference}, which looks up
+     * the value from the global {@link Bindings} store at run-time.
+     *
+     * Used by `UPDATE … AS u DELETE WHERE …` so that predicates can
+     * reference other bindings by name, and to keep `LOAD JSON FROM …`
+     * behaviour consistent at arbitrary depth.
+     */
+    convertUnresolvedReferencesToBindings(node) {
+        for (const child of node.getChildren().slice()) {
+            if (child instanceof reference_1.default &&
+                child.referred === undefined &&
+                !child.identifier.startsWith("$")) {
+                node.replaceChild(child, new binding_reference_1.default(child.identifier));
+            }
+            else {
+                this.convertUnresolvedReferencesToBindings(child);
+            }
+        }
+    }
     parseMatch() {
         let optional = false;
         if (this.token.isOptional()) {
@@ -956,7 +1650,7 @@ class Parser extends base_parser_1.default {
             return null;
         }
         this.setNextToken();
-        this.expectAndSkipWhitespaceAndComments();
+        this.skipWhitespaceAndComments();
         const query = this._parseTokenized(true);
         this.skipWhitespaceAndComments();
         if (!this.token.isClosingBrace()) {