Preserve native destructuring for CommonJS exports to keep iterator semantics (#3705)

Copilot · jakebailey · web-flow · commit 654d05ca29b5 · 2026-05-19T18:33:14.000Z
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: jakebailey &lt;5341706+jakebailey@users.noreply.github.com&gt;
diff --git a/internal/transformers/moduletransforms/commonjsmodule.go b/internal/transformers/moduletransforms/commonjsmodule.go
@@ -1109,13 +1109,14 @@ func (tx *CommonJSModuleTransformer) transformInitializedVariable(node *ast.Vari
 	}
 	name := node.Name()
 	if ast.IsBindingPattern(name) {
-		return transformers.FlattenDestructuringAssignment(
-			&tx.Transformer,
-			tx.Visitor().VisitNode(node.AsNode()),
-			false, /*needsValue*/
-			transformers.FlattenLevelAll,
-			tx.createAllExportExpressions,
-		)
+		// Convert the binding pattern into an equivalent assignment expression and visit it
+		// as a destructuring assignment. This preserves native destructuring (and therefore
+		// iterator semantics for array patterns) whenever each leaf identifier can be
+		// substituted to an export reference. Only when the destructuring would assign to
+		// re-aliased or multi-exported names (where native destructuring cannot update all
+		// targets) does `visitDestructuringAssignment` fall back to flattening.
+		assignment := transformers.ConvertVariableDeclarationToAssignmentExpression(tx.EmitContext(), node)
+		return tx.visitDestructuringAssignment(assignment.AsBinaryExpression(), true /*valueIsDiscarded*/)
 	}
 	propertyAccess := tx.Factory().NewPropertyAccessExpression(
 		tx.Factory().NewIdentifier("exports"),
@@ -1452,11 +1453,22 @@ func (tx *CommonJSModuleTransformer) destructuringNeedsFlattening(node *ast.Node
 		}
 	} else if ast.IsIdentifier(node) {
 		exportedNames := tx.getExports(node)
-		threshold := 0
 		if transformers.IsExportName(tx.EmitContext(), node) {
-			threshold = 1
+			// The identifier is already wrapped to be an export reference; tolerate up to one
+			// matching export.
+			return len(exportedNames) > 1
+		}
+		if len(exportedNames) == 0 {
+			return false
 		}
-		return len(exportedNames) > threshold
+		// A single direct export whose export name matches the identifier text can be handled
+		// natively: substitution will rewrite the identifier to `exports.X`, so no flattening
+		// is needed. Re-aliased exports (where the export name differs from the local name) or
+		// multi-exported names cannot be expressed natively in a destructuring assignment.
+		if len(exportedNames) == 1 && tx.isDirectExport(node) && exportedNames[0].Text() == node.Text() {
+			return false
+		}
+		return true
 	}
 	return false
 }
diff --git a/testdata/baselines/reference/compiler/exportDestructuring.js b/testdata/baselines/reference/compiler/exportDestructuring.js
@@ -10,4 +10,4 @@ export const [a, b] = arr;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.b = exports.a = void 0;
 const arr = [1, 2];
