fix #4252: preserve parentheses around functions

Author: evanw

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+* Preserve parentheses around function expressions ([#4252](https://github.com/evanw/esbuild/issues/4252))
+
+    The V8 JavaScript VM uses parentheses around function expressions as an optimization hint to immediately compile the function. Otherwise the function would be lazily-compiled, which has additional overhead if that function is always called immediately as lazy compilation involves parsing the function twice. You can read [V8's blog post about this](https://v8.dev/blog/preparser) for more details.
+
+    Previously esbuild did not represent parentheses around functions in the AST so they were lost during compilation. With this change, esbuild will now preserve parentheses around function expressions when they are present in the original source code. This means these optimization hints will not be lost when bundling with esbuild. In addition, esbuild will now automatically add this optimization hint to immediately-invoked function expressions. Here's an example:
+
+    ```js
+    // Original code
+    const fn0 = () => 0
+    const fn1 = (() => 1)
+    console.log(fn0, function() { return fn1() }())
+
+    // Old output
+    const fn0 = () => 0;
+    const fn1 = () => 1;
+    console.log(fn0, function() {
+      return fn1();
+    }());
+
+    // New output
+    const fn0 = () => 0;
+    const fn1 = (() => 1);
+    console.log(fn0, (function() {
+      return fn1();
+    })());
+    ```
+
+    Note that you do not want to wrap all function expressions in parentheses. This optimization hint should only be used for functions that are called on initial load. Using this hint for functions that are not called on initial load will unnecessarily delay the initial load. Again, see V8's blog post linked above for details.
+
 * Update Go from 1.23.10 to 1.23.12 ([#4257](https://github.com/evanw/esbuild/issues/4257), [#4258](https://github.com/evanw/esbuild/pull/4258))
 
     This should have no effect on existing code as this version change does not change Go's operating system support. It may remove certain false positive reports (specifically CVE-2025-4674 and CVE-2025-47907) from vulnerability scanners that only detect which version of the Go compiler esbuild uses.

internal/bundler_tests/snapshots/snapshots_default.txt

@@ -84,31 +84,31 @@ TestArgumentsSpecialCaseNoBundle
     var arguments;
     return arguments;
   } });
+  ((n) => r);
+  (() => r);
+  (async () => r);
+  ((n = r) => r);
+  (async (n = r) => r);
   (n) => r;
   () => r;
   async () => r;
   (n = r) => r;
   async (n = r) => r;
-  (n) => r;
-  () => r;
-  async () => r;
-  (n = r) => r;
-  async (n = r) => r;
-  (n) => {
+  ((n) => {
     return r;
-  };
-  () => {
+  });
+  (() => {
     return r;
-  };
-  async () => {
+  });
+  (async () => {
     return r;
-  };
-  (n = r) => {
+  });
+  ((n = r) => {
     return r;
-  };
-  async (n = r) => {
+  });
+  (async (n = r) => {
     return r;
-  };
+  });
   (n) => {
     return r;
   };
@@ -131,10 +131,10 @@ TestArrowFnScope
 ---------- /out.js ----------
 // entry.js
 tests = {
-  0: (s = (e) => s + e, t) => s + t,
-  1: (s, t = (e) => t + e) => t + s,
-  2: (s = (a = (c) => s + a + c, b) => s + a + b, t, e) => s + t + e,
-  3: (s, t, e = (a, b = (c) => e + b + c) => e + b + a) => e + s + t,
+  0: ((s = (e) => s + e, t) => s + t),
+  1: ((s, t = (e) => t + e) => t + s),
+  2: ((s = (a = (c) => s + a + c, b) => s + a + b, t, e) => s + t + e),
+  3: ((s, t, e = (a, b = (c) => e + b + c) => e + b + a) => e + s + t),
   4: (x = (s) => x + s, y, x + y),
   5: (y, x = (s) => x + s, x + y),
   6: (x = (s = (e) => x + s + e, t) => x + s + t, y, z, x + y + z),

internal/bundler_tests/snapshots/snapshots_lower.txt

@@ -998,7 +998,7 @@ var baz2_default = class _baz2_default extends x {
 };
 
 // outer.js
-var outer_default = function() {
+var outer_default = (function() {
   return __async(this, null, function* () {
     class y extends z {
       constructor() {
@@ -1010,7 +1010,7 @@ var outer_default = function() {
     }
     yield new y().foo()();
   });
-}();
+})();
 export {
   bar1_default as bar1,
   bar2_default as bar2,
@@ -1126,7 +1126,7 @@ var baz2_default = class _baz2_default extends x {
 };
 
 // outer.js
-var outer_default = function() {
+var outer_default = (function() {
   return __async(this, null, function* () {
     class y extends z {
       constructor() {
@@ -1138,7 +1138,7 @@ var outer_default = function() {
     }
     yield new y().foo()();
   });
-}();
+})();
 export {
   bar1_default as bar1,
   bar2_default as bar2,
@@ -3427,7 +3427,7 @@ var baz2_default = class _baz2_default extends x {
 };
 
 // outer.js
-var outer_default = function() {
+var outer_default = (function() {
   return __async(this, null, function* () {
     const _y = class _y extends z {
     };
@@ -3437,7 +3437,7 @@ var outer_default = function() {
     let y = _y;
     yield y.foo()();
   });
-}();
+})();
 export {
   bar1_default as bar1,
   bar2_default as bar2,
@@ -3545,7 +3545,7 @@ var baz2_default = class _baz2_default extends x {
 };
 
 // outer.js
-var outer_default = function() {
+var outer_default = (function() {
   return __async(this, null, function* () {
     const _y = class _y extends z {
     };
@@ -3555,7 +3555,7 @@ var outer_default = function() {
     let y = _y;
     yield y.foo()();
   });
-}();
+})();
 export {
   bar1_default as bar1,
   bar2_default as bar2,

internal/js_ast/js_ast.go

@@ -698,11 +698,19 @@ type EArrow struct {
 	HasRestArg bool
 	PreferExpr bool // Use shorthand if true and "Body" is a single return statement
 
+	// V8 uses parentheses as an optimization hint: https://v8.dev/blog/preparser#pife
+	IsParenthesized bool
+
 	// See: https://github.com/rollup/rollup/pull/5024
 	HasNoSideEffectsComment bool
 }
 
-type EFunction struct{ Fn Fn }
+type EFunction struct {
+	Fn Fn
+
+	// V8 uses parentheses as an optimization hint: https://v8.dev/blog/preparser#pife
+	IsParenthesized bool
+}
 
 type EClass struct{ Class Class }
 

internal/js_parser/js_parser.go

@@ -3505,7 +3505,12 @@ func (p *parser) parsePrefix(level js_ast.L, errors *deferredErrors, flags exprF
 			p.allowIn = true
 
 			value := p.parseExpr(js_ast.LLowest)
-			p.markExprAsParenthesized(value, loc, false)
+
+			// Don't consider the "@(...)" decorator syntax to be important parentheses to preserve
+			if (flags & exprFlagDecorator) == 0 {
+				p.markExprAsParenthesized(value, loc, false)
+			}
+
 			p.lexer.Expect(js_lexer.TCloseParen)
 
 			p.allowIn = oldAllowIn
@@ -11670,6 +11675,10 @@ func (p *parser) markExprAsParenthesized(value js_ast.Expr, openParenLoc logger.
 		e.IsParenthesized = true
 	case *js_ast.EObject:
 		e.IsParenthesized = true
+	case *js_ast.EFunction:
+		e.IsParenthesized = true
+	case *js_ast.EArrow:
+		e.IsParenthesized = true
 	}
 }
 
@@ -14987,7 +14996,12 @@ func (p *parser) visitExprInOut(expr js_ast.Expr, in exprIn) (js_ast.Expr, exprO
 			storeThisArgForParentOptionalChain: e.OptionalChain == js_ast.OptionalChainStart || isParenthesizedOptionalChain,
 		})
 		e.Target = target
-		p.warnAboutImportNamespaceCall(e.Target, exprKindCall)
+		p.warnAboutImportNamespaceCall(target, exprKindCall)
+
+		// Automatically mark immediately-invoked function expressions for eager compilation
+		if fn, ok := target.Data.(*js_ast.EFunction); ok {
+			fn.IsParenthesized = true
+		}
 
 		hasSpread := false
 		oldIsControlFlowDead := p.isControlFlowDead

internal/js_parser/js_parser_test.go

@@ -1580,6 +1580,10 @@ func TestFunction(t *testing.T) {
 	expectParseError(t, "switch (0) { case 1: let f; default: function f() {} }", redeclaredError)
 	expectParseError(t, "switch (0) { case 1: var f; default: function f() {} }", redeclaredError)
 	expectParseError(t, "switch (0) { case 1: var f; default: function *f() {} }", redeclaredError)
+
+	// Inject parentheses around IIFEs as they are an optimization hint for VMs
+	expectPrinted(t, "var x = function() { y() }()", "var x = (function() {\n  y();\n})();\n")
+	expectPrinted(t, "var x = (true && function() { y() })()", "var x = (function() {\n  y();\n})();\n")
 }
 
 func TestClass(t *testing.T) {
@@ -2331,12 +2335,12 @@ func TestAsync(t *testing.T) {
 	expectParseError(t, "new async => {}", "<stdin>: ERROR: Expected \";\" but found \"=>\"\n")
 	expectParseError(t, "new async () => {}", "<stdin>: ERROR: Expected \";\" but found \"=>\"\n")
 
-	expectPrinted(t, "(async x => y), z", "async (x) => y, z;\n")
+	expectPrinted(t, "(async x => y), z", "(async (x) => y), z;\n")
 	expectPrinted(t, "(async x => y, z)", "async (x) => y, z;\n")
-	expectPrinted(t, "(async x => (y, z))", "async (x) => (y, z);\n")
-	expectPrinted(t, "(async (x) => y), z", "async (x) => y, z;\n")
+	expectPrinted(t, "(async x => (y, z))", "(async (x) => (y, z));\n")
+	expectPrinted(t, "(async (x) => y), z", "(async (x) => y), z;\n")
 	expectPrinted(t, "(async (x) => y, z)", "async (x) => y, z;\n")
-	expectPrinted(t, "(async (x) => (y, z))", "async (x) => (y, z);\n")
+	expectPrinted(t, "(async (x) => (y, z))", "(async (x) => (y, z));\n")
 	expectPrinted(t, "async x => y, z", "async (x) => y, z;\n")
 	expectPrinted(t, "async x => (y, z)", "async (x) => (y, z);\n")
 	expectPrinted(t, "async (x) => y, z", "async (x) => y, z;\n")
@@ -2494,7 +2498,7 @@ func TestArrow(t *testing.T) {
 
 	expectPrinted(t, "x => function() {}", "(x) => function() {\n};\n")
 	expectPrinted(t, "(x) => function() {}", "(x) => function() {\n};\n")
-	expectPrinted(t, "(x => function() {})", "(x) => function() {\n};\n")
+	expectPrinted(t, "(x => function() {})", "((x) => function() {\n});\n")
 
 	expectPrinted(t, "(x = () => {}) => {}", "(x = () => {\n}) => {\n};\n")
 	expectPrinted(t, "async (x = () => {}) => {}", "async (x = () => {\n}) => {\n};\n")
@@ -4285,7 +4289,7 @@ func TestMangleNullOrUndefinedWithSideEffects(t *testing.T) {
 	expectPrintedNormalAndMangle(t, "x('' ?? 1)", "x(\"\");\n", "x(\"\");\n")
 	expectPrintedNormalAndMangle(t, "x(/./ ?? 1)", "x(/./);\n", "x(/./);\n")
 	expectPrintedNormalAndMangle(t, "x({} ?? 1)", "x({});\n", "x({});\n")
-	expectPrintedNormalAndMangle(t, "x((() => {}) ?? 1)", "x(() => {\n});\n", "x(() => {\n});\n")
+	expectPrintedNormalAndMangle(t, "x((() => {}) ?? 1)", "x((() => {\n}));\n", "x((() => {\n}));\n")
 	expectPrintedNormalAndMangle(t, "x(class {} ?? 1)", "x(class {\n});\n", "x(class {\n});\n")
 	expectPrintedNormalAndMangle(t, "x(function() {} ?? 1)", "x(function() {\n});\n", "x(function() {\n});\n")
 
@@ -4651,7 +4655,7 @@ func TestMangleIIFE(t *testing.T) {
 	expectPrintedNormalAndMangle(t, "(async () => { a() })()", "(async () => {\n  a();\n})();\n", "(async () => a())();\n")
 	expectPrintedNormalAndMangle(t, "(async () => { let b = a; b() })()", "(async () => {\n  let b = a;\n  b();\n})();\n", "(async () => a())();\n")
 
-	expectPrintedNormalAndMangle(t, "var a = (function() {})()", "var a = /* @__PURE__ */ function() {\n}();\n", "var a = /* @__PURE__ */ function() {\n}();\n")
+	expectPrintedNormalAndMangle(t, "var a = (function() {})()", "var a = /* @__PURE__ */ (function() {\n})();\n", "var a = /* @__PURE__ */ (function() {\n})();\n")
 	expectPrintedNormalAndMangle(t, "(function() {})()", "/* @__PURE__ */ (function() {\n})();\n", "")
 	expectPrintedNormalAndMangle(t, "(function*() {})()", "(function* () {\n})();\n", "")
 	expectPrintedNormalAndMangle(t, "(async function() {})()", "(async function() {\n})();\n", "")
@@ -4998,7 +5002,7 @@ func TestMangleUnused(t *testing.T) {
 	expectPrintedNormalAndMangle(t, "this", "this;\n", "")
 	expectPrintedNormalAndMangle(t, "/regex/", "/regex/;\n", "")
 	expectPrintedNormalAndMangle(t, "(function() {})", "(function() {\n});\n", "")
-	expectPrintedNormalAndMangle(t, "(() => {})", "() => {\n};\n", "")
+	expectPrintedNormalAndMangle(t, "(() => {})", "(() => {\n});\n", "")
 	expectPrintedNormalAndMangle(t, "import.meta", "import.meta;\n", "")
 
 	// Unary operators

internal/js_parser/ts_parser_test.go

@@ -647,7 +647,7 @@ func TestTSSatisfies(t *testing.T) {
 	expectPrintedTS(t, "const t2 = { a: 1, b: 1 } satisfies I1;", "const t2 = { a: 1, b: 1 };\n")
 	expectPrintedTS(t, "const t3 = { } satisfies I1;", "const t3 = {};\n")
 	expectPrintedTS(t, "const t4: T1 = { a: 'a' } satisfies T1;", "const t4 = { a: \"a\" };\n")
-	expectPrintedTS(t, "const t5 = (m => m.substring(0)) satisfies T2;", "const t5 = (m) => m.substring(0);\n")
+	expectPrintedTS(t, "const t5 = (m => m.substring(0)) satisfies T2;", "const t5 = ((m) => m.substring(0));\n")
 	expectPrintedTS(t, "const t6 = [1, 2] satisfies [number, number];", "const t6 = [1, 2];\n")
 	expectPrintedTS(t, "let t7 = { a: 'test' } satisfies A;", "let t7 = { a: \"test\" };\n")
 	expectPrintedTS(t, "let t8 = { a: 'test', b: 'test' } satisfies A;", "let t8 = { a: \"test\", b: \"test\" };\n")
@@ -1688,7 +1688,7 @@ bar = 0 /* FOO */;
 `)
 
 	// https://github.com/evanw/esbuild/issues/3205
-	expectPrintedTS(t, "(() => { const enum Foo { A } () => Foo.A })", `() => {
+	expectPrintedTS(t, "() => { const enum Foo { A } () => Foo.A }", `() => {
   let Foo;
   ((Foo) => {
     Foo[Foo["A"] = 0] = "A";
@@ -1839,11 +1839,11 @@ func TestTSDecl(t *testing.T) {
 	expectParseErrorTS(t, "var a!, b", "<stdin>: ERROR: Expected \":\" but found \",\"\n")
 
 	expectPrinted(t, "a ? ({b}) => {} : c", "a ? ({ b }) => {\n} : c;\n")
-	expectPrinted(t, "a ? (({b}) => {}) : c", "a ? ({ b }) => {\n} : c;\n")
+	expectPrinted(t, "a ? (({b}) => {}) : c", "a ? (({ b }) => {\n}) : c;\n")
 	expectPrinted(t, "a ? (({b})) : c", "a ? { b } : c;\n")
 	expectParseError(t, "a ? (({b})) => {} : c", "<stdin>: ERROR: Invalid binding pattern\n")
 	expectPrintedTS(t, "a ? ({b}) => {} : c", "a ? ({ b }) => {\n} : c;\n")
-	expectPrintedTS(t, "a ? (({b}) => {}) : c", "a ? ({ b }) => {\n} : c;\n")
+	expectPrintedTS(t, "a ? (({b}) => {}) : c", "a ? (({ b }) => {\n}) : c;\n")
 	expectPrintedTS(t, "a ? (({b})) : c", "a ? { b } : c;\n")
 	expectParseErrorTS(t, "a ? (({b})) => {} : c", "<stdin>: ERROR: Invalid binding pattern\n")
 }
@@ -3150,12 +3150,12 @@ func TestTSJSX(t *testing.T) {
 	expectParseErrorTSX(t, "(<T>(x: X<Y>) => {}</Y></T>)", invalidWithHint)
 	expectParseErrorTSX(t, "(<T extends>(y) => {}</T>)", invalid)
 	expectParseErrorTSX(t, "(<T extends={false}>(y) => {}</T>)", invalid)
-	expectPrintedTSX(t, "(<T = X>(y) => {})", "(y) => {\n};\n")
-	expectPrintedTSX(t, "(<T extends X>(y) => {})", "(y) => {\n};\n")
-	expectPrintedTSX(t, "(<T extends X = Y>(y) => {})", "(y) => {\n};\n")
-	expectPrintedTSX(t, "(<T,>() => {})", "() => {\n};\n")
-	expectPrintedTSX(t, "(<T, X>(y) => {})", "(y) => {\n};\n")
-	expectPrintedTSX(t, "(<T, X>(y): (() => {}) => {})", "(y) => {\n};\n")
+	expectPrintedTSX(t, "(<T = X>(y) => {})", "((y) => {\n});\n")
+	expectPrintedTSX(t, "(<T extends X>(y) => {})", "((y) => {\n});\n")
+	expectPrintedTSX(t, "(<T extends X = Y>(y) => {})", "((y) => {\n});\n")
+	expectPrintedTSX(t, "(<T,>() => {})", "(() => {\n});\n")
+	expectPrintedTSX(t, "(<T, X>(y) => {})", "((y) => {\n});\n")
+	expectPrintedTSX(t, "(<T, X>(y): (() => {}) => {})", "((y) => {\n});\n")
 	expectParseErrorTSX(t, "(<T>() => {})", invalidWithHint+"<stdin>: ERROR: Unexpected end of file before a closing \"T\" tag\n<stdin>: NOTE: The opening \"T\" tag is here:\n")
 	expectParseErrorTSX(t, "(<T>(x: X<Y>) => {})", invalidWithHint+"<stdin>: ERROR: Unexpected end of file before a closing \"Y\" tag\n<stdin>: NOTE: The opening \"Y\" tag is here:\n")
 	expectParseErrorTSX(t, "(<T>(x: X<Y>) => {})</Y>", invalidWithHint+"<stdin>: ERROR: Unexpected end of file before a closing \"T\" tag\n<stdin>: NOTE: The opening \"T\" tag is here:\n")
@@ -3174,9 +3174,9 @@ func TestTSJSX(t *testing.T) {
 }
 
 func TestTSNoAmbiguousLessThan(t *testing.T) {
-	expectPrintedTSNoAmbiguousLessThan(t, "(<T,>() => {})", "() => {\n};\n")
-	expectPrintedTSNoAmbiguousLessThan(t, "(<T, X>() => {})", "() => {\n};\n")
-	expectPrintedTSNoAmbiguousLessThan(t, "(<T extends X>() => {})", "() => {\n};\n")
+	expectPrintedTSNoAmbiguousLessThan(t, "(<T,>() => {})", "(() => {\n});\n")
+	expectPrintedTSNoAmbiguousLessThan(t, "(<T, X>() => {})", "(() => {\n});\n")
+	expectPrintedTSNoAmbiguousLessThan(t, "(<T extends X>() => {})", "(() => {\n});\n")
 	expectParseErrorTSNoAmbiguousLessThan(t, "(<T>x)",
 		"<stdin>: ERROR: This syntax is not allowed in files with the \".mts\" or \".cts\" extension\n")
 	expectParseErrorTSNoAmbiguousLessThan(t, "(<T>() => {})",

internal/js_printer/js_printer.go

@@ -2710,7 +2710,7 @@ func (p *printer) printExpr(expr js_ast.Expr, level js_ast.L, flags printExprFla
 		}
 
 	case *js_ast.EArrow:
-		wrap := level >= js_ast.LAssign
+		wrap := e.IsParenthesized || level >= js_ast.LAssign
 
 		if wrap {
 			p.print("(")
@@ -2738,8 +2738,12 @@ func (p *printer) printExpr(expr js_ast.Expr, level js_ast.L, flags printExprFla
 		wasPrinted := false
 		if len(e.Body.Block.Stmts) == 1 && e.PreferExpr {
 			if s, ok := e.Body.Block.Stmts[0].Data.(*js_ast.SReturn); ok && s.ValueOrNil.Data != nil {
+				var nestedFlags printExprFlags
+				if (flags&forbidIn) != 0 && !wrap {
+					nestedFlags |= forbidIn
+				}
 				p.arrowExprStart = len(p.js)
-				p.printExprWithoutLeadingNewline(s.ValueOrNil, js_ast.LComma, flags&forbidIn)
+				p.printExprWithoutLeadingNewline(s.ValueOrNil, js_ast.LComma, nestedFlags)
 				wasPrinted = true
 			}
 		}
@@ -2752,7 +2756,7 @@ func (p *printer) printExpr(expr js_ast.Expr, level js_ast.L, flags printExprFla
 
 	case *js_ast.EFunction:
 		n := len(p.js)
-		wrap := p.stmtStart == n || p.exportDefaultStart == n ||
+		wrap := e.IsParenthesized || p.stmtStart == n || p.exportDefaultStart == n ||
 			((flags&isPropertyAccessTarget) != 0 && p.options.UnsupportedFeatures.Has(compat.FunctionOrClassPropertyAccess))
 		if wrap {
 			p.print("(")