@ttsc/factory 0.19.3 → 0.20.0

package/README.md

@@ -89,6 +89,8 @@ factory.createCallExpression(id("foo"), undefined, [a, b]); // foo(a, b)
 // )
 ```
 
+`printWidth` picks a layout, never a meaning. The break-time trailing comma is dropped where it would change the program (after the rest element of a destructuring assignment target, or after an argument-list hole), and it is written in both layouts where it is a value (the hole in `["a", "b", ,]`). JSX children stay on one line whenever a break would delete a whitespace-only child or trim the significant edge space off a text child, so the same tree renders the same text at every width.
+
 ### Comments
 
 Attach leading / trailing comments with the legacy `ts.addSyntheticLeadingComment` family. The printer renders them in place — multi-line bodies re-indent with their node, so JSDoc on a nested member stays aligned.

package/lib/TsPrinter.d.ts

@@ -54,23 +54,82 @@ export declare class TsPrinter {
     private statementBlock;
     private typeArguments;
     /**
-     * Whether a broken parameter list / binding pattern may append a synthetic
-     * trailing comma after its last element.
+     * Trailing-comma policy for a parameter list or binding pattern.
      *
-     * A trailing comma after a rest element (`...rest`) is a syntax error (TS1013
-     * / V8 `SyntaxError`), and one after a trailing elision (`OmittedExpression`)
-     * is not cosmetic: `[a, ,]` parses to one more hole than `[a, ]`, so the flat
-     * and broken layouts of the same node would disagree. Call arguments and
-     * array / object literals are unaffected — a trailing comma after a spread is
-     * legal there.
+     * A comma the printer adds only because a group broke must never change
+     * whether the text parses, nor what it parses to. After a rest element
+     * (`...rest`) it changes the first: a trailing comma there is a syntax error
+     * (TS1013 / V8 `SyntaxError`). After a trailing elision it changes the
+     * second: `[a, ,]` has one more hole than `[a, ]`, so the flat and broken
+     * layouts of the same node would disagree. A binding pattern is the one place
+     * where dropping that hole is lossless, since a trailing hole binds nothing;
+     * {@link literalTrailingComma} materializes it instead, because in an array
+     * literal the hole is a value.
      */
     private listTrailingComma;
+    /**
+     * Trailing-comma policy for a call or `new` argument list.
+     *
+     * A trailing `OmittedExpression` prints as nothing, so the list already ends
+     * in the separator comma of its last real argument: `f(a, )`, which is what
+     * the legacy printer emits too and parses as one argument. Adding the break
+     * comma on top produces `f(a, ,)`, which is a syntax error. A trailing spread
+     * is unaffected — a comma after it is legal in an argument list.
+     */
+    private argsTrailingComma;
+    /**
+     * Trailing-comma policy for an array or object literal.
+     *
+     * Two positions make the comma load-bearing rather than cosmetic.
+     *
+     * A trailing elision is a **value**: the comma is the token that materializes
+     * the hole, so `["a", ]` has one element and `["a", ,]` has two. The legacy
+     * printer emits it in every layout, so this printer emits it in every layout
+     * too; leaving it to the break would make the same node mean different things
+     * at different widths.
+     *
+     * A destructuring **assignment target** is the same node kind as an rvalue
+     * literal, but ECMAScript forbids a comma after its `AssignmentRestElement` /
+     * `AssignmentRestProperty`: `[a, ...rest,] = source` is a syntax error, while
+     * the identical rvalue `[a, ...rest,]` is legal. Only the target position
+     * suppresses it, so the rvalue twin keeps its break comma.
+     */
+    private literalTrailingComma;
     private params;
     private args;
     private modifiers;
     private heritage;
+    /**
+     * Lay out a JSX element's or fragment's children.
+     *
+     * A line break between JSX children is not cosmetic. JSX deletes a
+     * whitespace-only text child that contains a newline and trims
+     * whitespace-carrying-a-newline off both edges of every other text child, so
+     * a break introduced only because the group did not fit changes what the
+     * component renders: `<div>Hello there, {name}!</div>` becomes `Hello
+     * there,NAME!`, and the separator in `<div>{a} {b}</div>` disappears
+     * outright.
+     *
+     * Children are therefore laid out across lines only when the break survives
+     * that transformation unchanged: every text child must carry non-whitespace
+     * content, must not begin or end with whitespace, and must not sit next to
+     * another text child, since inserting a newline between two of them would
+     * merge into one text with a space in the middle. Otherwise the children are
+     * emitted verbatim on one line, whatever `printWidth` says — width may choose
+     * a layout, never a meaning.
+     */
+    private jsxChildren;
+    private jsxChildrenMayBreak;
     private optType;
     private optBody;
+    /**
+     * @param assignmentTarget Whether `node` occupies destructuring
+     *   assignment-target position, where an array or object literal is a pattern
+     *   rather than a value. The flag is set by the assignment and `for…in` /
+     *   `for…of` cases, forwarded by every node that is transparent to it (a
+     *   spread, a property's initializer, a parenthesis, an `=` default), and
+     *   dropped by every other node.
+     */
     private emit;
     /** Render a leading comment followed by its node separator. */
     private leadingComment;
@@ -85,21 +144,66 @@ export declare class TsPrinter {
      * re-associate — matching the legacy printer's parenthesizer rules.
      */
     private parenthesizedExpression;
+    /**
+     * The partial-emission wrapper carries transform provenance but emits no
+     * syntax of its own, so every grammar predicate must inspect its inner node.
+     */
+    private skipPartiallyEmittedExpressions;
     private expressionForDisallowedComma;
+    /**
+     * Emit an operand the grammar requires to be a `LeftHandSideExpression`,
+     * mirroring the legacy parenthesizer's
+     * `parenthesizeLeftSideOfAccess(expression, optionalChain)`.
+     *
+     * `optionalChain` is the **consuming** node's own chain-ness, not the
+     * operand's. An optional chain may be emitted bare only when the node
+     * consuming it continues the same chain: `a?.b?.()` is one chain, while
+     * `(a?.b)()` is a plain call on the chain's value. Emitting the second as
+     * `a?.b()` re-parses as the first, which stops throwing on a nullish head,
+     * and in `new`, tagged-template and decorator position it does not compile at
+     * all.
+     */
     private leftSideExpression;
+    /**
+     * Whether {@link leftSideExpression} wraps this operand.
+     *
+     * The legacy rule also parenthesizes an argument-less `new` here, because it
+     * prints `new X` bare and `new X.y` would re-parse with `y` on the target.
+     * This printer always emits the argument list, so `new X().y` already says
+     * what the tree says and needs no wrapper.
+     */
+    private leftSideNeedsParentheses;
+    private isOptionalChain;
     private newExpressionTarget;
     /**
      * Whether a `new` target must be parenthesized to keep its call arguments
      * from re-binding to the `new` — mirroring the legacy printer's
      * `parenthesizeExpressionOfNew`. A `new` target is grammatically a
-     * `MemberExpression`, so a call anywhere on the target's left spine (not just
-     * a direct one: `new (f().bar)()`, `new (a.b().c)()`) would otherwise
-     * re-parse with the call's arguments consumed by the `new` — a different
-     * program. Argument-less `new` on the spine is kept parenthesized for
-     * continuity with the direct case, though this printer always prints an
-     * argument list, which already disambiguates it.
+     * `MemberExpression`, so a call anywhere on the target's printed left spine
+     * (not just a direct one: `new (f().bar)()`, `new (a.b().c)()`) would
+     * otherwise re-parse with the call's arguments consumed by the `new` — a
+     * different program. Argument-less `new` on the spine is kept parenthesized
+     * for continuity with the direct case, though this printer always prints an
+     * argument list, which already disambiguates it. Anything else falls back to
+     * the shared left-side rule, which is what parenthesizes an optional-chain
+     * target (`new (a?.b)()`, TS1209 without it).
      */
     private newExpressionTargetNeedsParentheses;
+    /**
+     * The node whose own text opens `expression`'s printed form, or `undefined`
+     * when that text opens with a printer-inserted `(`.
+     *
+     * The legacy factory parenthesizes each operand as it builds the node, so its
+     * `getLeftmostExpression` walk halts on the resulting
+     * `ParenthesizedExpression`. This printer decides the same parentheses at
+     * emit time instead, so the walk has to ask {@link leftSideNeedsParentheses}
+     * the same question directly; otherwise `new` re-wraps a target whose call is
+     * already behind parentheses, and `new (f?.()).bar()` comes out as `new
+     * ((f?.()).bar)()`. Calls halt the walk, matching the legacy
+     * `stopAtCallExpressions` mode this predicate is the only user of.
+     */
+    private leftmostPrintedExpression;
+    private leftmostPrintedLeftSide;
     private prefixUnaryOperand;
     private postfixUnaryOperand;
     private conditionalCondition;
@@ -124,9 +228,12 @@ export declare class TsPrinter {
     private expressionNeedsExportDefaultParentheses;
     /**
      * Walk to the expression's leftmost node — the one that starts its printed
-     * text. With `stopAtCall`, calls terminate the walk instead of being walked
-     * through, matching the legacy `getLeftmostExpression`'s
-     * `stopAtCallExpressions` mode used by the `new`-target parenthesizer.
+     * text — matching the legacy `getLeftmostExpression`.
+     *
+     * Used by the statement, concise-body and export-default predicates, which
+     * ask only whether the text opens with a `function`, `class` or `{` token.
+     * The `new`-target predicate needs the printed left edge instead and uses
+     * {@link leftmostPrintedExpression}.
      */
     private leftmostExpression;
     private needsPrefixUnaryGap;