-exports.a = arr[0], exports.b = arr[1];
+[exports.a, exports.b] = arr;
diff --git a/testdata/baselines/reference/compiler/exportDestructuringIterator.js b/testdata/baselines/reference/compiler/exportDestructuringIterator.js
@@ -0,0 +1,24 @@
+//// [tests/cases/compiler/exportDestructuringIterator.ts] ////
+
+//// [exportDestructuringIterator.ts]
+declare function foo(): any;
+export const [A, V] = foo();
+export const { x, y } = foo();
+export const [a = 1, b = 2] = foo();
+export const [c, ...d] = foo();
+export const [, e, , f] = foo();
+export const [[g, h], { i, j: k }] = foo();
+export const { m: [n, o], p: { q } } = foo();
+
+
+//// [exportDestructuringIterator.js]
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.q = exports.o = exports.n = exports.k = exports.i = exports.h = exports.g = exports.f = exports.e = exports.d = exports.c = exports.b = exports.a = exports.y = exports.x = exports.V = exports.A = void 0;
+[exports.A, exports.V] = foo();
+({ x: exports.x, y: exports.y } = foo());
+[exports.a = 1, exports.b = 2] = foo();
+[exports.c, ...exports.d] = foo();
+[, exports.e, , exports.f] = foo();
+[[exports.g, exports.h], { i: exports.i, j: exports.k }] = foo();
+({ m: [exports.n, exports.o], p: { q: exports.q } } = foo());
diff --git a/testdata/baselines/reference/compiler/exportDestructuringIterator.symbols b/testdata/baselines/reference/compiler/exportDestructuringIterator.symbols
@@ -0,0 +1,44 @@
+//// [tests/cases/compiler/exportDestructuringIterator.ts] ////
+
+=== exportDestructuringIterator.ts ===
+declare function foo(): any;
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const [A, V] = foo();
+>A : Symbol(A, Decl(exportDestructuringIterator.ts, 1, 14))
+>V : Symbol(V, Decl(exportDestructuringIterator.ts, 1, 16))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const { x, y } = foo();
+>x : Symbol(x, Decl(exportDestructuringIterator.ts, 2, 14))
+>y : Symbol(y, Decl(exportDestructuringIterator.ts, 2, 17))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const [a = 1, b = 2] = foo();
+>a : Symbol(a, Decl(exportDestructuringIterator.ts, 3, 14))
+>b : Symbol(b, Decl(exportDestructuringIterator.ts, 3, 20))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const [c, ...d] = foo();
+>c : Symbol(c, Decl(exportDestructuringIterator.ts, 4, 14))
+>d : Symbol(d, Decl(exportDestructuringIterator.ts, 4, 16))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const [, e, , f] = foo();
+>e : Symbol(e, Decl(exportDestructuringIterator.ts, 5, 15))
+>f : Symbol(f, Decl(exportDestructuringIterator.ts, 5, 20))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const [[g, h], { i, j: k }] = foo();
+>g : Symbol(g, Decl(exportDestructuringIterator.ts, 6, 15))
+>h : Symbol(h, Decl(exportDestructuringIterator.ts, 6, 17))
+>i : Symbol(i, Decl(exportDestructuringIterator.ts, 6, 23))
+>k : Symbol(k, Decl(exportDestructuringIterator.ts, 6, 26))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
+export const { m: [n, o], p: { q } } = foo();
+>n : Symbol(n, Decl(exportDestructuringIterator.ts, 7, 19))
+>o : Symbol(o, Decl(exportDestructuringIterator.ts, 7, 21))
+>q : Symbol(q, Decl(exportDestructuringIterator.ts, 7, 30))
+>foo : Symbol(foo, Decl(exportDestructuringIterator.ts, 0, 0))
+
diff --git a/testdata/baselines/reference/compiler/exportDestructuringIterator.types b/testdata/baselines/reference/compiler/exportDestructuringIterator.types
@@ -0,0 +1,56 @@
+//// [tests/cases/compiler/exportDestructuringIterator.ts] ////
+
+=== exportDestructuringIterator.ts ===
+declare function foo(): any;
+>foo : () => any
+
+export const [A, V] = foo();
+>A : any
+>V : any
+>foo() : any
+>foo : () => any
+
+export const { x, y } = foo();
+>x : any
+>y : any
+>foo() : any
+>foo : () => any
+
+export const [a = 1, b = 2] = foo();
+>a : any
+>1 : 1
+>b : any
+>2 : 2
+>foo() : any
+>foo : () => any
+
+export const [c, ...d] = foo();
+>c : any
+>d : any
+>foo() : any
+>foo : () => any
+
+export const [, e, , f] = foo();
+>e : any
+>f : any
+>foo() : any
+>foo : () => any
+
+export const [[g, h], { i, j: k }] = foo();
+>g : any
+>h : any
+>i : any
+>j : any
+>k : any
+>foo() : any
+>foo : () => any
+
+export const { m: [n, o], p: { q } } = foo();
+>m : any
+>n : any
+>o : any
+>p : any
+>q : any
+>foo() : any
+>foo : () => any
+
diff --git a/testdata/baselines/reference/submodule/compiler/bindingPatternOmittedExpressionNesting.js b/testdata/baselines/reference/submodule/compiler/bindingPatternOmittedExpressionNesting.js
@@ -5,9 +5,8 @@ export let [,,[,[],,[],]] = undefined as any;
 
 //// [bindingPatternOmittedExpressionNesting.js]
 "use strict";
