rawsql-ts 0.11.43-beta → 0.12.0

package/dist/esm/src/transformers/SqlPrinter.js

@@ -1,6 +1,10 @@
 import { SqlPrintTokenType, SqlPrintTokenContainerType } from "../models/SqlPrintToken";
 import { LinePrinter } from "./LinePrinter";
 import { resolveIndentCharOption, resolveNewlineOption } from "./FormatOptionResolver";
+import { OnelineFormattingHelper, } from "./OnelineFormattingHelper";
+const CREATE_TABLE_SINGLE_PAREN_KEYWORDS = new Set(['unique', 'check', 'key', 'index']);
+const CREATE_TABLE_MULTI_PAREN_KEYWORDS = new Set(['primary key', 'foreign key', 'unique key']);
+const CREATE_TABLE_PAREN_KEYWORDS_WITH_IDENTIFIER = new Set(['references']);
 /**
  * SqlPrinter formats a SqlPrintToken tree into a SQL string with flexible style options.
  *
@@ -26,9 +30,11 @@ export class SqlPrinter {
      * @param options Optional style settings for pretty printing
      */
     constructor(options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
         /** Track whether we are currently inside a WITH clause for full-oneline formatting */
         this.insideWithClause = false;
+        /** Tracks nesting depth while formatting MERGE WHEN predicate segments */
+        this.mergeWhenPredicateDepth = 0;
         /** Pending line comment that needs a forced newline before next token */
         this.pendingLineCommentBreak = null;
         /** Accumulates lines when reconstructing multi-line block comments inside CommentBlocks */
@@ -47,19 +53,32 @@ export class SqlPrinter {
         this.andBreak = (_e = options === null || options === void 0 ? void 0 : options.andBreak) !== null && _e !== void 0 ? _e : 'none';
         this.orBreak = (_f = options === null || options === void 0 ? void 0 : options.orBreak) !== null && _f !== void 0 ? _f : 'none';
         this.keywordCase = (_g = options === null || options === void 0 ? void 0 : options.keywordCase) !== null && _g !== void 0 ? _g : 'none';
-        this.exportComment = (_h = options === null || options === void 0 ? void 0 : options.exportComment) !== null && _h !== void 0 ? _h : false;
-        this.withClauseStyle = (_j = options === null || options === void 0 ? void 0 : options.withClauseStyle) !== null && _j !== void 0 ? _j : 'standard';
-        this.commentStyle = (_k = options === null || options === void 0 ? void 0 : options.commentStyle) !== null && _k !== void 0 ? _k : 'block';
-        this.parenthesesOneLine = (_l = options === null || options === void 0 ? void 0 : options.parenthesesOneLine) !== null && _l !== void 0 ? _l : false;
-        this.betweenOneLine = (_m = options === null || options === void 0 ? void 0 : options.betweenOneLine) !== null && _m !== void 0 ? _m : false;
-        this.valuesOneLine = (_o = options === null || options === void 0 ? void 0 : options.valuesOneLine) !== null && _o !== void 0 ? _o : false;
-        this.joinOneLine = (_p = options === null || options === void 0 ? void 0 : options.joinOneLine) !== null && _p !== void 0 ? _p : false;
-        this.caseOneLine = (_q = options === null || options === void 0 ? void 0 : options.caseOneLine) !== null && _q !== void 0 ? _q : false;
-        this.subqueryOneLine = (_r = options === null || options === void 0 ? void 0 : options.subqueryOneLine) !== null && _r !== void 0 ? _r : false;
-        this.indentNestedParentheses = (_s = options === null || options === void 0 ? void 0 : options.indentNestedParentheses) !== null && _s !== void 0 ? _s : false;
+        this.commentExportMode = this.resolveCommentExportMode(options === null || options === void 0 ? void 0 : options.exportComment);
+        this.withClauseStyle = (_h = options === null || options === void 0 ? void 0 : options.withClauseStyle) !== null && _h !== void 0 ? _h : 'standard';
+        this.commentStyle = (_j = options === null || options === void 0 ? void 0 : options.commentStyle) !== null && _j !== void 0 ? _j : 'block';
+        this.parenthesesOneLine = (_k = options === null || options === void 0 ? void 0 : options.parenthesesOneLine) !== null && _k !== void 0 ? _k : false;
+        this.betweenOneLine = (_l = options === null || options === void 0 ? void 0 : options.betweenOneLine) !== null && _l !== void 0 ? _l : false;
+        this.valuesOneLine = (_m = options === null || options === void 0 ? void 0 : options.valuesOneLine) !== null && _m !== void 0 ? _m : false;
+        this.joinOneLine = (_o = options === null || options === void 0 ? void 0 : options.joinOneLine) !== null && _o !== void 0 ? _o : false;
+        this.caseOneLine = (_p = options === null || options === void 0 ? void 0 : options.caseOneLine) !== null && _p !== void 0 ? _p : false;
+        this.subqueryOneLine = (_q = options === null || options === void 0 ? void 0 : options.subqueryOneLine) !== null && _q !== void 0 ? _q : false;
+        this.indentNestedParentheses = (_r = options === null || options === void 0 ? void 0 : options.indentNestedParentheses) !== null && _r !== void 0 ? _r : false;
+        this.insertColumnsOneLine = (_s = options === null || options === void 0 ? void 0 : options.insertColumnsOneLine) !== null && _s !== void 0 ? _s : false;
+        this.whenOneLine = (_t = options === null || options === void 0 ? void 0 : options.whenOneLine) !== null && _t !== void 0 ? _t : false;
+        const onelineOptions = {
+            parenthesesOneLine: this.parenthesesOneLine,
+            betweenOneLine: this.betweenOneLine,
+            valuesOneLine: this.valuesOneLine,
+            joinOneLine: this.joinOneLine,
+            caseOneLine: this.caseOneLine,
+            subqueryOneLine: this.subqueryOneLine,
+            insertColumnsOneLine: this.insertColumnsOneLine,
+            withClauseStyle: this.withClauseStyle,
+        };
+        this.onelineHelper = new OnelineFormattingHelper(onelineOptions);
         this.linePrinter = new LinePrinter(this.indentChar, this.indentSize, this.newline, this.commaBreak);
         // Initialize
-        this.indentIncrementContainers = new Set((_t = options === null || options === void 0 ? void 0 : options.indentIncrementContainerTypes) !== null && _t !== void 0 ? _t : [
+        this.indentIncrementContainers = new Set((_u = options === null || options === void 0 ? void 0 : options.indentIncrementContainerTypes) !== null && _u !== void 0 ? _u : [
             SqlPrintTokenContainerType.SelectClause,
             SqlPrintTokenContainerType.FromClause,
             SqlPrintTokenContainerType.WhereClause,
@@ -79,7 +98,11 @@ export class SqlPrinter {
             SqlPrintTokenContainerType.CaseThenValue,
             SqlPrintTokenContainerType.ElseClause,
             SqlPrintTokenContainerType.CaseElseValue,
-            SqlPrintTokenContainerType.SimpleSelectQuery
+            SqlPrintTokenContainerType.SimpleSelectQuery,
+            SqlPrintTokenContainerType.CreateTableDefinition,
+            SqlPrintTokenContainerType.AlterTableStatement,
+            SqlPrintTokenContainerType.IndexColumnList,
+            SqlPrintTokenContainerType.SetClause
             // Note: CommentBlock is intentionally excluded from indentIncrementContainers
             // because it serves as a grouping mechanism without affecting indentation.
             // CaseExpression, SwitchCaseArgument, CaseKeyValuePair, and ElseClause
@@ -108,7 +131,42 @@ export class SqlPrinter {
         this.appendToken(token, level, undefined, 0, false);
         return this.linePrinter.print();
     }
-    appendToken(token, level, parentContainerType, caseContextDepth = 0, indentParentActive = false) {
+    // Resolve legacy boolean values into explicit comment export modes.
+    resolveCommentExportMode(option) {
+        if (option === undefined) {
+            return 'none';
+        }
+        if (option === true) {
+            return 'full';
+        }
+        if (option === false) {
+            return 'none';
+        }
+        return option;
+    }
+    // Determine whether the current mode allows emitting inline comments.
+    rendersInlineComments() {
+        return this.commentExportMode === 'full';
+    }
+    // Decide if a comment block or token should be rendered given its context.
+    shouldRenderComment(token, context) {
+        if (context === null || context === void 0 ? void 0 : context.forceRender) {
+            return this.commentExportMode !== 'none';
+        }
+        switch (this.commentExportMode) {
+            case 'full':
+                return true;
+            case 'none':
+                return false;
+            case 'header-only':
+                return token.isHeaderComment === true;
+            case 'top-header-only':
+                return token.isHeaderComment === true && Boolean(context === null || context === void 0 ? void 0 : context.isTopLevelContainer);
+            default:
+                return false;
+        }
+    }
+    appendToken(token, level, parentContainerType, caseContextDepth = 0, indentParentActive = false, commentContext) {
         // Track WITH clause context for full-oneline formatting
         const wasInsideWithClause = this.insideWithClause;
         if (token.containerType === SqlPrintTokenContainerType.WithClause && this.withClauseStyle === 'full-oneline') {
@@ -117,6 +175,45 @@ export class SqlPrinter {
         if (this.shouldSkipToken(token)) {
             return;
         }
+        const containerIsTopLevel = parentContainerType === undefined;
+        let leadingCommentCount = 0;
+        // Collect leading comment blocks with context so we can respect the export mode.
+        const leadingCommentContexts = [];
+        if (token.innerTokens && token.innerTokens.length > 0) {
+            while (leadingCommentCount < token.innerTokens.length) {
+                const leadingCandidate = token.innerTokens[leadingCommentCount];
+                if (leadingCandidate.containerType !== SqlPrintTokenContainerType.CommentBlock) {
+                    break;
+                }
+                const context = {
+                    position: 'leading',
+                    isTopLevelContainer: containerIsTopLevel,
+                };
+                const shouldRender = this.shouldRenderComment(leadingCandidate, context);
+                leadingCommentContexts.push({ token: leadingCandidate, context, shouldRender });
+                leadingCommentCount++;
+            }
+        }
+        const hasRenderableLeadingComment = leadingCommentContexts.some(item => item.shouldRender);
+        const leadingCommentIndentLevel = hasRenderableLeadingComment
+            ? this.getLeadingCommentIndentLevel(parentContainerType, level)
+            : null;
+        if (hasRenderableLeadingComment
+            && !this.isOnelineMode()
+            && this.shouldAddNewlineBeforeLeadingComments(parentContainerType)) {
+            const currentLine = this.linePrinter.getCurrentLine();
+            if (currentLine.text.trim().length > 0) {
+                // Align the newline before leading comments with the intended comment indentation.
+                this.linePrinter.appendNewline(leadingCommentIndentLevel !== null && leadingCommentIndentLevel !== void 0 ? leadingCommentIndentLevel : level);
+            }
+        }
+        for (const leading of leadingCommentContexts) {
+            if (!leading.shouldRender) {
+                continue;
+            }
+            // Keep leading comment processing aligned with its computed indentation level.
+            this.appendToken(leading.token, leadingCommentIndentLevel !== null && leadingCommentIndentLevel !== void 0 ? leadingCommentIndentLevel : level, token.containerType, caseContextDepth, indentParentActive, leading.context);
+        }
         if (this.smartCommentBlockBuilder && token.containerType !== SqlPrintTokenContainerType.CommentBlock && token.type !== SqlPrintTokenType.commentNewline) {
             this.flushSmartCommentBlockBuilder();
         }
@@ -130,8 +227,17 @@ export class SqlPrinter {
                 return;
             }
         }
+        // Fallback context applies when the caller did not provide comment metadata.
+        const effectiveCommentContext = commentContext !== null && commentContext !== void 0 ? commentContext : {
+            position: 'inline',
+            isTopLevelContainer: containerIsTopLevel,
+        };
         if (token.containerType === SqlPrintTokenContainerType.CommentBlock) {
-            this.handleCommentBlockContainer(token, level);
+            if (!this.shouldRenderComment(token, effectiveCommentContext)) {
+                return;
+            }
+            const commentLevel = this.getCommentBaseIndentLevel(level, parentContainerType);
+            this.handleCommentBlockContainer(token, commentLevel, effectiveCommentContext);
             return;
         }
         const current = this.linePrinter.getCurrentLine();
@@ -146,7 +252,7 @@ export class SqlPrinter {
             this.handleCommaToken(token, level, parentContainerType);
         }
         else if (token.type === SqlPrintTokenType.parenthesis) {
-            this.handleParenthesisToken(token, level, indentParentActive);
+            this.handleParenthesisToken(token, level, indentParentActive, parentContainerType);
         }
         else if (token.type === SqlPrintTokenType.operator && token.text.toLowerCase() === 'and') {
             this.handleAndOperatorToken(token, level, parentContainerType, caseContextDepth);
@@ -154,34 +260,34 @@ export class SqlPrinter {
         else if (token.type === SqlPrintTokenType.operator && token.text.toLowerCase() === 'or') {
             this.handleOrOperatorToken(token, level, parentContainerType, caseContextDepth);
         }
-        else if (token.containerType === "JoinClause") {
+        else if (token.containerType === SqlPrintTokenContainerType.JoinClause) {
             this.handleJoinClauseToken(token, level);
         }
         else if (token.type === SqlPrintTokenType.comment) {
-            if (this.exportComment) {
-                this.printCommentToken(token.text, level, parentContainerType);
+            if (this.shouldRenderComment(token, effectiveCommentContext)) {
+                const commentLevel = this.getCommentBaseIndentLevel(level, parentContainerType);
+                this.printCommentToken(token.text, commentLevel, parentContainerType);
             }
         }
         else if (token.type === SqlPrintTokenType.space) {
             this.handleSpaceToken(token, parentContainerType);
         }
         else if (token.type === SqlPrintTokenType.commentNewline) {
-            this.handleCommentNewlineToken(token, level);
+            if (this.whenOneLine && parentContainerType === SqlPrintTokenContainerType.MergeWhenClause) {
+                return;
+            }
+            const commentLevel = this.getCommentBaseIndentLevel(level, parentContainerType);
+            this.handleCommentNewlineToken(token, commentLevel);
         }
         else if (token.containerType === SqlPrintTokenContainerType.CommonTable && this.withClauseStyle === 'cte-oneline') {
             this.handleCteOnelineToken(token, level);
             return; // Return early to avoid processing innerTokens
         }
-        else if ((token.containerType === SqlPrintTokenContainerType.ParenExpression && this.parenthesesOneLine && !shouldIndentNested) ||
-            (token.containerType === SqlPrintTokenContainerType.BetweenExpression && this.betweenOneLine) ||
-            (token.containerType === SqlPrintTokenContainerType.Values && this.valuesOneLine) ||
-            (token.containerType === SqlPrintTokenContainerType.JoinOnClause && this.joinOneLine) ||
-            (token.containerType === SqlPrintTokenContainerType.CaseExpression && this.caseOneLine) ||
-            (token.containerType === SqlPrintTokenContainerType.InlineQuery && this.subqueryOneLine)) {
+        else if (this.shouldFormatContainerAsOneline(token, shouldIndentNested)) {
             this.handleOnelineToken(token, level);
             return; // Return early to avoid processing innerTokens
         }
-        else {
+        else if (!this.tryAppendInsertClauseTokenText(token.text, parentContainerType)) {
             this.linePrinter.appendText(token.text);
         }
         // append keyword tokens(not indented)
@@ -195,7 +301,18 @@ export class SqlPrinter {
         let increasedIndent = false;
         const shouldIncreaseIndent = this.indentIncrementContainers.has(token.containerType) || shouldIndentNested;
         const delayIndentNewline = shouldIndentNested && token.containerType === SqlPrintTokenContainerType.ParenExpression;
-        if (!this.isOnelineMode() && shouldIncreaseIndent) {
+        const isAlterTableStatement = token.containerType === SqlPrintTokenContainerType.AlterTableStatement;
+        let deferAlterTableIndent = false;
+        const alignExplainChild = this.shouldAlignExplainStatementChild(parentContainerType, token.containerType);
+        if (alignExplainChild) {
+            // Keep EXPLAIN target statements flush left so they render like standalone statements.
+            if (!this.isOnelineMode() && current.text !== '') {
+                this.linePrinter.appendNewline(level);
+            }
+            innerLevel = level;
+            increasedIndent = false;
+        }
+        else if (!this.isOnelineMode() && shouldIncreaseIndent) {
             if (this.insideWithClause && this.withClauseStyle === 'full-oneline') {
                 // Keep everything on one line for full-oneline WITH clauses.
             }
@@ -204,15 +321,96 @@ export class SqlPrinter {
                 increasedIndent = true;
             }
             else if (current.text !== '') {
-                innerLevel = level + 1;
+                if (isAlterTableStatement) {
+                    // Delay the first line break so ALTER TABLE keeps the table name on the opening line.
+                    innerLevel = level + 1;
+                    increasedIndent = true;
+                    deferAlterTableIndent = true;
+                }
+                else {
+                    let targetIndentLevel = level + 1;
+                    if (token.containerType === SqlPrintTokenContainerType.SetClause &&
+                        parentContainerType === SqlPrintTokenContainerType.MergeUpdateAction) {
+                        targetIndentLevel = level + 2;
+                    }
+                    if (this.shouldAlignCreateTableSelect(token.containerType, parentContainerType)) {
+                        innerLevel = level;
+                        increasedIndent = false;
+                        this.linePrinter.appendNewline(level);
+                    }
+                    else {
+                        innerLevel = targetIndentLevel;
+                        increasedIndent = true;
+                        this.linePrinter.appendNewline(innerLevel);
+                    }
+                }
+            }
+            else if (token.containerType === SqlPrintTokenContainerType.SetClause) {
+                innerLevel = parentContainerType === SqlPrintTokenContainerType.MergeUpdateAction ? level + 2 : level + 1;
                 increasedIndent = true;
-                this.linePrinter.appendNewline(innerLevel);
+                current.level = innerLevel;
             }
         }
-        for (let i = 0; i < token.innerTokens.length; i++) {
+        const isMergeWhenClause = this.whenOneLine && token.containerType === SqlPrintTokenContainerType.MergeWhenClause;
+        let mergePredicateActive = isMergeWhenClause;
+        let alterTableTableRendered = false;
+        let alterTableIndentInserted = false;
+        for (let i = leadingCommentCount; i < token.innerTokens.length; i++) {
             const child = token.innerTokens[i];
+            const nextChild = token.innerTokens[i + 1];
+            const previousEntry = this.findPreviousSignificantToken(token.innerTokens, i);
+            const previousChild = previousEntry === null || previousEntry === void 0 ? void 0 : previousEntry.token;
+            const priorEntry = previousEntry ? this.findPreviousSignificantToken(token.innerTokens, previousEntry.index) : undefined;
+            const priorChild = priorEntry === null || priorEntry === void 0 ? void 0 : priorEntry.token;
+            const childIsAction = this.isMergeActionContainer(child);
+            const nextIsAction = this.isMergeActionContainer(nextChild);
+            const inMergePredicate = mergePredicateActive && !childIsAction;
+            if (isAlterTableStatement) {
+                if (child.containerType === SqlPrintTokenContainerType.QualifiedName) {
+                    // Track when the table name has been printed so we can defer indentation until after it.
+                    alterTableTableRendered = true;
+                }
+                else if (deferAlterTableIndent && alterTableTableRendered && !alterTableIndentInserted) {
+                    if (!this.isOnelineMode()) {
+                        this.linePrinter.appendNewline(innerLevel);
+                    }
+                    alterTableIndentInserted = true;
+                    deferAlterTableIndent = false;
+                    if (!this.isOnelineMode() && child.type === SqlPrintTokenType.space) {
+                        // Drop the space token because we already emitted a newline.
+                        continue;
+                    }
+                }
+            }
+            if (child.type === SqlPrintTokenType.space) {
+                if (this.shouldConvertSpaceToClauseBreak(token.containerType, nextChild)) {
+                    if (!this.isOnelineMode()) {
+                        // Use a dedicated indent resolver so clause breaks can shift indentation for nested blocks.
+                        const clauseBreakIndent = this.getClauseBreakIndentLevel(token.containerType, innerLevel);
+                        this.linePrinter.appendNewline(clauseBreakIndent);
+                    }
+                    if (isMergeWhenClause && nextIsAction) {
+                        mergePredicateActive = false;
+                    }
+                    continue;
+                }
+                this.handleSpaceToken(child, token.containerType, nextChild, previousChild, priorChild);
+                continue;
+            }
             const childIndentParentActive = token.containerType === SqlPrintTokenContainerType.ParenExpression ? shouldIndentNested : indentParentActive;
-            this.appendToken(child, innerLevel, token.containerType, nextCaseContextDepth, childIndentParentActive);
+            if (inMergePredicate) {
+                this.mergeWhenPredicateDepth++;
+            }
+            const childCommentContext = child.containerType === SqlPrintTokenContainerType.CommentBlock
+                ? { position: 'inline', isTopLevelContainer: containerIsTopLevel }
+                : undefined;
+            this.appendToken(child, innerLevel, token.containerType, nextCaseContextDepth, childIndentParentActive, childCommentContext);
+            if (inMergePredicate) {
+                this.mergeWhenPredicateDepth--;
+            }
+            if (childIsAction && isMergeWhenClause) {
+                mergePredicateActive = false;
+            }
         }
         if (this.smartCommentBlockBuilder && this.smartCommentBlockBuilder.mode === 'line') {
             this.flushSmartCommentBlockBuilder();
@@ -229,6 +427,21 @@ export class SqlPrinter {
             this.linePrinter.appendNewline(level);
         }
     }
+    shouldAlignExplainStatementChild(parentType, childType) {
+        if (parentType !== SqlPrintTokenContainerType.ExplainStatement) {
+            return false;
+        }
+        switch (childType) {
+            case SqlPrintTokenContainerType.SimpleSelectQuery:
+            case SqlPrintTokenContainerType.InsertQuery:
+            case SqlPrintTokenContainerType.UpdateQuery:
+            case SqlPrintTokenContainerType.DeleteQuery:
+            case SqlPrintTokenContainerType.MergeQuery:
+                return true;
+            default:
+                return false;
+        }
+    }
     isCaseContext(containerType) {
         switch (containerType) {
             case SqlPrintTokenContainerType.CaseExpression:
@@ -265,11 +478,13 @@ export class SqlPrinter {
     }
     handleKeywordToken(token, level, parentContainerType, caseContextDepth = 0) {
         const lower = token.text.toLowerCase();
-        if (lower === 'and' && this.andBreak !== 'none') {
+        if (lower === 'and' &&
+            (this.andBreak !== 'none' || (this.whenOneLine && parentContainerType === SqlPrintTokenContainerType.MergeWhenClause))) {
             this.handleAndOperatorToken(token, level, parentContainerType, caseContextDepth);
             return;
         }
-        else if (lower === 'or' && this.orBreak !== 'none') {
+        else if (lower === 'or' &&
+            (this.orBreak !== 'none' || (this.whenOneLine && parentContainerType === SqlPrintTokenContainerType.MergeWhenClause))) {
             this.handleOrOperatorToken(token, level, parentContainerType, caseContextDepth);
             return;
         }
@@ -278,18 +493,50 @@ export class SqlPrinter {
             this.linePrinter.appendText(text);
             return;
         }
+        this.ensureSpaceBeforeKeyword();
         this.linePrinter.appendText(text);
     }
+    ensureSpaceBeforeKeyword() {
+        const currentLine = this.linePrinter.getCurrentLine();
+        if (currentLine.text === '') {
+            return;
+        }
+        const lastChar = currentLine.text[currentLine.text.length - 1];
+        if (lastChar === '(') {
+            return;
+        }
+        this.ensureTrailingSpace();
+    }
+    ensureTrailingSpace() {
+        const currentLine = this.linePrinter.getCurrentLine();
+        if (currentLine.text === '') {
+            return;
+        }
+        if (!currentLine.text.endsWith(' ')) {
+            currentLine.text += ' ';
+        }
+        currentLine.text = currentLine.text.replace(/\s+$/, ' ');
+    }
+    /**
+     * Normalizes INSERT column list token text when one-line formatting is active.
+     */
+    tryAppendInsertClauseTokenText(text, parentContainerType) {
+        const currentLineText = this.linePrinter.getCurrentLine().text;
+        const result = this.onelineHelper.formatInsertClauseToken(text, parentContainerType, currentLineText, () => this.ensureTrailingSpace());
+        if (!result.handled) {
+            return false;
+        }
+        if (result.text) {
+            this.linePrinter.appendText(result.text);
+        }
+        return true;
+    }
     handleCommaToken(token, level, parentContainerType) {
         const text = token.text;
         const isWithinWithClause = parentContainerType === SqlPrintTokenContainerType.WithClause;
-        const isWithinValuesClause = parentContainerType === SqlPrintTokenContainerType.Values;
-        let effectiveCommaBreak = this.commaBreak;
-        if (isWithinWithClause) {
-            effectiveCommaBreak = this.cteCommaBreak;
-        }
-        else if (isWithinValuesClause) {
-            effectiveCommaBreak = this.valuesCommaBreak;
+        let effectiveCommaBreak = this.onelineHelper.resolveCommaBreak(parentContainerType, this.commaBreak, this.cteCommaBreak, this.valuesCommaBreak);
+        if (parentContainerType === SqlPrintTokenContainerType.SetClause) {
+            effectiveCommaBreak = 'before';
         }
         // Skip comma newlines when inside WITH clause with full-oneline style
         if (this.insideWithClause && this.withClauseStyle === 'full-oneline') {
@@ -307,6 +554,14 @@ export class SqlPrinter {
             }
             if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
                 this.linePrinter.appendNewline(level);
+                if (this.newline === ' ') {
+                    // Remove the spacer introduced by space newlines so commas attach directly to the preceding token.
+                    this.linePrinter.trimTrailingWhitespaceFromPreviousLine();
+                }
+                if (parentContainerType === SqlPrintTokenContainerType.InsertClause) {
+                    // Align comma-prefixed column entries under the INSERT column indentation.
+                    this.linePrinter.getCurrentLine().level = level + 1;
+                }
             }
             this.linePrinter.appendText(text);
             if (previousCommaBreak !== 'before') {
@@ -335,6 +590,9 @@ export class SqlPrinter {
                 this.linePrinter.commaBreak = 'none';
             }
             this.linePrinter.appendText(text);
+            if (this.onelineHelper.isInsertClauseOneline(parentContainerType)) {
+                this.ensureTrailingSpace();
+            }
             if (previousCommaBreak !== 'none') {
                 this.linePrinter.commaBreak = previousCommaBreak;
             }
@@ -349,6 +607,11 @@ export class SqlPrinter {
             this.linePrinter.appendText(text);
             return;
         }
+        if (this.whenOneLine &&
+            (parentContainerType === SqlPrintTokenContainerType.MergeWhenClause || this.mergeWhenPredicateDepth > 0)) {
+            this.linePrinter.appendText(text);
+            return;
+        }
         if (this.andBreak === 'before') {
             // Skip newline when inside WITH clause with full-oneline style
             if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
@@ -367,20 +630,32 @@ export class SqlPrinter {
             this.linePrinter.appendText(text);
         }
     }
-    handleParenthesisToken(token, level, indentParentActive) {
+    handleParenthesisToken(token, level, indentParentActive, parentContainerType) {
         if (token.text === '(') {
             this.linePrinter.appendText(token.text);
-            if (indentParentActive && !this.isOnelineMode()) {
-                if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
+            if ((parentContainerType === SqlPrintTokenContainerType.InsertClause ||
+                parentContainerType === SqlPrintTokenContainerType.MergeInsertAction) &&
+                this.insertColumnsOneLine) {
+                return;
+            }
+            if (!this.isOnelineMode()) {
+                if (this.shouldBreakAfterOpeningParen(parentContainerType)) {
+                    this.linePrinter.appendNewline(level + 1);
+                }
+                else if (indentParentActive && !(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
                     this.linePrinter.appendNewline(level);
                 }
             }
             return;
         }
-        if (token.text === ')' && indentParentActive && !this.isOnelineMode()) {
-            // Align closing parenthesis with the outer indentation level when nested groups expand.
-            const closingLevel = Math.max(level - 1, 0);
-            if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
+        if (token.text === ')' && !this.isOnelineMode()) {
+            if (this.shouldBreakBeforeClosingParen(parentContainerType)) {
+                this.linePrinter.appendNewline(Math.max(level, 0));
+                this.linePrinter.appendText(token.text);
+                return;
+            }
+            if (indentParentActive && !(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
+                const closingLevel = Math.max(level - 1, 0);
                 this.linePrinter.appendNewline(closingLevel);
             }
         }
@@ -393,6 +668,11 @@ export class SqlPrinter {
             this.linePrinter.appendText(text);
             return;
         }
+        if (this.whenOneLine &&
+            (parentContainerType === SqlPrintTokenContainerType.MergeWhenClause || this.mergeWhenPredicateDepth > 0)) {
+            this.linePrinter.appendText(text);
+            return;
+        }
         if (this.orBreak === 'before') {
             // Insert a newline before OR unless WITH full-oneline mode suppresses breaks.
             if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
@@ -442,37 +722,140 @@ export class SqlPrinter {
     }
     handleJoinClauseToken(token, level) {
         const text = this.applyKeywordCase(token.text);
-        // before join clause, add newline (skip when inside WITH clause with full-oneline style)
-        if (!(this.insideWithClause && this.withClauseStyle === 'full-oneline')) {
+        // before join clause, add newline when multiline formatting is allowed
+        if (this.onelineHelper.shouldInsertJoinNewline(this.insideWithClause)) {
             this.linePrinter.appendNewline(level);
         }
         this.linePrinter.appendText(text);
     }
+    /**
+     * Decides whether the current container should collapse into a single line.
+     */
+    shouldFormatContainerAsOneline(token, shouldIndentNested) {
+        return this.onelineHelper.shouldFormatContainer(token, shouldIndentNested);
+    }
+    /**
+     * Detects an INSERT column list that must stay on a single line.
+     */
+    isInsertClauseOneline(parentContainerType) {
+        return this.onelineHelper.isInsertClauseOneline(parentContainerType);
+    }
     /**
      * Handles space tokens with context-aware filtering.
      * Skips spaces in CommentBlocks when in specific CTE modes to prevent duplication.
      */
-    handleSpaceToken(token, parentContainerType) {
+    handleSpaceToken(token, parentContainerType, nextToken, previousToken, priorToken) {
         if (this.smartCommentBlockBuilder && this.smartCommentBlockBuilder.mode === 'line') {
             this.flushSmartCommentBlockBuilder();
         }
-        if (this.shouldSkipCommentBlockSpace(parentContainerType)) {
+        const currentLineText = this.linePrinter.getCurrentLine().text;
+        if (this.onelineHelper.shouldSkipInsertClauseSpace(parentContainerType, nextToken, currentLineText)) {
+            return;
+        }
+        if (this.onelineHelper.shouldSkipCommentBlockSpace(parentContainerType, this.insideWithClause)) {
             const currentLine = this.linePrinter.getCurrentLine();
             if (currentLine.text !== '' && !currentLine.text.endsWith(' ')) {
                 this.linePrinter.appendText(' ');
             }
             return;
         }
+        // Skip redundant spaces before structural parentheses in CREATE TABLE DDL.
+        if (this.shouldSkipSpaceBeforeParenthesis(parentContainerType, nextToken, previousToken, priorToken)) {
+            return;
+        }
         this.linePrinter.appendText(token.text);
     }
-    /**
-     * Determines whether to skip space tokens in CommentBlocks.
-     * Prevents duplicate spacing in CTE full-oneline mode only.
-     */
-    shouldSkipCommentBlockSpace(parentContainerType) {
-        return parentContainerType === SqlPrintTokenContainerType.CommentBlock &&
-            this.insideWithClause &&
-            this.withClauseStyle === 'full-oneline';
+    findPreviousSignificantToken(tokens, index) {
+        for (let i = index - 1; i >= 0; i--) {
+            const candidate = tokens[i];
+            if (candidate.type === SqlPrintTokenType.space || candidate.type === SqlPrintTokenType.commentNewline) {
+                continue;
+            }
+            if (candidate.type === SqlPrintTokenType.comment && !this.rendersInlineComments()) {
+                continue;
+            }
+            return { token: candidate, index: i };
+        }
+        return undefined;
+    }
+    shouldSkipSpaceBeforeParenthesis(parentContainerType, nextToken, previousToken, priorToken) {
+        if (!nextToken || nextToken.type !== SqlPrintTokenType.parenthesis || nextToken.text !== '(') {
+            return false;
+        }
+        if (!parentContainerType || !this.isCreateTableSpacingContext(parentContainerType)) {
+            return false;
+        }
+        if (!previousToken) {
+            return false;
+        }
+        if (this.isCreateTableNameToken(previousToken, parentContainerType)) {
+            return true;
+        }
+        if (this.isCreateTableConstraintKeyword(previousToken, parentContainerType)) {
+            return true;
+        }
+        if (priorToken && this.isCreateTableConstraintKeyword(priorToken, parentContainerType)) {
+            if (this.isIdentifierAttachedToConstraint(previousToken, priorToken, parentContainerType)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    shouldAlignCreateTableSelect(containerType, parentContainerType) {
+        return containerType === SqlPrintTokenContainerType.SimpleSelectQuery &&
+            parentContainerType === SqlPrintTokenContainerType.CreateTableQuery;
+    }
+    isCreateTableSpacingContext(parentContainerType) {
+        switch (parentContainerType) {
+            case SqlPrintTokenContainerType.CreateTableQuery:
+            case SqlPrintTokenContainerType.CreateTableDefinition:
+            case SqlPrintTokenContainerType.TableConstraintDefinition:
+            case SqlPrintTokenContainerType.ColumnConstraintDefinition:
+            case SqlPrintTokenContainerType.ReferenceDefinition:
+                return true;
+            default:
+                return false;
+        }
+    }
+    isCreateTableNameToken(previousToken, parentContainerType) {
+        if (parentContainerType !== SqlPrintTokenContainerType.CreateTableQuery) {
+            return false;
+        }
+        return previousToken.containerType === SqlPrintTokenContainerType.QualifiedName;
+    }
+    isCreateTableConstraintKeyword(token, parentContainerType) {
+        if (token.type !== SqlPrintTokenType.keyword) {
+            return false;
+        }
+        const text = token.text.toLowerCase();
+        if (parentContainerType === SqlPrintTokenContainerType.ReferenceDefinition) {
+            return CREATE_TABLE_PAREN_KEYWORDS_WITH_IDENTIFIER.has(text);
+        }
+        if (CREATE_TABLE_SINGLE_PAREN_KEYWORDS.has(text)) {
+            return true;
+        }
+        if (CREATE_TABLE_MULTI_PAREN_KEYWORDS.has(text)) {
+            return true;
+        }
+        return false;
+    }
+    isIdentifierAttachedToConstraint(token, keywordToken, parentContainerType) {
+        if (!token) {
+            return false;
+        }
+        if (parentContainerType === SqlPrintTokenContainerType.ReferenceDefinition) {
+            return token.containerType === SqlPrintTokenContainerType.QualifiedName &&
+                CREATE_TABLE_PAREN_KEYWORDS_WITH_IDENTIFIER.has(keywordToken.text.toLowerCase());
+        }
+        if (parentContainerType === SqlPrintTokenContainerType.TableConstraintDefinition ||
+            parentContainerType === SqlPrintTokenContainerType.ColumnConstraintDefinition) {
+            const normalized = keywordToken.text.toLowerCase();
+            if (CREATE_TABLE_SINGLE_PAREN_KEYWORDS.has(normalized) ||
+                CREATE_TABLE_MULTI_PAREN_KEYWORDS.has(normalized)) {
+                return token.containerType === SqlPrintTokenContainerType.IdentifierString;
+            }
+        }
+        return false;
     }
     printCommentToken(text, level, parentContainerType) {
         const trimmed = text.trim();
@@ -495,11 +878,12 @@ export class SqlPrinter {
                 const lineText = content ? `-- ${content}` : '--';
                 if (parentContainerType === SqlPrintTokenContainerType.CommentBlock) {
                     this.linePrinter.appendText(lineText);
-                    this.pendingLineCommentBreak = level;
+                    this.pendingLineCommentBreak = this.resolveCommentIndentLevel(level, parentContainerType);
                 }
                 else {
                     this.linePrinter.appendText(lineText);
-                    this.linePrinter.appendNewline(level);
+                    const effectiveLevel = this.resolveCommentIndentLevel(level, parentContainerType);
+                    this.linePrinter.appendNewline(effectiveLevel);
                 }
             }
         }
@@ -520,10 +904,11 @@ export class SqlPrinter {
             }
             if (trimmed.startsWith('--')) {
                 if (parentContainerType === SqlPrintTokenContainerType.CommentBlock) {
-                    this.pendingLineCommentBreak = level;
+                    this.pendingLineCommentBreak = this.resolveCommentIndentLevel(level, parentContainerType);
                 }
                 else {
-                    this.linePrinter.appendNewline(level);
+                    const effectiveLevel = this.resolveCommentIndentLevel(level, parentContainerType);
+                    this.linePrinter.appendNewline(effectiveLevel);
                 }
             }
         }
@@ -566,11 +951,8 @@ export class SqlPrinter {
         this.flushSmartCommentBlockBuilder();
         return false;
     }
-    handleCommentBlockContainer(token, level) {
+    handleCommentBlockContainer(token, level, context) {
         var _a;
-        if (!this.exportComment) {
-            return;
-        }
         if (this.commentStyle !== 'smart') {
             const rawLines = this.extractRawCommentBlockLines(token);
             if (rawLines.length > 0) {
@@ -580,7 +962,13 @@ export class SqlPrinter {
                 return;
             }
             for (const child of token.innerTokens) {
-                this.appendToken(child, level, token.containerType, 0, false);
+                // Force inner comment tokens to render once the block is approved.
+                const childContext = {
+                    position: context.position,
+                    isTopLevelContainer: context.isTopLevelContainer,
+                    forceRender: true,
+                };
+                this.appendToken(child, level, token.containerType, 0, false, childContext);
             }
             return;
         }
@@ -642,7 +1030,8 @@ export class SqlPrinter {
         }
         const { lines, level, mode } = this.smartCommentBlockBuilder;
         if (mode === 'line') {
-            if (lines.length > 1) {
+            const meaningfulLineCount = lines.filter(line => line.trim() !== '').length;
+            if (meaningfulLineCount > 1) {
                 const blockText = this.buildBlockComment(lines, level);
                 this.linePrinter.appendText(blockText);
             }
@@ -805,6 +1194,19 @@ export class SqlPrinter {
             .replace(/\/\*/g, '\\/\\*')
             .replace(/\*\//g, '*\\/');
     }
+    getCommentBaseIndentLevel(level, parentContainerType) {
+        if (!parentContainerType) {
+            return level;
+        }
+        const clauseAlignedLevel = this.getClauseBreakIndentLevel(parentContainerType, level);
+        return Math.max(level, clauseAlignedLevel);
+    }
+    resolveCommentIndentLevel(level, parentContainerType) {
+        var _a;
+        const baseLevel = this.getCommentBaseIndentLevel(level, parentContainerType);
+        const currentLevel = (_a = this.linePrinter.getCurrentLine().level) !== null && _a !== void 0 ? _a : baseLevel;
+        return Math.max(baseLevel, currentLevel);
+    }
     /**
      * Handles commentNewline tokens with conditional newline behavior.
      * In multiline mode (newline !== ' '), adds a newline after comments.
@@ -835,6 +1237,43 @@ export class SqlPrinter {
         return (this.insideWithClause && this.withClauseStyle === 'full-oneline') ||
             this.withClauseStyle === 'cte-oneline';
     }
+    shouldAddNewlineBeforeLeadingComments(parentType) {
+        if (!parentType) {
+            return false;
+        }
+        if (parentType === SqlPrintTokenContainerType.TupleExpression) {
+            return true;
+        }
+        if (parentType === SqlPrintTokenContainerType.InsertClause ||
+            parentType === SqlPrintTokenContainerType.MergeInsertAction) {
+            return !this.insertColumnsOneLine;
+        }
+        if (parentType === SqlPrintTokenContainerType.SetClause) {
+            return true;
+        }
+        if (parentType === SqlPrintTokenContainerType.SelectClause) {
+            return true;
+        }
+        if (parentType === SqlPrintTokenContainerType.ExplainStatement) {
+            // Ensure EXPLAIN targets print header comments on a dedicated line.
+            return true;
+        }
+        return false;
+    }
+    getLeadingCommentIndentLevel(parentType, currentLevel) {
+        if (parentType === SqlPrintTokenContainerType.TupleExpression) {
+            return currentLevel + 1;
+        }
+        if (parentType === SqlPrintTokenContainerType.InsertClause ||
+            parentType === SqlPrintTokenContainerType.MergeInsertAction ||
+            parentType === SqlPrintTokenContainerType.SelectClause) {
+            return currentLevel + 1;
+        }
+        if (parentType === SqlPrintTokenContainerType.SetClause) {
+            return currentLevel + 1;
+        }
+        return currentLevel;
+    }
     /**
      * Determines if the printer is in oneliner mode.
      * Oneliner mode uses single spaces instead of actual newlines.
@@ -867,9 +1306,10 @@ export class SqlPrinter {
             andBreak: this.andBreak,
             orBreak: this.orBreak,
             keywordCase: this.keywordCase,
-            exportComment: false,
+            exportComment: 'none',
             withClauseStyle: 'standard', // Prevent recursive processing
             indentNestedParentheses: false,
+            insertColumnsOneLine: this.insertColumnsOneLine,
         });
     }
     /**
@@ -882,6 +1322,117 @@ export class SqlPrinter {
         const cleanedResult = this.cleanDuplicateSpaces(onelineResult);
         this.linePrinter.appendText(cleanedResult);
     }
+    getClauseBreakIndentLevel(parentType, level) {
+        if (!parentType) {
+            return level;
+        }
+        switch (parentType) {
+            case SqlPrintTokenContainerType.MergeWhenClause:
+                // Actions under WHEN clauses should be indented one level deeper than the WHEN line.
+                return level + 1;
+            case SqlPrintTokenContainerType.MergeUpdateAction:
+            case SqlPrintTokenContainerType.MergeDeleteAction:
+            case SqlPrintTokenContainerType.MergeInsertAction:
+                // Keep MERGE actions and their follow-up keywords (e.g., VALUES, WHERE) aligned with the action keyword.
+                return level + 1;
+            default:
+                return level;
+        }
+    }
+    isMergeActionContainer(token) {
+        if (!token) {
+            return false;
+        }
+        switch (token.containerType) {
+            case SqlPrintTokenContainerType.MergeUpdateAction:
+            case SqlPrintTokenContainerType.MergeDeleteAction:
+            case SqlPrintTokenContainerType.MergeInsertAction:
+            case SqlPrintTokenContainerType.MergeDoNothingAction:
+                return true;
+            default:
+                return false;
+        }
+    }
+    shouldBreakAfterOpeningParen(parentType) {
+        if (!parentType) {
+            return false;
+        }
+        if (parentType === SqlPrintTokenContainerType.InsertClause ||
+            parentType === SqlPrintTokenContainerType.MergeInsertAction) {
+            return !this.isInsertClauseOneline(parentType);
+        }
+        return false;
+    }
+    shouldBreakBeforeClosingParen(parentType) {
+        if (!parentType) {
+            return false;
+        }
+        if (parentType === SqlPrintTokenContainerType.InsertClause ||
+            parentType === SqlPrintTokenContainerType.MergeInsertAction) {
+            return !this.isInsertClauseOneline(parentType);
+        }
+        return false;
+    }
+    shouldConvertSpaceToClauseBreak(parentType, nextToken) {
+        if (!parentType || !nextToken) {
+            return false;
+        }
+        const nextKeyword = nextToken.type === SqlPrintTokenType.keyword ? nextToken.text.toLowerCase() : null;
+        const nextContainer = nextToken.containerType;
+        if (parentType === SqlPrintTokenContainerType.MergeQuery) {
+            // Break before USING blocks and before each WHEN clause to mirror statement structure.
+            if (nextKeyword === 'using') {
+                return true;
+            }
+            if (nextContainer === SqlPrintTokenContainerType.MergeWhenClause) {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.MergeWhenClause) {
+            // Force the action to start on the next line with additional indentation.
+            if (nextContainer === SqlPrintTokenContainerType.MergeUpdateAction ||
+                nextContainer === SqlPrintTokenContainerType.MergeDeleteAction ||
+                nextContainer === SqlPrintTokenContainerType.MergeInsertAction ||
+                nextContainer === SqlPrintTokenContainerType.MergeDoNothingAction) {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.UpdateQuery) {
+            if (nextKeyword === 'set' || nextKeyword === 'from' || nextKeyword === 'where' || nextKeyword === 'returning') {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.InsertQuery) {
+            if (nextKeyword === 'returning') {
+                return true;
+            }
+            if (nextKeyword && (nextKeyword.startsWith('select') || nextKeyword.startsWith('values'))) {
+                return true;
+            }
+            if (nextContainer === SqlPrintTokenContainerType.ValuesQuery || nextContainer === SqlPrintTokenContainerType.SimpleSelectQuery) {
+                return true;
+            }
+            if (nextContainer === SqlPrintTokenContainerType.InsertClause) {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.DeleteQuery) {
+            if (nextKeyword === 'using' || nextKeyword === 'where' || nextKeyword === 'returning') {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.MergeUpdateAction || parentType === SqlPrintTokenContainerType.MergeDeleteAction) {
+            if (nextKeyword === 'where') {
+                return true;
+            }
+        }
+        if (parentType === SqlPrintTokenContainerType.MergeInsertAction) {
+            if (nextKeyword && (nextKeyword.startsWith('values') || nextKeyword === 'default values')) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Creates a unified SqlPrinter instance configured for oneline formatting.
      * Works for all oneline options: parentheses, BETWEEN, VALUES, JOIN, CASE, subqueries.
@@ -898,7 +1449,8 @@ export class SqlPrinter {
             andBreak: 'none', // Disable AND-based line breaks
             orBreak: 'none', // Disable OR-based line breaks
             keywordCase: this.keywordCase,
-            exportComment: this.exportComment,
+            exportComment: this.commentExportMode,
+            commentStyle: this.commentStyle,
             withClauseStyle: 'standard',
             parenthesesOneLine: false, // Prevent recursive processing (avoid infinite loops)
             betweenOneLine: false, // Prevent recursive processing (avoid infinite loops)
@@ -907,6 +1459,7 @@ export class SqlPrinter {
             caseOneLine: false, // Prevent recursive processing (avoid infinite loops)
             subqueryOneLine: false, // Prevent recursive processing (avoid infinite loops)
             indentNestedParentheses: false,
+            insertColumnsOneLine: this.insertColumnsOneLine,
         });
     }
     /**