@quereus/quereus 0.1.0

package/dist/src/parser/parser.js

@@ -0,0 +1,2619 @@
+import { createLogger } from '../common/logger.js'; // Import logger
+import { Lexer, TokenType } from './lexer.js';
+import { ConflictResolution } from '../common/constants.js';
+import { quereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import { getSyncLiteral } from './utils.js';
+const log = createLogger('parser:parser'); // Create logger instance
+const errorLog = log.extend('error');
+export class ParseError extends Error {
+    token;
+    constructor(token, message) {
+        super(message);
+        this.token = token;
+        this.name = 'ParseError';
+    }
+}
+// Helper function to create the location object
+function _createLoc(startToken, endToken) {
+    return {
+        start: {
+            line: startToken.startLine,
+            column: startToken.startColumn,
+            offset: startToken.startOffset,
+        },
+        end: {
+            line: endToken.endLine,
+            column: endToken.endColumn,
+            offset: endToken.endOffset,
+        },
+    };
+}
+export class Parser {
+    tokens = [];
+    current = 0;
+    // Counter for positional parameters
+    parameterPosition = 1;
+    /**
+     * Initialize the parser with tokens from a SQL string
+     * @param sql SQL string to parse
+     * @returns this parser instance for chaining
+     */
+    initialize(sql) {
+        const lexer = new Lexer(sql);
+        this.tokens = lexer.scanTokens();
+        this.current = 0;
+        this.parameterPosition = 1; // Reset parameter counter
+        // Check for errors from lexer
+        const errorToken = this.tokens.find(t => t.type === TokenType.ERROR);
+        if (errorToken) {
+            quereusError(`Lexer error: ${errorToken.lexeme}`, StatusCode.ERROR, undefined, {
+                loc: {
+                    start: {
+                        line: errorToken.startLine,
+                        column: errorToken.startColumn,
+                    },
+                    end: {
+                        line: errorToken.endLine,
+                        column: errorToken.endColumn,
+                    }
+                }
+            });
+        }
+        return this;
+    }
+    /**
+     * Parse SQL text into an array of ASTs
+     */
+    parseAll(sql) {
+        this.initialize(sql);
+        const statements = [];
+        while (!this.isAtEnd()) {
+            try {
+                const stmt = this.statement();
+                statements.push(stmt); // Cast needed as statement() returns AstNode
+                // Consume optional semicolon at the end of the statement
+                this.match(TokenType.SEMICOLON);
+            }
+            catch (e) {
+                // error() method now throws QuereusError directly with location info
+                if (e instanceof Error && e.name === 'QuereusError') {
+                    throw e;
+                }
+                // Handle unexpected non-QuereusError exceptions
+                errorLog("Unhandled parser error: %O", e);
+                quereusError(`Parser error: ${e instanceof Error ? e.message : e}`, StatusCode.ERROR, e instanceof Error ? e : undefined);
+            }
+        }
+        // If we consumed all tokens and didn't parse any statements (e.g., empty input or only comments/whitespace),
+        // return an empty array instead of throwing an error.
+        return statements;
+    }
+    /**
+     * Parse SQL text into a single AST node.
+     * Use parseAll instead for potentially multi-statement strings.
+     * Throws error if more than one statement is found after the first.
+     */
+    parse(sql) {
+        const statements = this.parseAll(sql);
+        if (statements.length === 0) {
+            // Handle case of empty input or input with only comments/whitespace
+            // Depending on desired behavior, could return null, undefined, or throw.
+            // Throwing seems reasonable as prepare/eval expect a statement.
+            quereusError("No SQL statement found to parse.", StatusCode.ERROR);
+        }
+        if (statements.length > 1) {
+            // Find the token that starts the second statement for better error location
+            const secondStatementStartToken = statements[1]?.loc?.start;
+            const errToken = this.tokens.find(t => t.startOffset === secondStatementStartToken?.offset) ?? this.peek();
+            this.error(errToken, "Provided SQL string contains multiple statements. Use exec() for multi-statement execution.");
+        }
+        return statements[0];
+    }
+    /**
+     * Attempts to parse a WITH clause if present.
+     * @returns The WithClause AST node or undefined if no WITH clause is found.
+     */
+    tryParseWithClause() {
+        if (!this.check(TokenType.WITH)) {
+            return undefined;
+        }
+        const startToken = this.advance(); // Consume WITH
+        const recursive = this.match(TokenType.RECURSIVE);
+        const ctes = [];
+        do {
+            ctes.push(this.commonTableExpression());
+        } while (this.match(TokenType.COMMA));
+        // Parse optional OPTION clause
+        let options;
+        if (this.matchKeyword('OPTION')) {
+            this.consume(TokenType.LPAREN, "Expected '(' after OPTION.");
+            // Parse MAXRECURSION option
+            if (this.matchKeyword('MAXRECURSION')) {
+                if (!this.check(TokenType.INTEGER)) {
+                    this.error(this.peek(), "Expected integer value after MAXRECURSION.");
+                }
+                const maxRecursionToken = this.advance();
+                const maxRecursion = maxRecursionToken.literal;
+                if (maxRecursion < 0) {
+                    this.error(maxRecursionToken, "MAXRECURSION value must be non-negative.");
+                }
+                options = { maxRecursion };
+            }
+            else {
+                throw this.error(this.peek(), "Expected MAXRECURSION in OPTION clause.");
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after OPTION clause.");
+        }
+        const endToken = this.previous(); // Last token of the WITH clause
+        return { type: 'with', recursive, ctes, options, loc: _createLoc(startToken, endToken) };
+    }
+    /**
+     * Parses a single Common Table Expression (CTE).
+     * cte_name [(col1, col2, ...)] AS (query)
+     */
+    commonTableExpression() {
+        const startToken = this.peek(); // Peek before consuming name
+        const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'like'], "Expected CTE name.");
+        let endToken = this.previous(); // End token initially is the name
+        let columns;
+        if (this.match(TokenType.LPAREN)) {
+            columns = [];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'like'], "Expected column name in CTE definition."));
+                } while (this.match(TokenType.COMMA));
+            }
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after CTE column list.");
+        }
+        this.consume(TokenType.AS, "Expected 'AS' after CTE name.");
+        let materializationHint;
+        if (this.matchKeyword('MATERIALIZED')) {
+            materializationHint = 'materialized';
+        }
+        else if (this.matchKeyword('NOT')) {
+            this.consumeKeyword('MATERIALIZED', "Expected 'MATERIALIZED' after 'NOT'.");
+            materializationHint = 'not_materialized';
+        }
+        this.consume(TokenType.LPAREN, "Expected '(' before CTE query.");
+        // Parse the CTE query (can be SELECT, VALUES (via SELECT), INSERT, UPDATE, DELETE)
+        const queryStartToken = this.peek();
+        let query;
+        if (this.check(TokenType.SELECT)) {
+            this.advance(); // Consume SELECT token
+            query = this.selectStatement(queryStartToken); // Pass start token
+        }
+        else if (this.check(TokenType.INSERT)) {
+            this.advance(); // Consume INSERT token
+            query = this.insertStatement(queryStartToken);
+        }
+        else if (this.check(TokenType.UPDATE)) {
+            this.advance(); // Consume UPDATE token
+            query = this.updateStatement(queryStartToken);
+        }
+        else if (this.check(TokenType.DELETE)) {
+            this.advance(); // Consume DELETE token
+            query = this.deleteStatement(queryStartToken);
+        }
+        // TODO: Add support for VALUES directly if needed (though VALUES is usually part of SELECT)
+        else {
+            throw this.error(this.peek(), "Expected SELECT, INSERT, UPDATE, or DELETE statement for CTE query.");
+        }
+        endToken = this.consume(TokenType.RPAREN, "Expected ')' after CTE query."); // Capture ')' as end token
+        return { type: 'commonTableExpr', name, columns, query, materializationHint, loc: _createLoc(startToken, endToken) };
+    }
+    /**
+     * Parse a single SQL statement
+     */
+    statement() {
+        // Check for WITH clause first
+        let withClause;
+        if (this.check(TokenType.WITH)) {
+            withClause = this.tryParseWithClause();
+        }
+        const startToken = this.peek();
+        // --- Check for specific keywords first ---
+        const currentKeyword = startToken.lexeme.toUpperCase();
+        let stmt;
+        switch (currentKeyword) {
+            case 'SELECT':
+                this.advance();
+                stmt = this.selectStatement(startToken, withClause);
+                break;
+            case 'INSERT':
+                this.advance();
+                stmt = this.insertStatement(startToken, withClause);
+                break;
+            case 'UPDATE':
+                this.advance();
+                stmt = this.updateStatement(startToken, withClause);
+                break;
+            case 'DELETE':
+                this.advance();
+                stmt = this.deleteStatement(startToken, withClause);
+                break;
+            case 'VALUES':
+                this.advance();
+                stmt = this.valuesStatement(startToken);
+                break;
+            case 'CREATE':
+                this.advance();
+                stmt = this.createStatement(startToken, withClause);
+                break;
+            case 'DROP':
+                this.advance();
+                stmt = this.dropStatement(startToken, withClause);
+                break;
+            case 'ALTER':
+                this.advance();
+                stmt = this.alterTableStatement(startToken, withClause);
+                break;
+            case 'BEGIN':
+                this.advance();
+                stmt = this.beginStatement(startToken, withClause);
+                break;
+            case 'COMMIT':
+                this.advance();
+                stmt = this.commitStatement(startToken, withClause);
+                break;
+            case 'ROLLBACK':
+                this.advance();
+                stmt = this.rollbackStatement(startToken, withClause);
+                break;
+            case 'SAVEPOINT':
+                this.advance();
+                stmt = this.savepointStatement(startToken, withClause);
+                break;
+            case 'RELEASE':
+                this.advance();
+                stmt = this.releaseStatement(startToken, withClause);
+                break;
+            // TODO: Replace pragmas with build-in functions
+            case 'PRAGMA':
+                this.advance();
+                stmt = this.pragmaStatement(startToken, withClause);
+                break;
+            // --- Add default case ---
+            default:
+                // If it wasn't a recognized keyword starting the statement
+                throw this.error(startToken, `Expected statement type (SELECT, INSERT, UPDATE, DELETE, VALUES, CREATE, etc.), got '${startToken.lexeme}'.`);
+        }
+        // Attach WITH clause if present and supported
+        if (withClause && this.statementSupportsWithClause(stmt)) {
+            stmt.withClause = withClause;
+            if (withClause.loc && stmt.loc) {
+                stmt.loc.start = withClause.loc.start;
+            }
+        }
+        else if (withClause) {
+            throw this.error(this.previous(), `WITH clause cannot be used with ${stmt.type} statement.`);
+        }
+        return stmt;
+    }
+    /**
+     * Parse an INSERT statement
+     * @returns AST for the INSERT statement
+     */
+    insertStatement(startToken, withClause) {
+        // INTO keyword is optional in SQLite
+        this.matchKeyword('INTO'); // Handle missing keyword gracefully
+        // Parse the table reference
+        const table = this.tableIdentifier();
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        // Parse column list if provided
+        let columns;
+        if (this.match(TokenType.LPAREN)) {
+            columns = [];
+            do {
+                if (!this.checkIdentifierLike(contextualKeywords)) {
+                    throw this.error(this.peek(), "Expected column name.");
+                }
+                columns.push(this.advance().lexeme);
+            } while (this.match(TokenType.COMMA));
+            this.consume(TokenType.RPAREN, "Expected ')' after column list.");
+        }
+        // Parse VALUES clause
+        let values;
+        let select;
+        let lastConsumedToken = this.previous(); // After columns or table id
+        if (this.match(TokenType.VALUES)) {
+            values = [];
+            do {
+                this.consume(TokenType.LPAREN, "Expected '(' before values.");
+                const valueList = [];
+                if (!this.check(TokenType.RPAREN)) { // Check for empty value list
+                    do {
+                        valueList.push(this.expression());
+                    } while (this.match(TokenType.COMMA));
+                }
+                this.consume(TokenType.RPAREN, "Expected ')' after values.");
+                values.push(valueList);
+                lastConsumedToken = this.previous(); // Update after closing paren of value list
+            } while (this.match(TokenType.COMMA));
+        }
+        else if (this.check(TokenType.SELECT)) { // If current token is SELECT
+            // Handle INSERT ... SELECT
+            // Consume the SELECT token, as selectStatement expects to start parsing after it.
+            // selectKeywordToken will be the actual 'SELECT' token object, used for location.
+            const selectKeywordToken = this.advance(); // Consume 'SELECT'
+            // Pass the withClause so the embedded SELECT can (via the planner) resolve CTEs defined for the INSERT.
+            select = this.selectStatement(selectKeywordToken, withClause);
+            lastConsumedToken = this.previous(); // After SELECT statement is parsed
+        }
+        else {
+            throw this.error(this.peek(), "Expected VALUES or SELECT after INSERT.");
+        }
+        // Parse RETURNING clause if present
+        let returning;
+        if (this.matchKeyword('RETURNING')) {
+            returning = this.columnList();
+            lastConsumedToken = this.previous(); // Update after RETURNING clause
+        }
+        return {
+            type: 'insert',
+            table,
+            columns,
+            values,
+            select,
+            returning,
+            loc: _createLoc(startToken, lastConsumedToken),
+        };
+    }
+    /**
+     * Parse a SELECT statement
+     * @param startToken The 'SELECT' token or start token of a sub-query
+     * @param withClause The WITH clause context for CTE access
+     * @param isCompoundSubquery If true, don't parse ORDER BY/LIMIT as they belong to the outer compound
+     * @returns AST for the SELECT statement
+     */
+    selectStatement(startToken, withClause, isCompoundSubquery = false) {
+        const start = startToken ?? this.previous(); // Use provided or the keyword token
+        let lastConsumedToken = start; // Initialize lastConsumed
+        const distinct = this.matchKeyword('DISTINCT');
+        if (distinct)
+            lastConsumedToken = this.previous();
+        const all = !distinct && this.matchKeyword('ALL');
+        if (all)
+            lastConsumedToken = this.previous();
+        // Parse column list
+        const columns = this.columnList();
+        if (columns.length > 0)
+            lastConsumedToken = this.previous(); // Update after last column element
+        // Parse FROM clause if present
+        let from;
+        if (this.match(TokenType.FROM)) {
+            from = this.tableSourceList(withClause);
+            if (from.length > 0)
+                lastConsumedToken = this.previous(); // After last source/join
+        }
+        // Parse WHERE clause if present
+        let where;
+        if (this.match(TokenType.WHERE)) {
+            where = this.expression();
+            lastConsumedToken = this.previous(); // After where expression
+        }
+        // Parse GROUP BY clause if present
+        let groupBy;
+        if (this.match(TokenType.GROUP) && this.consume(TokenType.BY, "Expected 'BY' after 'GROUP'.")) {
+            groupBy = [];
+            do {
+                groupBy.push(this.expression());
+            } while (this.match(TokenType.COMMA));
+            lastConsumedToken = this.previous(); // After last group by expression
+        }
+        // Parse HAVING clause if present
+        let having;
+        if (this.match(TokenType.HAVING)) {
+            having = this.expression();
+            lastConsumedToken = this.previous(); // After having expression
+        }
+        // Check for compound set operations (UNION / INTERSECT / EXCEPT) BEFORE ORDER BY/LIMIT
+        let compound;
+        if (this.match(TokenType.UNION, TokenType.INTERSECT, TokenType.EXCEPT)) {
+            const tok = this.previous();
+            let op;
+            if (tok.type === TokenType.UNION) {
+                if (this.match(TokenType.ALL)) {
+                    op = 'unionAll';
+                }
+                else {
+                    op = 'union';
+                }
+            }
+            else if (tok.type === TokenType.INTERSECT) {
+                op = 'intersect';
+            }
+            else {
+                op = 'except';
+            }
+            let rightSelect;
+            // Handle parenthesized subquery after set operation
+            if (this.match(TokenType.LPAREN)) {
+                const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in parenthesized set operation.");
+                rightSelect = this.selectStatement(selectToken, withClause, true); // Pass true to indicate compound subquery
+                this.consume(TokenType.RPAREN, "Expected ')' after parenthesized set operation.");
+            }
+            else {
+                // Handle direct SELECT statement
+                const selectStartToken = this.peek();
+                if (this.match(TokenType.SELECT)) {
+                    rightSelect = this.selectStatement(selectStartToken, withClause, true); // Pass true to indicate compound subquery
+                }
+                else {
+                    throw this.error(this.peek(), "Expected 'SELECT' or '(' after set operation keyword.");
+                }
+            }
+            lastConsumedToken = this.previous();
+            compound = { op, select: rightSelect };
+        }
+        // Parse ORDER BY clause if present (applies to final result after compound operations)
+        // Skip if this is a compound subquery as ORDER BY belongs to the outer compound
+        let orderBy;
+        if (!isCompoundSubquery && this.match(TokenType.ORDER) && this.consume(TokenType.BY, "Expected 'BY' after 'ORDER'.")) {
+            orderBy = [];
+            do {
+                const expr = this.expression();
+                const direction = this.match(TokenType.DESC) ? 'desc' :
+                    (this.match(TokenType.ASC) ? 'asc' : 'asc'); // Default to ASC
+                orderBy.push({ expr, direction });
+            } while (this.match(TokenType.COMMA));
+            lastConsumedToken = this.previous(); // After last order by clause
+        }
+        // Parse LIMIT clause if present (applies to final result after compound operations)
+        // Skip if this is a compound subquery as LIMIT belongs to the outer compound
+        let limit;
+        let offset;
+        if (!isCompoundSubquery && this.match(TokenType.LIMIT)) {
+            limit = this.expression();
+            lastConsumedToken = this.previous(); // After limit expression
+            // LIMIT x OFFSET y syntax
+            if (this.match(TokenType.OFFSET)) {
+                offset = this.expression();
+                lastConsumedToken = this.previous(); // After offset expression
+            }
+            // LIMIT x, y syntax (x is offset, y is limit)
+            else if (this.match(TokenType.COMMA)) {
+                offset = limit;
+                limit = this.expression();
+                lastConsumedToken = this.previous(); // After second limit expression
+            }
+        }
+        return {
+            type: 'select',
+            columns,
+            from,
+            where,
+            groupBy,
+            having,
+            orderBy,
+            limit,
+            offset,
+            distinct,
+            all,
+            compound,
+            loc: _createLoc(start, lastConsumedToken),
+        };
+    }
+    /**
+     * Parse a comma-separated list of result columns for SELECT
+     */
+    columnList() {
+        const columns = [];
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        do {
+            log(`columnList: Loop start. Current token: ${this.peek().lexeme} (${this.peek().type})`); // DEBUG
+            // Handle wildcard: * or table.*
+            if (this.match(TokenType.ASTERISK)) {
+                columns.push({ type: 'all' });
+            }
+            // Handle table.* syntax
+            else if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT) &&
+                this.checkNext(2, TokenType.ASTERISK)) {
+                const table = this.consumeIdentifier(contextualKeywords, "Expected table name before '.*'.");
+                this.advance(); // consume DOT
+                this.advance(); // consume ASTERISK
+                columns.push({ type: 'all', table });
+            }
+            // Handle regular column expression
+            else {
+                log(`columnList: Parsing expression...`); // DEBUG
+                const expr = this.expression();
+                log(`columnList: Parsed expression. Current token: ${this.peek().lexeme} (${this.peek().type})`); // DEBUG
+                let alias;
+                // Handle AS alias or just alias
+                if (this.match(TokenType.AS)) {
+                    if (this.checkIdentifierLike(contextualKeywords) || this.check(TokenType.STRING)) {
+                        const aliasToken = this.advance();
+                        alias = aliasToken.lexeme;
+                        if (aliasToken.type === TokenType.STRING) {
+                            alias = aliasToken.literal;
+                        }
+                    }
+                    else {
+                        throw this.error(this.peek(), "Expected identifier or string after 'AS'.");
+                    }
+                }
+                // Implicit alias (no AS keyword)
+                else if (this.checkIdentifierLike([]) &&
+                    !this.checkNext(1, TokenType.LPAREN) &&
+                    !this.checkNext(1, TokenType.DOT) &&
+                    !this.checkNext(1, TokenType.COMMA) &&
+                    !this.isEndOfClause()) {
+                    const aliasToken = this.advance();
+                    alias = aliasToken.lexeme;
+                }
+                columns.push({ type: 'column', expr, alias });
+            }
+            log(`columnList: Checking for comma. Current token: ${this.peek().lexeme} (${this.peek().type})`); // DEBUG
+        } while (this.match(TokenType.COMMA));
+        log(`columnList: Loop ended. Current token: ${this.peek().lexeme} (${this.peek().type})`); // DEBUG
+        return columns;
+    }
+    /**
+     * Parse a table identifier (possibly schema-qualified)
+     */
+    tableIdentifier() {
+        const startToken = this.peek();
+        let schema;
+        let name;
+        let endToken = startToken;
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        // Check for schema.table pattern
+        if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT)) {
+            schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
+            this.advance(); // Consume DOT
+            name = this.consumeIdentifier(contextualKeywords, "Expected table name after schema.");
+            endToken = this.previous();
+        }
+        else if (this.checkIdentifierLike(contextualKeywords)) {
+            name = this.consumeIdentifier(contextualKeywords, "Expected table name.");
+            endToken = this.previous();
+        }
+        else {
+            throw this.error(this.peek(), "Expected table name.");
+        }
+        return {
+            type: 'identifier',
+            name,
+            schema,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    /**
+     * Parse a comma-separated list of table sources (FROM clause)
+     */
+    tableSourceList(withClause) {
+        const sources = [];
+        do {
+            // Get the base table source
+            let source = this.tableSource(withClause);
+            // Look for JOINs
+            while (this.isJoinToken()) {
+                source = this.joinClause(source, withClause);
+            }
+            sources.push(source);
+        } while (this.match(TokenType.COMMA));
+        return sources;
+    }
+    /**
+     * Parse a single table source, which can now be a table name, table-valued function call, or subquery
+     */
+    tableSource(withClause) {
+        const startToken = this.peek();
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        // Check for subquery: ( SELECT ... or ( VALUES ... or ( INSERT/UPDATE/DELETE ...
+        if (this.check(TokenType.LPAREN)) {
+            // Look ahead to see if this is a subquery
+            const lookahead = this.current + 1;
+            if (lookahead < this.tokens.length) {
+                const nextTokenType = this.tokens[lookahead].type;
+                if (nextTokenType === TokenType.SELECT || nextTokenType === TokenType.VALUES) {
+                    return this.subquerySource(startToken, withClause);
+                }
+                else if (nextTokenType === TokenType.INSERT || nextTokenType === TokenType.UPDATE || nextTokenType === TokenType.DELETE) {
+                    return this.mutatingSubquerySource(startToken, withClause);
+                }
+            }
+        }
+        // Check for function call syntax: IDENTIFIER (
+        if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.LPAREN)) {
+            return this.functionSource(startToken);
+        }
+        // Otherwise, assume it's a standard table source
+        else {
+            return this.standardTableSource(startToken);
+        }
+    }
+    /** Parses a subquery source: (SELECT ...) AS alias */
+    subquerySource(startToken, withClause) {
+        this.consume(TokenType.LPAREN, "Expected '(' before subquery.");
+        let subquery;
+        if (this.check(TokenType.SELECT)) {
+            // Consume the SELECT token and pass it as startToken to selectStatement
+            const selectToken = this.advance();
+            subquery = this.selectStatement(selectToken, withClause);
+        }
+        else if (this.check(TokenType.VALUES)) {
+            // Handle VALUES subquery
+            const valuesToken = this.advance();
+            subquery = this.valuesStatement(valuesToken);
+        }
+        else {
+            throw this.error(this.peek(), "Expected 'SELECT' or 'VALUES' in subquery.");
+        }
+        this.consume(TokenType.RPAREN, "Expected ')' after subquery.");
+        // Parse optional alias for subquery
+        let alias;
+        let columns;
+        if (this.match(TokenType.AS)) {
+            if (!this.checkIdentifierLike([])) {
+                throw this.error(this.peek(), "Expected alias after 'AS'.");
+            }
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+        }
+        else if (this.checkIdentifierLike([]) &&
+            !this.checkNext(1, TokenType.DOT) &&
+            !this.checkNext(1, TokenType.COMMA) &&
+            !this.isJoinToken() &&
+            !this.isEndOfClause()) {
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+        }
+        else {
+            // Generate a default alias if none provided
+            alias = `subquery_${startToken.startOffset}`;
+        }
+        // Parse optional column list after alias: AS alias(col1, col2, ...)
+        if (this.match(TokenType.LPAREN)) {
+            columns = [];
+            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
+        }
+        const endToken = this.previous();
+        return {
+            type: 'subquerySource',
+            subquery,
+            alias,
+            columns,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    /** Parses a mutating subquery source: (INSERT/UPDATE/DELETE ... RETURNING ...) AS alias */
+    mutatingSubquerySource(startToken, withClause) {
+        this.consume(TokenType.LPAREN, "Expected '(' before mutating subquery.");
+        let stmt;
+        if (this.check(TokenType.INSERT)) {
+            const insertToken = this.advance();
+            stmt = this.insertStatement(insertToken, withClause);
+        }
+        else if (this.check(TokenType.UPDATE)) {
+            const updateToken = this.advance();
+            stmt = this.updateStatement(updateToken, withClause);
+        }
+        else if (this.check(TokenType.DELETE)) {
+            const deleteToken = this.advance();
+            stmt = this.deleteStatement(deleteToken, withClause);
+        }
+        else {
+            throw this.error(this.peek(), "Expected 'INSERT', 'UPDATE', or 'DELETE' in mutating subquery.");
+        }
+        // Validate that the statement has a RETURNING clause
+        if (!stmt.returning || stmt.returning.length === 0) {
+            throw this.error(this.previous(), "Mutating subqueries must have a RETURNING clause to be used as table sources.");
+        }
+        this.consume(TokenType.RPAREN, "Expected ')' after mutating subquery.");
+        // Parse optional alias for mutating subquery
+        let alias;
+        let columns;
+        if (this.match(TokenType.AS)) {
+            if (!this.checkIdentifierLike([])) {
+                throw this.error(this.peek(), "Expected alias after 'AS'.");
+            }
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+        }
+        else if (this.checkIdentifierLike([]) &&
+            !this.checkNext(1, TokenType.DOT) &&
+            !this.checkNext(1, TokenType.COMMA) &&
+            !this.isJoinToken() &&
+            !this.isEndOfClause()) {
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+        }
+        else {
+            // Generate a default alias if none provided
+            alias = `mutating_subquery_${startToken.startOffset}`;
+        }
+        // Parse optional column list after alias: AS alias(col1, col2, ...)
+        if (this.match(TokenType.LPAREN)) {
+            columns = [];
+            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
+        }
+        const endToken = this.previous();
+        return {
+            type: 'mutatingSubquerySource',
+            stmt,
+            alias,
+            columns,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    /** Parses a standard table source (schema.table or table) */
+    standardTableSource(startToken) {
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        // Parse table name (potentially schema-qualified)
+        const table = this.tableIdentifier();
+        let endToken = this.previous(); // Initialize endToken after parsing table identifier
+        // Parse optional alias
+        let alias;
+        if (this.match(TokenType.AS)) {
+            if (!this.checkIdentifierLike(contextualKeywords)) {
+                throw this.error(this.peek(), "Expected alias after 'AS'.");
+            }
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+            endToken = aliasToken;
+        }
+        else if (this.checkIdentifierLike([]) &&
+            !this.checkNext(1, TokenType.DOT) &&
+            !this.checkNext(1, TokenType.COMMA) &&
+            !this.isJoinToken() &&
+            !this.isEndOfClause()) {
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+            endToken = aliasToken;
+        }
+        return {
+            type: 'table',
+            table,
+            alias,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    /** Parses a table-valued function source: name(arg1, ...) [AS alias] */
+    functionSource(startToken) {
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        const name = this.tableIdentifier(); // name has its own loc
+        let endToken = this.previous(); // Initialize endToken after parsing function identifier
+        this.consume(TokenType.LPAREN, "Expected '(' after table function name.");
+        const args = [];
+        if (!this.check(TokenType.RPAREN)) {
+            // Handle DISTINCT inside function calls like COUNT(DISTINCT col)
+            const distinct = this.matchKeyword('DISTINCT');
+            // Handle * argument AFTER checking for distinct
+            if (this.match(TokenType.ASTERISK)) {
+                // Do not add '*' as an argument to the list for aggregates like COUNT(*)
+                if (args.length > 0 || distinct) {
+                    // '*' is only valid as the *only* argument, potentially after DISTINCT
+                    // e.g. COUNT(*), COUNT(DISTINCT *) - though DISTINCT * might not be standard SQL?
+                    // For now, disallow '*' if other args exist.
+                    throw this.error(this.previous(), "'*' cannot be used with other arguments in function call.");
+                }
+                // If we parsed '*', the args list remains empty.
+            }
+            else {
+                // Parse regular arguments if '*' wasn't found
+                do {
+                    args.push(this.expression());
+                } while (this.match(TokenType.COMMA));
+            }
+        }
+        endToken = this.consume(TokenType.RPAREN, "Expected ')' after table function arguments.");
+        // Parse optional alias (same logic as for standard tables)
+        let alias;
+        if (this.match(TokenType.AS)) {
+            if (!this.checkIdentifierLike(contextualKeywords)) {
+                throw this.error(this.peek(), "Expected alias after 'AS'.");
+            }
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+            endToken = aliasToken;
+        }
+        else if (this.checkIdentifierLike([]) &&
+            !this.checkNext(1, TokenType.DOT) &&
+            !this.checkNext(1, TokenType.COMMA) &&
+            !this.isJoinToken() &&
+            !this.isEndOfClause()) {
+            const aliasToken = this.advance();
+            alias = aliasToken.lexeme;
+            endToken = aliasToken;
+        }
+        return {
+            type: 'functionSource',
+            name,
+            args,
+            alias,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    /**
+     * Parse a JOIN clause
+     */
+    joinClause(left, withClause) {
+        const joinStartToken = this.peek(); // Capture token before parsing JOIN type
+        // Determine join type
+        let joinType = 'inner';
+        if (this.match(TokenType.LEFT)) {
+            this.match(TokenType.OUTER); // optional
+            joinType = 'left';
+        }
+        else if (this.match(TokenType.RIGHT)) {
+            this.match(TokenType.OUTER); // optional
+            joinType = 'right';
+        }
+        else if (this.match(TokenType.FULL)) {
+            this.match(TokenType.OUTER); // optional
+            joinType = 'full';
+        }
+        else if (this.match(TokenType.CROSS)) {
+            joinType = 'cross';
+        }
+        else if (this.match(TokenType.INNER)) {
+            joinType = 'inner';
+        }
+        // Consume JOIN token
+        this.consume(TokenType.JOIN, "Expected 'JOIN'.");
+        // Parse right side of join
+        const right = this.tableSource(withClause);
+        // Parse join condition
+        let condition;
+        let columns;
+        let endToken = this.previous(); // End token is end of right source initially
+        if (this.match(TokenType.ON)) {
+            condition = this.expression();
+            endToken = this.previous(); // End token is end of ON expression
+        }
+        else if (this.match(TokenType.USING)) {
+            this.consume(TokenType.LPAREN, "Expected '(' after 'USING'.");
+            columns = [];
+            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+            do {
+                columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name."));
+            } while (this.match(TokenType.COMMA));
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after columns.");
+        }
+        else if (joinType !== 'cross') {
+            throw this.error(this.peek(), "Expected 'ON' or 'USING' after JOIN.");
+        }
+        return {
+            type: 'join',
+            joinType,
+            left,
+            right,
+            condition,
+            columns,
+            loc: _createLoc(joinStartToken, endToken),
+        };
+    }
+    /**
+     * Parse an expression
+     */
+    expression() {
+        return this.logicalXorOr();
+    }
+    /**
+     * Parse logical OR and XOR expressions (lowest precedence)
+     */
+    logicalXorOr() {
+        let expr = this.logicalAnd();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.OR, TokenType.XOR)) { // Added XOR
+            const operator = this.previous().type === TokenType.XOR ? 'XOR' : 'OR'; // Determine operator
+            const right = this.logicalAnd();
+            const endToken = this.previous(); // End token is end of right expr
+            expr = {
+                type: 'binary',
+                operator,
+                left: expr,
+                right,
+                loc: _createLoc(startToken, endToken),
+            };
+        }
+        return expr;
+    }
+    /**
+     * Parse logical AND expression
+     */
+    logicalAnd() {
+        let expr = this.isNull();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.AND)) {
+            const operator = 'AND';
+            const right = this.isNull();
+            const endToken = this.previous(); // End token is end of right expr
+            expr = {
+                type: 'binary',
+                operator,
+                left: expr,
+                right,
+                loc: _createLoc(startToken, endToken),
+            };
+        }
+        return expr;
+    }
+    /**
+     * Parse IS NULL / IS NOT NULL expressions
+     */
+    isNull() {
+        const expr = this.equality();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        if (this.match(TokenType.IS)) {
+            let isNot = false;
+            if (this.match(TokenType.NOT)) {
+                isNot = true;
+            }
+            if (this.match(TokenType.NULL)) {
+                const endToken = this.previous(); // End token is NULL
+                const operator = isNot ? 'IS NOT NULL' : 'IS NULL';
+                // Represent IS NULL / IS NOT NULL as UnaryExpr for simplicity
+                return { type: 'unary', operator, expr, loc: _createLoc(startToken, endToken) };
+            }
+            // If it was IS or IS NOT but not followed by NULL, maybe it's IS TRUE/FALSE/DISTINCT FROM?
+            // For now, assume standard comparison if NULL doesn't follow IS [NOT]
+            // We need to "unread" the IS and optional NOT token if we didn't match NULL.
+            // Backtrack current position.
+            if (isNot)
+                this.current--; // Backtrack NOT
+            this.current--; // Backtrack IS
+        }
+        return expr;
+    }
+    /**
+     * Parse equality expression
+     */
+    equality() {
+        let expr = this.comparison();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.EQUAL, TokenType.EQUAL_EQUAL, TokenType.NOT_EQUAL)) {
+            let operator;
+            switch (this.previous().type) {
+                case TokenType.NOT_EQUAL:
+                    operator = '!=';
+                    break;
+                case TokenType.EQUAL_EQUAL:
+                    operator = '==';
+                    break;
+                default:
+                    operator = '=';
+                    break;
+            }
+            const right = this.comparison();
+            const endToken = this.previous(); // End token is end of right expr
+            expr = {
+                type: 'binary',
+                operator,
+                left: expr,
+                right,
+                loc: _createLoc(startToken, endToken),
+            };
+        }
+        return expr;
+    }
+    /**
+     * Parse comparison expression
+     */
+    comparison() {
+        let expr = this.term();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.LESS, TokenType.LESS_EQUAL, TokenType.GREATER, TokenType.GREATER_EQUAL, TokenType.BETWEEN, TokenType.IN, TokenType.NOT, TokenType.LIKE)) {
+            const operatorToken = this.previous();
+            // Handle NOT IN, NOT BETWEEN, and NOT LIKE
+            if (operatorToken.type === TokenType.NOT) {
+                const notStartToken = operatorToken;
+                if (this.match(TokenType.IN)) {
+                    // NOT IN
+                    this.consume(TokenType.LPAREN, "Expected '(' after NOT IN.");
+                    if (this.check(TokenType.SELECT)) {
+                        // NOT IN subquery: expr NOT IN (SELECT ...)
+                        const selectToken = this.advance(); // Consume SELECT
+                        const subquery = this.selectStatement(selectToken);
+                        const endToken = this.consume(TokenType.RPAREN, "Expected ')' after NOT IN subquery.");
+                        // Create an IN expression with subquery, then wrap in NOT
+                        const inExpr = {
+                            type: 'in',
+                            expr,
+                            subquery,
+                            loc: _createLoc(startToken, endToken),
+                        };
+                        expr = {
+                            type: 'unary',
+                            operator: 'NOT',
+                            expr: inExpr,
+                            loc: _createLoc(notStartToken, endToken),
+                        };
+                    }
+                    else {
+                        // NOT IN value list: expr NOT IN (value1, value2, ...)
+                        const values = [];
+                        if (!this.check(TokenType.RPAREN)) {
+                            do {
+                                values.push(this.expression());
+                            } while (this.match(TokenType.COMMA));
+                        }
+                        const endToken = this.consume(TokenType.RPAREN, "Expected ')' after NOT IN values.");
+                        // Create an IN expression with value list, then wrap in NOT
+                        const inExpr = {
+                            type: 'in',
+                            expr,
+                            values,
+                            loc: _createLoc(startToken, endToken),
+                        };
+                        expr = {
+                            type: 'unary',
+                            operator: 'NOT',
+                            expr: inExpr,
+                            loc: _createLoc(notStartToken, endToken),
+                        };
+                    }
+                }
+                else if (this.match(TokenType.BETWEEN)) {
+                    // NOT BETWEEN
+                    const low = this.term();
+                    this.consume(TokenType.AND, "Expected 'AND' after NOT BETWEEN lower bound.");
+                    const high = this.term();
+                    const endToken = this.previous(); // End token is end of high expr
+                    // Create a binary AND expression for the bounds
+                    const boundsExpr = {
+                        type: 'binary',
+                        operator: 'AND',
+                        left: low,
+                        right: high,
+                        loc: _createLoc(low.loc?.start ? this.tokens.find(t => t.startOffset === low.loc.start.offset) ?? this.peek() : this.peek(), endToken)
+                    };
+                    // Create the BETWEEN expression as a binary expression, then wrap in NOT
+                    const betweenExpr = {
+                        type: 'binary',
+                        operator: 'BETWEEN',
+                        left: expr,
+                        right: boundsExpr,
+                        loc: _createLoc(startToken, endToken),
+                    };
+                    expr = {
+                        type: 'unary',
+                        operator: 'NOT',
+                        expr: betweenExpr,
+                        loc: _createLoc(notStartToken, endToken),
+                    };
+                }
+                else if (this.match(TokenType.LIKE)) {
+                    // NOT LIKE
+                    const pattern = this.term();
+                    const endToken = this.previous(); // End token is end of pattern expr
+                    // Create the LIKE expression as a binary expression, then wrap in NOT
+                    const likeExpr = {
+                        type: 'binary',
+                        operator: 'LIKE',
+                        left: expr,
+                        right: pattern,
+                        loc: _createLoc(startToken, endToken),
+                    };
+                    expr = {
+                        type: 'unary',
+                        operator: 'NOT',
+                        expr: likeExpr,
+                        loc: _createLoc(notStartToken, endToken),
+                    };
+                }
+                else {
+                    // Put back the NOT token and break out of the loop
+                    this.current--;
+                    break;
+                }
+            }
+            else if (operatorToken.type === TokenType.LIKE) {
+                // Parse LIKE expression: expr LIKE pattern
+                const pattern = this.term();
+                const endToken = this.previous(); // End token is end of pattern expr
+                // Create the LIKE expression as a binary expression
+                expr = {
+                    type: 'binary',
+                    operator: 'LIKE',
+                    left: expr,
+                    right: pattern,
+                    loc: _createLoc(startToken, endToken),
+                };
+            }
+            else if (operatorToken.type === TokenType.BETWEEN) {
+                // Parse BETWEEN expression: expr BETWEEN low AND high
+                const low = this.term();
+                this.consume(TokenType.AND, "Expected 'AND' after BETWEEN lower bound.");
+                const high = this.term();
+                const endToken = this.previous(); // End token is end of high expr
+                // Create a binary AND expression for the bounds
+                const boundsExpr = {
+                    type: 'binary',
+                    operator: 'AND',
+                    left: low,
+                    right: high,
+                    loc: _createLoc(low.loc?.start ? this.tokens.find(t => t.startOffset === low.loc.start.offset) ?? this.peek() : this.peek(), endToken)
+                };
+                // Create the BETWEEN expression as a binary expression
+                expr = {
+                    type: 'binary',
+                    operator: 'BETWEEN',
+                    left: expr,
+                    right: boundsExpr,
+                    loc: _createLoc(startToken, endToken),
+                };
+            }
+            else if (operatorToken.type === TokenType.IN) {
+                // Parse IN expression: expr IN (value1, value2, ...) or expr IN (subquery)
+                this.consume(TokenType.LPAREN, "Expected '(' after IN.");
+                // Check if this is a subquery or value list
+                if (this.check(TokenType.SELECT)) {
+                    // IN subquery: expr IN (SELECT ...)
+                    const selectToken = this.advance(); // Consume SELECT
+                    const subquery = this.selectStatement(selectToken);
+                    const endToken = this.consume(TokenType.RPAREN, "Expected ')' after IN subquery.");
+                    // Create an IN expression with subquery
+                    expr = {
+                        type: 'in',
+                        expr,
+                        subquery,
+                        loc: _createLoc(startToken, endToken),
+                    };
+                }
+                else {
+                    // IN value list: expr IN (value1, value2, ...)
+                    const values = [];
+                    if (!this.check(TokenType.RPAREN)) {
+                        do {
+                            values.push(this.expression());
+                        } while (this.match(TokenType.COMMA));
+                    }
+                    const endToken = this.consume(TokenType.RPAREN, "Expected ')' after IN values.");
+                    // Create an IN expression with value list
+                    expr = {
+                        type: 'in',
+                        expr,
+                        values,
+                        loc: _createLoc(startToken, endToken),
+                    };
+                }
+            }
+            else {
+                // Handle other comparison operators
+                let operator;
+                switch (operatorToken.type) {
+                    case TokenType.LESS:
+                        operator = '<';
+                        break;
+                    case TokenType.LESS_EQUAL:
+                        operator = '<=';
+                        break;
+                    case TokenType.GREATER:
+                        operator = '>';
+                        break;
+                    case TokenType.GREATER_EQUAL:
+                        operator = '>=';
+                        break;
+                    default: operator = '?';
+                }
+                const right = this.term();
+                const endToken = this.previous(); // End token is end of right expr
+                expr = {
+                    type: 'binary',
+                    operator,
+                    left: expr,
+                    right,
+                    loc: _createLoc(startToken, endToken),
+                };
+            }
+        }
+        return expr;
+    }
+    /**
+     * Parse addition and subtraction
+     */
+    term() {
+        let expr = this.factor();
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.PLUS, TokenType.MINUS)) {
+            const operator = this.previous().type === TokenType.PLUS ? '+' : '-';
+            const right = this.factor();
+            const endToken = this.previous(); // End token is end of right expr
+            expr = {
+                type: 'binary',
+                operator,
+                left: expr,
+                right,
+                loc: _createLoc(startToken, endToken),
+            };
+        }
+        return expr;
+    }
+    /**
+     * Parse multiplication and division
+     */
+    factor() {
+        // First, handle unary operators
+        if (this.match(TokenType.MINUS, TokenType.PLUS, TokenType.TILDE, TokenType.NOT)) { // Added NOT
+            const operatorToken = this.previous();
+            const operatorStartToken = operatorToken; // Start token is the operator itself
+            const operator = operatorToken.lexeme;
+            // Unary operator applies to the result of the *next* precedence level (concatenation)
+            const right = this.concatenation(); // Should call concatenation (higher precedence than factor)
+            const endToken = this.previous(); // End token is end of the operand
+            return { type: 'unary', operator, expr: right, loc: _createLoc(operatorStartToken, endToken) };
+        }
+        let expr = this.concatenation(); // Factor operands have higher precedence (concatenation)
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.ASTERISK, TokenType.SLASH, TokenType.PERCENT)) {
+            const operatorToken = this.previous();
+            const operator = operatorToken.lexeme;
+            const right = this.concatenation(); // Factor operands have higher precedence (concatenation)
+            const endToken = this.previous(); // End token is end of right expr
+            expr = { type: 'binary', operator, left: expr, right, loc: _createLoc(startToken, endToken) };
+        }
+        return expr;
+    }
+    /**
+     * Parse concatenation expression (||)
+     */
+    concatenation() {
+        let expr = this.collateExpression(); // Concatenation operands have higher precedence (collate)
+        const startToken = expr.loc ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek(); // Get start token of left expr
+        while (this.match(TokenType.PIPE_PIPE)) {
+            const operator = '||';
+            const right = this.collateExpression(); // Concatenation operands have higher precedence (collate)
+            const endToken = this.previous(); // End token is end of right expr
+            expr = {
+                type: 'binary',
+                operator,
+                left: expr,
+                right,
+                loc: _createLoc(startToken, endToken),
+            };
+        }
+        return expr;
+    }
+    /**
+     * Parse COLLATE expression
+     */
+    collateExpression() {
+        const expr = this.primary(); // Parse primary expression first
+        if (this.matchKeyword('COLLATE')) {
+            const collationToken = this.consume(TokenType.IDENTIFIER, "Expected collation name after COLLATE.");
+            const collation = collationToken.lexeme;
+            // Use the start of the original expression and end of collation name for location
+            const startLocToken = expr.loc?.start ? this.tokens.find(t => t.startOffset === expr.loc.start.offset) ?? this.peek() : this.peek();
+            return { type: 'collate', expr, collation, loc: _createLoc(startLocToken, collationToken) };
+        }
+        return expr;
+    }
+    /**
+     * Parse primary expressions (literals, identifiers, etc.)
+     */
+    primary() {
+        const startToken = this.peek();
+        // Case expression
+        if (this.matchKeyword('CASE')) {
+            return this.parseCaseExpression(startToken);
+        }
+        // CAST expression: CAST(expr AS type)
+        if (this.peekKeyword('CAST') && this.checkNext(1, TokenType.LPAREN)) {
+            const castToken = this.advance(); // Consume CAST
+            this.consume(TokenType.LPAREN, "Expected '(' after CAST.");
+            const expr = this.expression();
+            this.consumeKeyword('AS', "Expected 'AS' in CAST expression.");
+            // Allow type names that might be keywords (e.g., TEXT, INTEGER, REAL, BLOB)
+            // or multi-word type names if supported (e.g., "VARCHAR(255)") - for now, simple identifier
+            if (!this.check(TokenType.IDENTIFIER) &&
+                !this.isTypeNameKeyword(this.peek().lexeme.toUpperCase())) {
+                throw this.error(this.peek(), "Expected type name after 'AS' in CAST expression.");
+            }
+            const typeToken = this.advance(); // Consume type name
+            const targetType = typeToken.lexeme;
+            const endToken = this.consume(TokenType.RPAREN, "Expected ')' after CAST expression type.");
+            return { type: 'cast', expr, targetType, loc: _createLoc(castToken, endToken) };
+        }
+        // EXISTS expression: EXISTS(SELECT ...)
+        if (this.match(TokenType.EXISTS)) {
+            const existsToken = this.previous();
+            this.consume(TokenType.LPAREN, "Expected '(' after EXISTS.");
+            const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in EXISTS subquery.");
+            const subquery = this.selectStatement(selectToken);
+            const endToken = this.consume(TokenType.RPAREN, "Expected ')' after EXISTS subquery.");
+            return {
+                type: 'exists',
+                subquery,
+                loc: _createLoc(existsToken, endToken)
+            };
+        }
+        // Literals
+        if (this.match(TokenType.INTEGER, TokenType.FLOAT, TokenType.STRING, TokenType.NULL, TokenType.TRUE, TokenType.FALSE, TokenType.BLOB)) {
+            const token = this.previous();
+            let value;
+            let lexeme = undefined;
+            if (token.type === TokenType.NULL) {
+                value = null;
+                lexeme = token.lexeme; // Store original case (NULL vs null)
+            }
+            else if (token.type === TokenType.TRUE) {
+                value = true;
+                lexeme = token.lexeme; // Store original case (TRUE vs true)
+            }
+            else if (token.type === TokenType.FALSE) {
+                value = false;
+                lexeme = token.lexeme; // Store original case (FALSE vs false)
+            }
+            else if (token.type === TokenType.FLOAT) {
+                // For FLOAT, parse the literal (which is the original string)
+                value = parseFloat(token.literal);
+                lexeme = token.literal; // Store original string as lexeme
+            }
+            else if (token.type === TokenType.INTEGER) {
+                value = token.literal; // Already number or BigInt
+                if (token.lexeme !== String(value)) { // Store lexeme only if different
+                    lexeme = token.lexeme;
+                }
+            }
+            else {
+                value = token.literal; // STRING, BLOB
+            }
+            const node = { type: 'literal', value, loc: _createLoc(startToken, token) };
+            if (lexeme !== undefined) {
+                node.lexeme = lexeme;
+            }
+            return node;
+        }
+        // Parameter expressions (?, :name, $name)
+        if (this.match(TokenType.QUESTION)) {
+            const token = this.previous();
+            return { type: 'parameter', index: this.parameterPosition++, loc: _createLoc(startToken, token) };
+        }
+        if (this.match(TokenType.COLON, TokenType.DOLLAR)) {
+            // Named parameter (can be identifier like :name or integer like :1)
+            if (!this.check(TokenType.IDENTIFIER) && !this.check(TokenType.INTEGER)) {
+                throw this.error(this.peek(), "Expected identifier or number after parameter prefix.");
+            }
+            const nameToken = this.advance();
+            return { type: 'parameter', name: nameToken.lexeme, loc: _createLoc(startToken, nameToken) };
+        }
+        // Function call (with optional window function support)
+        if (this.checkIdentifierLike(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like']) && this.checkNext(1, TokenType.LPAREN)) {
+            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected function name.");
+            this.consume(TokenType.LPAREN, "Expected '(' after function name.");
+            const args = [];
+            let distinct = false;
+            if (!this.check(TokenType.RPAREN)) {
+                // Handle DISTINCT inside function calls like COUNT(DISTINCT col)
+                distinct = this.matchKeyword('DISTINCT');
+                // Handle * argument AFTER checking for distinct
+                if (this.match(TokenType.ASTERISK)) {
+                    // Do not add '*' as an argument to the list for aggregates like COUNT(*)
+                    if (args.length > 0 || distinct) {
+                        // '*' is only valid as the *only* argument, potentially after DISTINCT
+                        // e.g. COUNT(*), COUNT(DISTINCT *) - though DISTINCT * might not be standard SQL?
+                        // For now, disallow '*' if other args exist.
+                        throw this.error(this.previous(), "'*' cannot be used with other arguments in function call.");
+                    }
+                    // If we parsed '*', the args list remains empty.
+                }
+                else {
+                    // Parse regular arguments if '*' wasn't found
+                    do {
+                        args.push(this.expression());
+                    } while (this.match(TokenType.COMMA));
+                }
+            }
+            const endToken = this.consume(TokenType.RPAREN, "Expected ')' after function arguments.");
+            const funcExpr = {
+                type: 'function',
+                name,
+                args,
+                loc: _createLoc(startToken, endToken)
+            };
+            // Add distinct field if it was parsed
+            if (distinct) {
+                funcExpr.distinct = true;
+            }
+            // Check for OVER clause (window function)
+            if (this.matchKeyword('OVER')) {
+                const window = this.parseWindowSpecification();
+                const overEndToken = this.previous();
+                return {
+                    type: 'windowFunction',
+                    function: funcExpr,
+                    window,
+                    loc: _createLoc(startToken, overEndToken)
+                };
+            }
+            return funcExpr;
+        }
+        // Column/identifier expressions
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        if (this.checkIdentifierLike(contextualKeywords)) {
+            // Schema.table.column
+            if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, contextualKeywords) &&
+                this.checkNext(3, TokenType.DOT) && this.checkIdentifierLikeAt(4, contextualKeywords)) {
+                const schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
+                this.advance(); // Consume DOT
+                const table = this.consumeIdentifier(contextualKeywords, "Expected table name.");
+                this.advance(); // Consume DOT
+                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const nameToken = this.previous();
+                return {
+                    type: 'column',
+                    name,
+                    table,
+                    schema,
+                    loc: _createLoc(startToken, nameToken),
+                };
+            }
+            // table.column
+            else if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, contextualKeywords)) {
+                const table = this.consumeIdentifier(contextualKeywords, "Expected table name.");
+                this.advance(); // Consume DOT
+                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const nameToken = this.previous();
+                return {
+                    type: 'column',
+                    name,
+                    table,
+                    loc: _createLoc(startToken, nameToken),
+                };
+            }
+            // just column
+            else {
+                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const nameToken = this.previous();
+                return {
+                    type: 'column',
+                    name,
+                    loc: _createLoc(startToken, nameToken),
+                };
+            }
+        }
+        // Parenthesized expression or scalar subquery
+        if (this.match(TokenType.LPAREN)) {
+            // Look ahead to see if this is a scalar subquery (SELECT ...)
+            if (this.check(TokenType.SELECT)) {
+                const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in subquery.");
+                const subquery = this.selectStatement(selectToken);
+                this.consume(TokenType.RPAREN, "Expected ')' after subquery.");
+                return {
+                    type: 'subquery',
+                    query: subquery,
+                    loc: _createLoc(startToken, this.previous())
+                };
+            }
+            else {
+                // Regular parenthesized expression
+                const expr = this.expression();
+                this.consume(TokenType.RPAREN, "Expected ')' after expression.");
+                return expr;
+            }
+        }
+        throw this.error(this.peek(), "Expected expression.");
+    }
+    /**
+     * Parses a window specification: (PARTITION BY ... ORDER BY ... [frame])
+     */
+    parseWindowSpecification() {
+        if (this.match(TokenType.LPAREN)) {
+            let partitionBy;
+            let orderBy;
+            let frame;
+            if (this.matchKeyword('PARTITION')) {
+                this.consumeKeyword('BY', "Expected 'BY' after 'PARTITION'.");
+                partitionBy = [];
+                do {
+                    partitionBy.push(this.expression());
+                } while (this.match(TokenType.COMMA));
+            }
+            if (this.matchKeyword('ORDER')) {
+                this.consumeKeyword('BY', "Expected 'BY' after 'ORDER'.");
+                orderBy = [];
+                do {
+                    const expr = this.expression();
+                    const direction = this.match(TokenType.DESC) ? 'desc' : (this.match(TokenType.ASC) ? 'asc' : 'asc');
+                    // Handle NULLS FIRST/LAST
+                    let nullsOrdering;
+                    if (this.matchKeyword('NULLS')) {
+                        if (this.matchKeyword('FIRST')) {
+                            nullsOrdering = 'first';
+                        }
+                        else if (this.matchKeyword('LAST')) {
+                            nullsOrdering = 'last';
+                        }
+                        else {
+                            throw this.error(this.peek(), "Expected 'FIRST' or 'LAST' after 'NULLS'.");
+                        }
+                    }
+                    const orderClause = { expr, direction };
+                    if (nullsOrdering) {
+                        orderClause.nullsOrdering = nullsOrdering;
+                    }
+                    orderBy.push(orderClause);
+                } while (this.match(TokenType.COMMA));
+            }
+            // Frame clause (ROWS|RANGE ...)
+            if (this.matchKeyword('ROWS') || this.matchKeyword('RANGE')) {
+                const frameType = this.previous().lexeme.toLowerCase();
+                // Handle both BETWEEN...AND and single bound syntax
+                if (this.matchKeyword('BETWEEN')) {
+                    // ROWS BETWEEN start_bound AND end_bound
+                    const start = this.parseWindowFrameBound();
+                    this.consumeKeyword('AND', "Expected 'AND' after frame start bound.");
+                    const end = this.parseWindowFrameBound();
+                    frame = { type: frameType, start, end };
+                }
+                else {
+                    // ROWS start_bound (shorthand for ROWS BETWEEN start_bound AND CURRENT ROW)
+                    const start = this.parseWindowFrameBound();
+                    frame = { type: frameType, start, end: null };
+                }
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after window specification.");
+            return { type: 'windowDefinition', partitionBy, orderBy, frame };
+        }
+        else {
+            // Window name (not implemented)
+            throw this.error(this.peek(), 'Window name references are not yet supported. Use explicit window specs.');
+        }
+    }
+    /**
+     * Parses a window frame bound (UNBOUNDED PRECEDING, CURRENT ROW, n PRECEDING/FOLLOWING)
+     */
+    parseWindowFrameBound() {
+        if (this.matchKeyword('UNBOUNDED')) {
+            if (this.matchKeyword('PRECEDING')) {
+                return { type: 'unboundedPreceding' };
+            }
+            else if (this.matchKeyword('FOLLOWING')) {
+                return { type: 'unboundedFollowing' };
+            }
+            else {
+                throw this.error(this.peek(), "Expected PRECEDING or FOLLOWING after UNBOUNDED.");
+            }
+        }
+        else if (this.matchKeyword('CURRENT')) {
+            this.consumeKeyword('ROW', "Expected 'ROW' after 'CURRENT'.");
+            return { type: 'currentRow' };
+        }
+        else {
+            const value = this.expression();
+            if (this.matchKeyword('PRECEDING')) {
+                return { type: 'preceding', value };
+            }
+            else if (this.matchKeyword('FOLLOWING')) {
+                return { type: 'following', value };
+            }
+            else {
+                throw this.error(this.peek(), "Expected PRECEDING or FOLLOWING after frame value.");
+            }
+        }
+    }
+    // Helper methods for token management
+    match(...types) {
+        for (const type of types) {
+            if (this.check(type)) {
+                this.advance();
+                return true;
+            }
+        }
+        return false;
+    }
+    consume(type, message) {
+        if (this.check(type)) {
+            return this.advance();
+        }
+        this.error(this.peek(), message);
+    }
+    check(type) {
+        if (this.isAtEnd())
+            return false;
+        return this.peek().type === type;
+    }
+    checkNext(n, type) {
+        if (this.current + n >= this.tokens.length)
+            return false;
+        return this.tokens[this.current + n].type === type;
+    }
+    advance() {
+        if (!this.isAtEnd())
+            this.current++;
+        return this.previous();
+    }
+    isAtEnd() {
+        return this.peek().type === TokenType.EOF;
+    }
+    peek() {
+        return this.tokens[this.current];
+    }
+    previous() {
+        return this.tokens[this.current - 1];
+    }
+    error(token, message) {
+        quereusError(message, StatusCode.ERROR, undefined, {
+            loc: {
+                start: {
+                    line: token.startLine,
+                    column: token.startColumn,
+                },
+                end: {
+                    line: token.endLine,
+                    column: token.endColumn,
+                }
+            }
+        });
+    }
+    isJoinToken() {
+        return this.check(TokenType.JOIN) ||
+            this.check(TokenType.INNER) ||
+            this.check(TokenType.LEFT) ||
+            this.check(TokenType.RIGHT) ||
+            this.check(TokenType.FULL) ||
+            this.check(TokenType.CROSS);
+    }
+    isEndOfClause() {
+        const token = this.peek().type;
+        return token === TokenType.FROM ||
+            token === TokenType.WHERE ||
+            token === TokenType.GROUP ||
+            token === TokenType.HAVING ||
+            token === TokenType.ORDER ||
+            token === TokenType.LIMIT ||
+            token === TokenType.UNION ||
+            token === TokenType.SEMICOLON ||
+            token === TokenType.EOF;
+    }
+    // --- Statement Parsing Stubs ---
+    /** @internal */
+    updateStatement(startToken, _withClause) {
+        const table = this.tableIdentifier();
+        this.consume(TokenType.SET, "Expected 'SET' after table name in UPDATE.");
+        const assignments = [];
+        do {
+            const column = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name in SET clause.");
+            this.consume(TokenType.EQUAL, "Expected '=' after column name in SET clause.");
+            const value = this.expression();
+            assignments.push({ column, value });
+        } while (this.match(TokenType.COMMA));
+        let where;
+        if (this.match(TokenType.WHERE)) {
+            where = this.expression();
+        }
+        // Parse RETURNING clause if present
+        let returning;
+        if (this.matchKeyword('RETURNING')) {
+            returning = this.columnList();
+        }
+        const endToken = this.previous();
+        return { type: 'update', table, assignments, where, returning, loc: _createLoc(startToken, endToken) };
+    }
+    /** @internal */
+    deleteStatement(startToken, _withClause) {
+        this.matchKeyword('FROM');
+        const table = this.tableIdentifier();
+        let where;
+        if (this.match(TokenType.WHERE)) {
+            where = this.expression();
+        }
+        // Parse RETURNING clause if present
+        let returning;
+        if (this.matchKeyword('RETURNING')) {
+            returning = this.columnList();
+        }
+        const endToken = this.previous();
+        return { type: 'delete', table, where, returning, loc: _createLoc(startToken, endToken) };
+    }
+    /** @internal */
+    valuesStatement(startToken) {
+        const values = [];
+        do {
+            this.consume(TokenType.LPAREN, "Expected '(' before values.");
+            const valueList = [];
+            if (!this.check(TokenType.RPAREN)) { // Check for empty value list
+                do {
+                    valueList.push(this.expression());
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after values.");
+            values.push(valueList);
+        } while (this.match(TokenType.COMMA));
+        const endToken = this.previous();
+        return { type: 'values', values, loc: _createLoc(startToken, endToken) };
+    }
+    /** @internal */
+    createStatement(startToken, withClause) {
+        if (this.peekKeyword('TABLE')) {
+            this.consumeKeyword('TABLE', "Expected 'TABLE' after CREATE.");
+            return this.createTableStatement(startToken, withClause);
+        }
+        else if (this.peekKeyword('INDEX')) {
+            this.consumeKeyword('INDEX', "Expected 'INDEX' after CREATE.");
+            return this.createIndexStatement(startToken, false, withClause);
+        }
+        else if (this.peekKeyword('VIEW')) {
+            this.consumeKeyword('VIEW', "Expected 'VIEW' after CREATE.");
+            return this.createViewStatement(startToken, withClause);
+        }
+        else if (this.peekKeyword('UNIQUE')) {
+            this.consumeKeyword('UNIQUE', "Expected 'UNIQUE' after CREATE.");
+            this.consumeKeyword('INDEX', "Expected 'INDEX' after CREATE UNIQUE.");
+            return this.createIndexStatement(startToken, true, withClause);
+        }
+        throw this.error(this.peek(), "Expected TABLE, [UNIQUE] INDEX, VIEW, or VIRTUAL after CREATE.");
+    }
+    /**
+     * Parse CREATE TABLE statement
+     * @returns AST for CREATE TABLE
+     */
+    createTableStatement(startToken, _withClause) {
+        let isTemporary = false;
+        if (this.peekKeyword('TEMP') || this.peekKeyword('TEMPORARY')) {
+            isTemporary = true;
+            this.advance();
+        }
+        let ifNotExists = false;
+        if (this.matchKeyword('IF')) {
+            this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
+            this.consumeKeyword('EXISTS', "Expected 'EXISTS' after 'IF NOT'.");
+            ifNotExists = true;
+        }
+        const table = this.tableIdentifier();
+        const columns = [];
+        const constraints = [];
+        if (this.check(TokenType.LPAREN)) {
+            this.consume(TokenType.LPAREN, "Expected '(' to start table definition.");
+            do {
+                if (this.peekKeyword('PRIMARY') || this.peekKeyword('UNIQUE') || this.peekKeyword('CHECK') || this.peekKeyword('FOREIGN') || this.peekKeyword('CONSTRAINT')) {
+                    constraints.push(this.tableConstraint());
+                }
+                else {
+                    columns.push(this.columnDefinition());
+                }
+            } while (this.match(TokenType.COMMA));
+            this.consume(TokenType.RPAREN, "Expected ')' after table definition.");
+        }
+        else if (this.matchKeyword('AS')) {
+            const token = this.previous();
+            quereusError('CREATE TABLE AS SELECT is not supported.', StatusCode.UNSUPPORTED, undefined, { loc: { start: { line: token.startLine, column: token.startColumn } } });
+        }
+        else {
+            throw this.error(this.peek(), "Expected '(' or 'AS' after table name.");
+        }
+        let moduleName;
+        const moduleArgs = {};
+        if (this.matchKeyword('USING')) {
+            moduleName = this.consumeIdentifier("Expected module name after 'USING'.");
+            if (this.matchKeyword('(')) {
+                while (!this.match(TokenType.RPAREN)) {
+                    const nameValue = this.nameValueItem("module argument");
+                    moduleArgs[nameValue.name] = nameValue.value && nameValue.value.type === 'literal'
+                        ? getSyncLiteral(nameValue.value) : nameValue.name;
+                    if (!this.match(TokenType.COMMA) || this.check(TokenType.RPAREN)) {
+                        throw this.error(this.peek(), "Expected ',' or ')' after module argument.");
+                    }
+                }
+            }
+        }
+        return {
+            type: 'createTable',
+            table,
+            ifNotExists,
+            columns,
+            constraints,
+            isTemporary,
+            moduleName,
+            moduleArgs,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse CREATE INDEX statement
+     * @param isUnique Flag indicating if UNIQUE keyword was already parsed
+     * @returns AST for CREATE INDEX
+     */
+    createIndexStatement(startToken, isUnique = false, _withClause) {
+        if (!isUnique && this.peekKeyword('UNIQUE')) {
+            isUnique = true;
+            this.advance();
+        }
+        let ifNotExists = false;
+        if (this.matchKeyword('IF')) {
+            this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
+            this.consumeKeyword('EXISTS', "Expected 'EXISTS' after 'IF NOT'.");
+            ifNotExists = true;
+        }
+        const index = this.tableIdentifier();
+        this.consumeKeyword('ON', "Expected 'ON' after index name.");
+        const table = this.tableIdentifier();
+        this.consume(TokenType.LPAREN, "Expected '(' before indexed columns.");
+        const columns = this.indexedColumnList();
+        this.consume(TokenType.RPAREN, "Expected ')' after indexed columns.");
+        let where;
+        if (this.matchKeyword('WHERE')) {
+            where = this.expression();
+        }
+        return {
+            type: 'createIndex',
+            index,
+            table,
+            ifNotExists,
+            columns,
+            where,
+            isUnique,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse CREATE VIEW statement
+     * @returns AST for CREATE VIEW
+     */
+    createViewStatement(startToken, withClause) {
+        let isTemporary = false;
+        if (this.peekKeyword('TEMP') || this.peekKeyword('TEMPORARY')) {
+            isTemporary = true;
+            this.advance();
+        }
+        let ifNotExists = false;
+        if (this.matchKeyword('IF')) {
+            this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
+            this.consumeKeyword('EXISTS', "Expected 'EXISTS' after 'IF NOT'.");
+            ifNotExists = true;
+        }
+        const view = this.tableIdentifier();
+        let columns;
+        if (this.check(TokenType.LPAREN)) {
+            this.consume(TokenType.LPAREN, "Expected '(' to start view column list.");
+            columns = [];
+            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in view column list."));
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after view column list.");
+        }
+        this.consumeKeyword('AS', "Expected 'AS' before SELECT statement for CREATE VIEW.");
+        const selectStartToken = this.consume(TokenType.SELECT, "Expected 'SELECT' after 'AS' in CREATE VIEW.");
+        const select = this.selectStatement(selectStartToken, withClause);
+        return {
+            type: 'createView',
+            view,
+            ifNotExists,
+            columns,
+            select,
+            isTemporary,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse DROP statement
+     * @returns AST for DROP statement
+     */
+    dropStatement(startToken, _withClause) {
+        let objectType;
+        if (this.peekKeyword('TABLE')) {
+            this.consumeKeyword('TABLE', "Expected TABLE after DROP.");
+            objectType = 'table';
+        }
+        else if (this.peekKeyword('VIEW')) {
+            this.consumeKeyword('VIEW', "Expected VIEW after DROP.");
+            objectType = 'view';
+        }
+        else if (this.peekKeyword('INDEX')) {
+            this.consumeKeyword('INDEX', "Expected INDEX after DROP.");
+            objectType = 'index';
+        }
+        else {
+            throw this.error(this.peek(), "Expected TABLE, VIEW, or INDEX after DROP.");
+        }
+        let ifExists = false;
+        if (this.matchKeyword('IF')) {
+            this.consumeKeyword('EXISTS', "Expected 'EXISTS' after 'IF'.");
+            ifExists = true;
+        }
+        const name = this.tableIdentifier();
+        return {
+            type: 'drop',
+            objectType,
+            name,
+            ifExists,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse ALTER TABLE statement
+     * @returns AST for ALTER TABLE statement
+     */
+    alterTableStatement(startToken, _withClause) {
+        this.consumeKeyword('TABLE', "Expected 'TABLE' after ALTER.");
+        const table = this.tableIdentifier();
+        let action;
+        if (this.peekKeyword('RENAME')) {
+            this.consumeKeyword('RENAME', "Expected RENAME.");
+            if (this.matchKeyword('COLUMN')) {
+                const oldName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected old column name after RENAME COLUMN.");
+                this.consumeKeyword('TO', "Expected 'TO' after old column name.");
+                const newName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected new column name after TO.");
+                action = { type: 'renameColumn', oldName, newName };
+            }
+            else {
+                this.consumeKeyword('TO', "Expected 'TO' after RENAME.");
+                const newName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected new table name after RENAME TO.");
+                action = { type: 'renameTable', newName };
+            }
+        }
+        else if (this.peekKeyword('ADD')) {
+            this.consumeKeyword('ADD', "Expected ADD.");
+            if (this.peekKeyword('CONSTRAINT')) {
+                // ADD CONSTRAINT ... - let tableConstraint parse everything including CONSTRAINT keyword
+                const constraint = this.tableConstraint();
+                action = { type: 'addConstraint', constraint };
+            }
+            else {
+                // ADD [COLUMN] column_def
+                this.matchKeyword('COLUMN');
+                const column = this.columnDefinition();
+                action = { type: 'addColumn', column };
+            }
+        }
+        else if (this.peekKeyword('DROP')) {
+            this.consumeKeyword('DROP', "Expected DROP.");
+            this.matchKeyword('COLUMN');
+            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name after DROP COLUMN.");
+            action = { type: 'dropColumn', name };
+        }
+        else {
+            throw this.error(this.peek(), "Expected RENAME, ADD, or DROP after table name in ALTER TABLE.");
+        }
+        return {
+            type: 'alterTable',
+            table,
+            action,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse BEGIN statement
+     * @returns AST for BEGIN statement
+     */
+    beginStatement(startToken, _withClause) {
+        let mode;
+        if (this.peekKeyword('DEFERRED')) {
+            this.advance();
+            mode = 'deferred';
+        }
+        else if (this.peekKeyword('IMMEDIATE')) {
+            this.advance();
+            mode = 'immediate';
+        }
+        else if (this.peekKeyword('EXCLUSIVE')) {
+            this.advance();
+            mode = 'exclusive';
+        }
+        this.matchKeyword('TRANSACTION');
+        return { type: 'begin', mode, loc: _createLoc(startToken, this.previous()) };
+    }
+    /**
+     * Parse COMMIT statement
+     * @returns AST for COMMIT statement
+     */
+    commitStatement(startToken, _withClause) {
+        this.matchKeyword('TRANSACTION');
+        return { type: 'commit', loc: _createLoc(startToken, this.previous()) };
+    }
+    /**
+     * Parse ROLLBACK statement
+     * @returns AST for ROLLBACK statement
+     */
+    rollbackStatement(startToken, _withClause) {
+        this.matchKeyword('TRANSACTION');
+        let savepoint;
+        if (this.matchKeyword('TO')) {
+            this.matchKeyword('SAVEPOINT');
+            if (!this.check(TokenType.IDENTIFIER)) {
+                throw this.error(this.peek(), "Expected savepoint name after ROLLBACK TO.");
+            }
+            savepoint = this.advance().lexeme;
+        }
+        return { type: 'rollback', savepoint, loc: _createLoc(startToken, this.previous()) };
+    }
+    /**
+     * Parse SAVEPOINT statement
+     * @returns AST for SAVEPOINT statement
+     */
+    savepointStatement(startToken, _withClause) {
+        const name = this.consumeIdentifier("Expected savepoint name after SAVEPOINT.");
+        return { type: 'savepoint', name, loc: _createLoc(startToken, this.previous()) };
+    }
+    /**
+     * Parse RELEASE statement
+     * @returns AST for RELEASE statement
+     */
+    releaseStatement(startToken, _withClause) {
+        this.matchKeyword('SAVEPOINT');
+        const name = this.consumeIdentifier("Expected savepoint name after RELEASE [SAVEPOINT].");
+        return { type: 'release', savepoint: name, loc: _createLoc(startToken, this.previous()) };
+    }
+    /**
+     * Parse PRAGMA statement
+     * @returns AST for PRAGMA statement
+     */
+    pragmaStatement(startToken, _withClause) {
+        const nameValue = this.nameValueItem("pragma");
+        return { type: 'pragma', ...nameValue, loc: _createLoc(startToken, this.previous()) };
+    }
+    nameValueItem(context) {
+        const name = this.consumeIdentifier(`Expected ${context} name.`);
+        let value;
+        if (this.match(TokenType.EQUAL)) {
+            if (this.check(TokenType.IDENTIFIER)) {
+                value = { type: 'identifier', name: this.advance().lexeme };
+            }
+            else if (this.match(TokenType.STRING, TokenType.INTEGER, TokenType.FLOAT, TokenType.NULL, TokenType.TRUE, TokenType.FALSE)) {
+                const token = this.previous();
+                let literal_value;
+                if (token.type === TokenType.NULL) {
+                    literal_value = null;
+                }
+                else if (token.type === TokenType.TRUE) {
+                    literal_value = 1;
+                }
+                else if (token.type === TokenType.FALSE) {
+                    literal_value = 0;
+                }
+                else {
+                    literal_value = token.literal;
+                }
+                value = { type: 'literal', value: literal_value };
+            }
+            else if (this.match(TokenType.MINUS)) {
+                if (this.check(TokenType.INTEGER) || this.check(TokenType.FLOAT)) {
+                    const token = this.advance();
+                    value = { type: 'literal', value: -token.literal };
+                }
+                else {
+                    throw this.error(this.peek(), "Expected number after '-'.");
+                }
+            }
+            else {
+                throw this.error(this.peek(), `Expected ${context} value (identifier, string, number, or NULL).`);
+            }
+        }
+        // If no '=' is found, value remains undefined (reading mode)
+        return { name: name.toLowerCase(), value };
+    }
+    // --- Supporting Clause / Definition Parsers ---
+    /** @internal Parses a comma-separated list of indexed columns */
+    indexedColumnList() {
+        const columns = [];
+        do {
+            columns.push(this.indexedColumn());
+        } while (this.match(TokenType.COMMA));
+        return columns;
+    }
+    /** @internal Parses a single indexed column definition */
+    indexedColumn() {
+        const expr = this.expression();
+        let name;
+        if (expr.type === 'column' && !expr.table && !expr.schema) {
+            name = expr.name;
+        }
+        let direction;
+        if (this.match(TokenType.ASC)) {
+            direction = 'asc';
+        }
+        else if (this.match(TokenType.DESC)) {
+            direction = 'desc';
+        }
+        if (name) {
+            return { name, direction };
+        }
+        else {
+            return { expr, direction };
+        }
+    }
+    consumeIdentifier(errorMessageOrKeywords, errorMessage) {
+        if (typeof errorMessageOrKeywords === 'string') {
+            // Single parameter version - no contextual keywords
+            return this.consumeIdentifierOrContextualKeyword([], errorMessageOrKeywords);
+        }
+        else {
+            // Two parameter version - with contextual keywords
+            return this.consumeIdentifierOrContextualKeyword(errorMessageOrKeywords, errorMessage);
+        }
+    }
+    /**
+     * @internal Helper to consume an IDENTIFIER token or specified contextual keywords
+     * @param availableKeywords Array of keyword strings that can be used as identifiers in this context
+     * @param errorMessage Error message if no valid token is found
+     * @returns The lexeme of the consumed token
+     */
+    consumeIdentifierOrContextualKeyword(availableKeywords, errorMessage) {
+        const token = this.peek();
+        // First check for regular identifier
+        if (this.check(TokenType.IDENTIFIER)) {
+            return this.advance().lexeme;
+        }
+        // Then check for available contextual keywords
+        for (const keyword of availableKeywords) {
+            const keywordUpper = keyword.toUpperCase();
+            const expectedTokenType = TokenType[keywordUpper];
+            if (expectedTokenType && token.type === expectedTokenType) {
+                // This keyword token is available as an identifier in this context
+                return this.advance().lexeme;
+            }
+        }
+        throw this.error(this.peek(), errorMessage);
+    }
+    /**
+     * @internal Helper to check if current token is an identifier or available contextual keyword
+     */
+    checkIdentifierLike(availableKeywords = []) {
+        if (this.check(TokenType.IDENTIFIER)) {
+            return true;
+        }
+        return this.isContextualKeywordAvailable(availableKeywords);
+    }
+    /**
+     * @internal Helper to check if token at offset is an identifier or available contextual keyword
+     */
+    checkIdentifierLikeAt(offset, availableKeywords = []) {
+        if (this.checkNext(offset, TokenType.IDENTIFIER)) {
+            return true;
+        }
+        if (this.current + offset >= this.tokens.length)
+            return false;
+        const token = this.tokens[this.current + offset];
+        for (const keyword of availableKeywords) {
+            const keywordUpper = keyword.toUpperCase();
+            const expectedTokenType = TokenType[keywordUpper];
+            if (expectedTokenType && token.type === expectedTokenType) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * @internal Helper to check if any of the specified contextual keywords are available at current position
+     */
+    isContextualKeywordAvailable(availableKeywords) {
+        const token = this.peek();
+        for (const keyword of availableKeywords) {
+            const keywordUpper = keyword.toUpperCase();
+            const expectedTokenType = TokenType[keywordUpper];
+            if (expectedTokenType && token.type === expectedTokenType) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // --- Stubs for required helpers (implement fully for CREATE TABLE) ---
+    /** @internal Parses a column definition */
+    columnDefinition() {
+        const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name.");
+        let dataType;
+        if (this.check(TokenType.IDENTIFIER)) {
+            dataType = this.advance().lexeme;
+            if (this.match(TokenType.LPAREN)) {
+                dataType += '(';
+                let parenLevel = 1;
+                while (parenLevel > 0 && !this.isAtEnd()) {
+                    const token = this.peek();
+                    if (token.type === TokenType.LPAREN)
+                        parenLevel++;
+                    if (token.type === TokenType.RPAREN)
+                        parenLevel--;
+                    if (parenLevel > 0) {
+                        dataType += this.advance().lexeme;
+                    }
+                }
+                dataType += ')';
+                this.consume(TokenType.RPAREN, "Expected ')' after type parameters.");
+            }
+        }
+        const constraints = this.columnConstraintList();
+        return { name, dataType, constraints };
+    }
+    /** @internal Parses column constraints */
+    columnConstraintList() {
+        const constraints = [];
+        while (this.isColumnConstraintStart()) {
+            constraints.push(this.columnConstraint());
+        }
+        return constraints;
+    }
+    /** @internal Checks if the current token can start a column constraint */
+    isColumnConstraintStart() {
+        return this.check(TokenType.CONSTRAINT) ||
+            this.check(TokenType.PRIMARY) ||
+            this.check(TokenType.NOT) ||
+            this.check(TokenType.NULL) ||
+            this.check(TokenType.UNIQUE) ||
+            this.check(TokenType.CHECK) ||
+            this.check(TokenType.DEFAULT) ||
+            this.check(TokenType.COLLATE) ||
+            this.check(TokenType.REFERENCES) ||
+            this.check(TokenType.GENERATED);
+    }
+    /** @internal Parses a single column constraint */
+    columnConstraint() {
+        let name;
+        const startToken = this.peek(); // Capture start token
+        let endToken = startToken; // Initialize end token
+        if (this.match(TokenType.CONSTRAINT)) {
+            name = this.consumeIdentifier("Expected constraint name after CONSTRAINT.");
+            endToken = this.previous();
+        }
+        if (this.match(TokenType.PRIMARY)) {
+            this.consume(TokenType.KEY, "Expected KEY after PRIMARY.");
+            const direction = this.match(TokenType.ASC) ? 'asc' : this.match(TokenType.DESC) ? 'desc' : undefined;
+            if (direction)
+                endToken = this.previous();
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous(); // Update endToken if conflict clause was parsed
+            const autoincrement = this.match(TokenType.AUTOINCREMENT);
+            if (autoincrement)
+                endToken = this.previous();
+            return { type: 'primaryKey', name, onConflict, autoincrement, direction, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.NOT)) {
+            this.consume(TokenType.NULL, "Expected NULL after NOT.");
+            endToken = this.previous();
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous(); // Update endToken if conflict clause was parsed
+            return { type: 'notNull', name, onConflict, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.NULL)) {
+            endToken = this.previous();
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous(); // Update endToken if conflict clause was parsed
+            return { type: 'null', name, onConflict, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.UNIQUE)) {
+            endToken = this.previous();
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous(); // Update endToken if conflict clause was parsed
+            return { type: 'unique', name, onConflict, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.CHECK)) {
+            // --- Parse optional ON clause before parentheses --- //
+            let operations;
+            if (this.matchKeyword('ON')) {
+                operations = this.parseRowOpList();
+            }
+            // --- End Parse ON clause --- //
+            this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
+            const expr = this.expression();
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
+            return { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.DEFAULT)) {
+            const expr = this.expression();
+            endToken = this.previous();
+            return { type: 'default', name, expr, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.COLLATE)) {
+            if (!this.check(TokenType.IDENTIFIER)) {
+                throw this.error(this.peek(), "Expected collation name after COLLATE.");
+            }
+            const collation = this.advance().lexeme;
+            endToken = this.previous();
+            return { type: 'collate', name, collation, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.REFERENCES)) {
+            const fkClause = this.foreignKeyClause();
+            endToken = this.previous(); // End token is end of FK clause
+            return { type: 'foreignKey', name, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.GENERATED)) {
+            this.consume(TokenType.ALWAYS, "Expected ALWAYS after GENERATED.");
+            this.consume(TokenType.AS, "Expected AS after GENERATED ALWAYS.");
+            this.consume(TokenType.LPAREN, "Expected '(' after AS.");
+            const expr = this.expression();
+            this.consume(TokenType.RPAREN, "Expected ')' after generated expression.");
+            endToken = this.previous();
+            let stored = false;
+            if (this.match(TokenType.STORED)) {
+                stored = true;
+                endToken = this.previous();
+            }
+            else if (this.match(TokenType.VIRTUAL)) {
+                endToken = this.previous();
+            }
+            return { type: 'generated', name, generated: { expr, stored }, loc: _createLoc(startToken, endToken) };
+        }
+        throw this.error(this.peek(), "Expected column constraint type (PRIMARY KEY, NOT NULL, UNIQUE, CHECK, DEFAULT, COLLATE, REFERENCES, GENERATED).");
+    }
+    /** @internal Parses a table constraint */
+    tableConstraint() {
+        let name;
+        const startToken = this.peek(); // Capture start token
+        let endToken = startToken; // Initialize end token
+        if (this.match(TokenType.CONSTRAINT)) {
+            name = this.consumeIdentifier("Expected constraint name after CONSTRAINT.");
+            endToken = this.previous();
+        }
+        if (this.match(TokenType.PRIMARY)) {
+            this.consume(TokenType.KEY, "Expected KEY after PRIMARY.");
+            this.consume(TokenType.LPAREN, "Expected '(' before PRIMARY KEY columns.");
+            // Handle empty PRIMARY KEY () for singleton tables (Third Manifesto feature)
+            let columns = [];
+            if (!this.check(TokenType.RPAREN)) {
+                columns = this.identifierListWithDirection();
+            }
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after PRIMARY KEY columns.");
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous();
+            return { type: 'primaryKey', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.UNIQUE)) {
+            this.consume(TokenType.LPAREN, "Expected '(' before UNIQUE columns.");
+            const columnsSimple = this.identifierList();
+            const columns = columnsSimple.map(name => ({ name }));
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after UNIQUE columns.");
+            const onConflict = this.parseConflictClause();
+            if (onConflict)
+                endToken = this.previous();
+            return { type: 'unique', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.CHECK)) {
+            // --- Parse optional ON clause before parentheses --- //
+            let operations;
+            if (this.matchKeyword('ON')) {
+                operations = this.parseRowOpList();
+            }
+            // --- End Parse ON clause --- //
+            this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
+            const expr = this.expression();
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
+            return { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
+        }
+        else if (this.match(TokenType.FOREIGN)) {
+            this.consume(TokenType.KEY, "Expected KEY after FOREIGN.");
+            this.consume(TokenType.LPAREN, "Expected '(' before FOREIGN KEY columns.");
+            const columns = this.identifierList().map(name => ({ name }));
+            this.consume(TokenType.RPAREN, "Expected ')' after FOREIGN KEY columns.");
+            const fkClause = this.foreignKeyClause();
+            endToken = this.previous(); // End token is end of FK clause
+            return { type: 'foreignKey', name, columns, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
+        }
+        throw this.error(this.peek(), "Expected table constraint type (PRIMARY KEY, UNIQUE, CHECK, FOREIGN KEY).");
+    }
+    /** @internal Parses a foreign key clause */
+    foreignKeyClause() {
+        this.consume(TokenType.REFERENCES, "Expected REFERENCES for foreign key.");
+        const table = this.consumeIdentifier("Expected foreign table name.");
+        let columns;
+        if (this.match(TokenType.LPAREN)) {
+            columns = this.identifierList();
+            this.consume(TokenType.RPAREN, "Expected ')' after foreign columns.");
+        }
+        let onDelete;
+        let onUpdate;
+        let deferrable;
+        let initiallyDeferred;
+        while (this.check(TokenType.ON) || this.check(TokenType.DEFERRABLE) || this.check(TokenType.NOT)) {
+            if (this.match(TokenType.ON)) {
+                if (this.match(TokenType.DELETE)) {
+                    onDelete = this.parseForeignKeyAction();
+                }
+                else if (this.match(TokenType.UPDATE)) {
+                    onUpdate = this.parseForeignKeyAction();
+                }
+                else {
+                    throw this.error(this.peek(), "Expected DELETE or UPDATE after ON.");
+                }
+            }
+            else if (this.match(TokenType.DEFERRABLE)) {
+                deferrable = true;
+                if (this.match(TokenType.INITIALLY)) {
+                    if (this.match(TokenType.DEFERRED)) {
+                        initiallyDeferred = true;
+                    }
+                    else if (this.match(TokenType.IMMEDIATE)) {
+                        initiallyDeferred = false;
+                    }
+                    else {
+                        throw this.error(this.peek(), "Expected DEFERRED or IMMEDIATE after INITIALLY.");
+                    }
+                }
+            }
+            else if (this.match(TokenType.NOT)) {
+                this.consume(TokenType.DEFERRABLE, "Expected DEFERRABLE after NOT.");
+                deferrable = false;
+                if (this.match(TokenType.INITIALLY)) {
+                    if (this.match(TokenType.DEFERRED)) {
+                        initiallyDeferred = true;
+                    }
+                    else if (this.match(TokenType.IMMEDIATE)) {
+                        initiallyDeferred = false;
+                    }
+                    else {
+                        throw this.error(this.peek(), "Expected DEFERRED or IMMEDIATE after INITIALLY.");
+                    }
+                }
+            }
+            else {
+                break;
+            }
+        }
+        return { table, columns, onDelete, onUpdate, deferrable, initiallyDeferred };
+    }
+    /** @internal Parses the ON CONFLICT clause */
+    parseConflictClause() {
+        if (this.match(TokenType.ON)) {
+            this.consume(TokenType.CONFLICT, "Expected CONFLICT after ON.");
+            if (this.match(TokenType.ROLLBACK))
+                return ConflictResolution.ROLLBACK;
+            if (this.match(TokenType.ABORT))
+                return ConflictResolution.ABORT;
+            if (this.match(TokenType.FAIL))
+                return ConflictResolution.FAIL;
+            if (this.match(TokenType.IGNORE))
+                return ConflictResolution.IGNORE;
+            if (this.match(TokenType.REPLACE))
+                return ConflictResolution.REPLACE;
+            throw this.error(this.peek(), "Expected conflict resolution algorithm (ROLLBACK, ABORT, FAIL, IGNORE, REPLACE).");
+        }
+        return undefined;
+    }
+    /** @internal Parses the foreign key action */
+    parseForeignKeyAction() {
+        if (this.match(TokenType.SET)) {
+            if (this.match(TokenType.NULL))
+                return 'setNull';
+            if (this.match(TokenType.DEFAULT))
+                return 'setDefault';
+            throw this.error(this.peek(), "Expected NULL or DEFAULT after SET.");
+        }
+        else if (this.match(TokenType.CASCADE)) {
+            return 'cascade';
+        }
+        else if (this.match(TokenType.RESTRICT)) {
+            return 'restrict';
+        }
+        else if (this.match(TokenType.NO)) {
+            this.consume(TokenType.ACTION, "Expected ACTION after NO.");
+            return 'noAction';
+        }
+        throw this.error(this.peek(), "Expected foreign key action (SET NULL, SET DEFAULT, CASCADE, RESTRICT, NO ACTION).");
+    }
+    /** @internal Parses a comma-separated list of identifiers, optionally with ASC/DESC */
+    identifierList() {
+        const identifiers = [];
+        do {
+            identifiers.push(this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected identifier in list."));
+        } while (this.match(TokenType.COMMA));
+        return identifiers;
+    }
+    /** @internal Parses a comma-separated list of identifiers, optionally with ASC/DESC */
+    identifierListWithDirection() {
+        const identifiers = [];
+        do {
+            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected identifier in list.");
+            const direction = this.match(TokenType.ASC) ? 'asc' : this.match(TokenType.DESC) ? 'desc' : undefined;
+            identifiers.push({ name, direction });
+        } while (this.match(TokenType.COMMA));
+        return identifiers;
+    }
+    // --- Helper method to peek keywords case-insensitively ---
+    peekKeyword(keyword) {
+        if (this.isAtEnd())
+            return false;
+        const token = this.peek();
+        // The keyword lookup string should be uppercase to match TokenType enum keys (e.g., TokenType.SELECT)
+        const keywordKey = keyword.toUpperCase();
+        const expectedTokenType = TokenType[keywordKey];
+        // Check if the current token's type is the expected specific keyword TokenType.
+        // This assumes the lexer has already correctly typed true keywords.
+        if (expectedTokenType !== undefined && token.type === expectedTokenType) {
+            return true;
+        }
+        // Fallback: if the token is a generic IDENTIFIER, check if its lexeme matches the keyword.
+        // This handles contextual keywords like FIRST, LAST that aren't reserved keywords.
+        if (token.type === TokenType.IDENTIFIER && token.lexeme.toUpperCase() === keywordKey) {
+            return true;
+        }
+        return false;
+    }
+    // --- Helper method to match keywords case-insensitively ---
+    matchKeyword(keyword) {
+        if (this.isAtEnd())
+            return false;
+        if (this.peekKeyword(keyword)) {
+            this.advance();
+            return true;
+        }
+        return false;
+    }
+    // --- Helper method to consume keywords case-insensitively ---
+    consumeKeyword(keyword, message) {
+        if (this.peekKeyword(keyword)) {
+            return this.advance();
+        }
+        throw this.error(this.peek(), message);
+    }
+    /** Parses the list of operations for CHECK ON */
+    parseRowOpList() {
+        const operations = [];
+        // Parse operations in a comma-separated list
+        do {
+            if (this.match(TokenType.INSERT)) {
+                operations.push('insert');
+            }
+            else if (this.match(TokenType.UPDATE)) {
+                operations.push('update');
+            }
+            else if (this.match(TokenType.DELETE)) {
+                operations.push('delete');
+            }
+            else {
+                throw this.error(this.peek(), "Expected INSERT, UPDATE, or DELETE after ON.");
+            }
+        } while (this.match(TokenType.COMMA));
+        // Optional: Check for duplicates? The design allows them but ignores them.
+        return operations;
+    }
+    /**
+     * Parses a CASE expression
+     * CASE [base_expr] WHEN cond THEN result ... [ELSE else_result] END
+     * CASE WHEN cond THEN result ... [ELSE else_result] END
+     */
+    parseCaseExpression(startToken) {
+        let baseExpr;
+        const whenThenClauses = [];
+        let elseExpr;
+        let endToken = startToken; // Initialize with CASE token
+        // Check if it's CASE expr WHEN ... or CASE WHEN ...
+        if (!this.peekKeyword('WHEN')) { // Changed from checkKeyword
+            baseExpr = this.expression();
+        }
+        while (this.matchKeyword('WHEN')) {
+            const whenCondition = this.expression();
+            this.consumeKeyword('THEN', "Expected 'THEN' after WHEN condition in CASE expression.");
+            const thenResult = this.expression();
+            whenThenClauses.push({ when: whenCondition, then: thenResult });
+            endToken = this.previous(); // Update endToken to the end of the THEN expression
+        }
+        if (whenThenClauses.length === 0) {
+            throw this.error(this.peek(), "CASE expression must have at least one WHEN clause.");
+        }
+        if (this.matchKeyword('ELSE')) {
+            elseExpr = this.expression();
+            endToken = this.previous(); // Update endToken to the end of the ELSE expression
+        }
+        endToken = this.consumeKeyword('END', "Expected 'END' to terminate CASE expression.");
+        return {
+            type: 'case',
+            baseExpr,
+            whenThenClauses,
+            elseExpr,
+            loc: _createLoc(startToken, endToken),
+        };
+    }
+    // Helper to check if a token lexeme is a common type name keyword for CAST
+    isTypeNameKeyword(lexeme) {
+        const typeKeywords = ['TEXT', 'INTEGER', 'REAL', 'BLOB', 'NUMERIC', 'VARCHAR', 'CHAR', 'DATE', 'DATETIME', 'BOOLEAN', 'INT'];
+        return typeKeywords.includes(lexeme.toUpperCase());
+    }
+    statementSupportsWithClause(statement) {
+        return statement.type === 'select' ||
+            statement.type === 'insert' ||
+            statement.type === 'update' ||
+            statement.type === 'delete';
+    }
+}
+//# sourceMappingURL=parser.js.map