-var _a, _b, _c, _d;
 Object.defineProperty(exports, "__esModule", { value: true });
-_a = undefined, _b = _a[2], _c = _b[1], _d = _b[3];
+[, , [, [], , []]] = undefined;
 
 
 //// [bindingPatternOmittedExpressionNesting.d.ts]
diff --git a/testdata/baselines/reference/submodule/compiler/declarationEmitRetainsJsdocyComments.js b/testdata/baselines/reference/submodule/compiler/declarationEmitRetainsJsdocyComments.js
@@ -78,10 +78,11 @@ class Foo {
     }
 }
 exports.Foo = Foo;
-/**
-* comment5
-*/
-exports.someMethod = null.someMethod;
+({ 
+    /**
+    * comment5
+    */
+    someMethod: exports.someMethod } = null);
 
 
 //// [declarationEmitRetainsJsdocyComments.d.ts]
diff --git a/testdata/baselines/reference/submodule/compiler/destructuringInVariableDeclarations1.js b/testdata/baselines/reference/submodule/compiler/destructuringInVariableDeclarations1.js
@@ -11,7 +11,7 @@ export let { toString } = 1;
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toString = void 0;
-exports.toString = 1..toString;
+({ toString: exports.toString } = 1);
 {
     let { toFixed } = 1;
 }
diff --git a/testdata/baselines/reference/submodule/compiler/downlevelLetConst13(target=es2015).js b/testdata/baselines/reference/submodule/compiler/downlevelLetConst13(target=es2015).js
@@ -27,10 +27,10 @@ exports.M = exports.bar4 = exports.bar3 = exports.bar2 = exports.bar1 = exports.
 // exported let\const bindings should not be renamed
 exports.foo = 10;
 exports.bar = "123";
-exports.bar1 = [1][0];
-exports.bar2 = [2][0];
-exports.bar3 = { a: 1 }.a;
-exports.bar4 = { a: 1 }.a;
+[exports.bar1] = [1];
+[exports.bar2] = [2];
+({ a: exports.bar3 } = { a: 1 });
+({ a: exports.bar4 } = { a: 1 });
 var M;
 (function (M) {
     M.baz = 100;
diff --git a/testdata/baselines/reference/submodule/compiler/exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js b/testdata/baselines/reference/submodule/compiler/exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js
@@ -5,6 +5,5 @@ export const [] = [];
 
 //// [exportEmptyArrayBindingPattern.js]
 "use strict";
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-_a = [];
+[] = [];
diff --git a/testdata/baselines/reference/submodule/compiler/exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js b/testdata/baselines/reference/submodule/compiler/exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js
@@ -5,6 +5,5 @@ export const {} = {};
 
 //// [exportEmptyObjectBindingPattern.js]
 "use strict";
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-_a = {};
+({} = {});
diff --git a/testdata/baselines/reference/submodule/compiler/exportObjectRest(module=commonjs,target=esnext).js b/testdata/baselines/reference/submodule/compiler/exportObjectRest(module=commonjs,target=esnext).js
@@ -5,7 +5,6 @@ export const { x, ...rest } = { x: 'x', y: 'y' };
 
 //// [exportObjectRest.js]
 "use strict";
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rest = exports.x = void 0;
-_a = { x: 'x', y: 'y' }, exports.x = _a.x, exports.rest = __rest(_a, ["x"]);
+({ x: exports.x, ...exports.rest } = { x: 'x', y: 'y' });
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/bindingPatternOmittedExpressionNesting.js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/bindingPatternOmittedExpressionNesting.js.diff
@@ -0,0 +1,13 @@
+--- old.bindingPatternOmittedExpressionNesting.js
++++ new.bindingPatternOmittedExpressionNesting.js
+@@= skipped -4, +4 lines =@@
+
+ //// [bindingPatternOmittedExpressionNesting.js]
+ "use strict";
+-var _a, _b, _c, _d;
+ Object.defineProperty(exports, "__esModule", { value: true });
+-_a = undefined, _b = _a[2], _c = _b[1], _d = _b[3];
++[, , [, [], , []]] = undefined;
+
+
+ //// [bindingPatternOmittedExpressionNesting.d.ts]
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/declarationEmitRetainsJsdocyComments.js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/declarationEmitRetainsJsdocyComments.js.diff
@@ -0,0 +1,18 @@
+--- old.declarationEmitRetainsJsdocyComments.js
++++ new.declarationEmitRetainsJsdocyComments.js
+@@= skipped -77, +77 lines =@@
+     }
+ }
+ exports.Foo = Foo;
+-/**
+-* comment5
+-*/
+-exports.someMethod = null.someMethod;
++({ 
++    /**
++    * comment5
++    */
++    someMethod: exports.someMethod } = null);
+
+
+ //// [declarationEmitRetainsJsdocyComments.d.ts]
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/destructuringInVariableDeclarations1.js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/destructuringInVariableDeclarations1.js.diff
@@ -0,0 +1,11 @@
+--- old.destructuringInVariableDeclarations1.js
++++ new.destructuringInVariableDeclarations1.js
+@@= skipped -10, +10 lines =@@
+ "use strict";
+ Object.defineProperty(exports, "__esModule", { value: true });
+ exports.toString = void 0;
+-exports.toString = 1..toString;
++({ toString: exports.toString } = 1);
+ {
+     let { toFixed } = 1;
+ }
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/downlevelLetConst13(target=es2015).js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/downlevelLetConst13(target=es2015).js.diff
@@ -0,0 +1,17 @@
+--- old.downlevelLetConst13(target=es2015).js
++++ new.downlevelLetConst13(target=es2015).js
+@@= skipped -26, +26 lines =@@
+ // exported let\const bindings should not be renamed
+ exports.foo = 10;
+ exports.bar = "123";
+-exports.bar1 = [1][0];
+-exports.bar2 = [2][0];
+-exports.bar3 = { a: 1 }.a;
+-exports.bar4 = { a: 1 }.a;
++[exports.bar1] = [1];
++[exports.bar2] = [2];
++({ a: exports.bar3 } = { a: 1 });
++({ a: exports.bar4 } = { a: 1 });
+ var M;
+ (function (M) {
+     M.baz = 100;
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js.diff
@@ -0,0 +1,10 @@
+--- old.exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js
++++ new.exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js
+@@= skipped -4, +4 lines =@@
+
+ //// [exportEmptyArrayBindingPattern.js]
+ "use strict";
+-var _a;
+ Object.defineProperty(exports, "__esModule", { value: true });
+-_a = [];
++[] = [];
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js.diff
@@ -0,0 +1,10 @@
+--- old.exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js
++++ new.exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js
+@@= skipped -4, +4 lines =@@
+
+ //// [exportEmptyObjectBindingPattern.js]
+ "use strict";
+-var _a;
+ Object.defineProperty(exports, "__esModule", { value: true });
+-_a = {};
++({} = {});
diff --git a/testdata/baselines/reference/submoduleAccepted/compiler/exportObjectRest(module=commonjs,target=esnext).js.diff b/testdata/baselines/reference/submoduleAccepted/compiler/exportObjectRest(module=commonjs,target=esnext).js.diff
@@ -0,0 +1,11 @@
+--- old.exportObjectRest(module=commonjs,target=esnext).js
++++ new.exportObjectRest(module=commonjs,target=esnext).js
+@@= skipped -4, +4 lines =@@
+
+ //// [exportObjectRest.js]
+ "use strict";
+-var _a;
+ Object.defineProperty(exports, "__esModule", { value: true });
+ exports.rest = exports.x = void 0;
+-_a = { x: 'x', y: 'y' }, exports.x = _a.x, exports.rest = __rest(_a, ["x"]);
++({ x: exports.x, ...exports.rest } = { x: 'x', y: 'y' });
diff --git a/testdata/submoduleAccepted.txt b/testdata/submoduleAccepted.txt
@@ -1331,6 +1331,16 @@ conformance/objectLiteralErrors(target=es2015).types.diff
 conformance/propertyAndAccessorWithSameName.symbols.diff
 conformance/propertyAndAccessorWithSameName.types.diff
 
+## Preserve native destructuring for CommonJS exports to keep iterator semantics
+## https://github.com/microsoft/typescript-go/issues/3701
+compiler/bindingPatternOmittedExpressionNesting.js.diff
+compiler/declarationEmitRetainsJsdocyComments.js.diff
+compiler/destructuringInVariableDeclarations1.js.diff
+compiler/downlevelLetConst13(target=es2015).js.diff
+compiler/exportEmptyArrayBindingPattern(module=commonjs,target=esnext).js.diff
+compiler/exportEmptyObjectBindingPattern(module=commonjs,target=esnext).js.diff
+compiler/exportObjectRest(module=commonjs,target=esnext).js.diff
+
 ## Module resolver does not guess the project root to provide speculative resolutions for self-name
 ## imports in the presence of TS2209 "ambiguous project root" errors.
 ## After merging repos, consider adding a `rootDir` option to these tests
diff --git a/testdata/tests/cases/compiler/exportDestructuringIterator.ts b/testdata/tests/cases/compiler/exportDestructuringIterator.ts
@@ -0,0 +1,12 @@
+// @target: esnext
+// @module: commonjs
+// @strict: true
+
+declare function foo(): any;
+export const [A, V] = foo();
+export const { x, y } = foo();
+export const [a = 1, b = 2] = foo();
+export const [c, ...d] = foo();
+export const [, e, , f] = foo();
+export const [[g, h], { i, j: k }] = foo();
+export const { m: [n, o], p: { q } } = foo();

Original file line number	Diff line number	Diff line change
`@@ -78,10 +78,11 @@ class Foo {`
`78`	`78`	`}`
`79`	`79`	`}`
`80`	`80`	`exports.Foo = Foo;`
`81`		`-/**`
`82`		`-* comment5`
`83`		`-*/`
`84`		`-exports.someMethod = null.someMethod;`
	`81`	`+({`
	`82`	`+ /**`
	`83`	`+ * comment5`
	`84`	`+ */`
	`85`	`+ someMethod: exports.someMethod } = null);`
`85`	`86`
`86`	`87`
`87`	`88`	`//// [declarationEmitRetainsJsdocyComments.d.ts]`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ export let { toString } = 1;`
`11`	`11`	`"use strict";`
`12`	`12`	`Object.defineProperty(exports, "__esModule", { value: true });`
`13`	`13`	`exports.toString = void 0;`
`14`		`-exports.toString = 1..toString;`
	`14`	`+({ toString: exports.toString } = 1);`
`15`	`15`	`{`
`16`	`16`	`let { toFixed } = 1;`
`17`	`17`	`}`