`export declare` sometimes affects JS emit

[nicolo-ribaudo]

🔎 Search Terms

export declare js emit

🕗 Version & Regression Information

• This is the behavior in every version I tried

⏯ Playground Link

https://www.typescriptlang.org/play/?module=1#code/KYDwDg9gTgLgBAE2AYwDYEMrDq490BccAdgK4C2ARsFANwBQ6cAvHAEwNA

💻 Code

export declare let a: number;
a = 2;

🙁 Actual behavior

When compiled to JS, will that code export a variable named a? It depends!

• if compiling to ESM, no
• if compiling to CJS/AMD, yes
• if inside a namespace, yes

🙂 Expected behavior

Compiling to ESM or to CJS/AMD should behave the same. Specifically, they should all have the ESM behavior (no a exported), since declare means "this statement is only to tell something to the type checker, it should not actually affect the emitted JS code".

Maybe referencing locally something declared as export declare should be an error.

Additional information about the issue

Babel (babel/babel#17038), SWC (swc-project/swc#9821), and OXC (https://playground.oxc.rs/#eNo9TjFuwzAM/IrA2UNToIuKrp37gC60QgcGJFIg5TSB4b+XiuNo0R15d7wVEkRgLGQVEwW2sP5y8Ee3KtrCmVJGpZCpBYyBlzKSfu4SDF/h5HiDAQTiCrpw/+zODW8Qmy40QJ65QZwwmxNLUunY2L2Mkg/WFNkm0bIPtgEqqpH2xKrk6Eo/XoXtmeaKnv1QOH75d0tDvZAfBrL3t9MHuCLJmS7UKzopM8/TfJiTcFPJ31n+uvlKOop50f3Qtv0D8iJmOg==) already have the behavior I'm proposing.

[robpalme]

FYI ESBuild consciously chose to match current tsc behavior.

[nicolo-ribaudo]

ESBuild only matches tsc when it comes to export declare inside namespace, and not for export declare when targeting CJS: https://esbuild.egoist.dev/#W1siaW5kZXgudHMiLHsiY29udGVudCI6ImV4cG9ydCBkZWNsYXJlIGxldCBhOiBudW1iZXI7XG5hID0gMjsifV0sWyJlc2J1aWxkLmNvbmZpZy5qc29uIix7ImNvbnRlbnQiOiJ7XG4gIFwiZm9ybWF0XCI6IFwiY2pzXCIsXG4gIFwiY2RuVXJsXCI6IFwiaHR0cHM6Ly9lc20uc2hcIlxufSJ9XV0=

[Andarist]

export declare... what that even is supposed to mean? 😅 The non-ESM module transforms emit this based on the logic in substituteExpressionIdentifier (that calls into resolver.getReferencedExportContainer, which returns exportContainer.kind === SyntaxKind.SourceFile). This is something that's recorded as an export of that source file, so it seems to be "available" as an export/import.

When this is imported by other modules the emit for them includes appropriate importing statements:

• commonjs: workbench
• esm: workbench

@RyanCavanaugh could you clarify what the expected behavior here is?

[RyanCavanaugh]

export declare is indeed extremely confusing. I think the best interpretation is effectively "Pretend that someone text-concats an equivalent real export declaration somewhere in this file", which is load-bearing on "equivalent"

Looking at the emit again, I'm not super sure what the defect is actually supposed to be.

For CJS we have

exports.a = 2;

which is a correct output; it's the same as if you wrote

export let a: number = 3;
a = 2;

which produces

exports.a = 3;
exports.a = 2;

so we're exactly corresponding to the second line

For ESM we have

a = 2;

which is correct according to the "pretend that someone text-concated" interpretation of export declare

Absent a stronger argument, this is maybe just working as intended?

[nicolo-ribaudo]

I was going to ask "what does it mean in namespaces then, since we cannot just pretend to inject something in the middle of it" but then I realized that declaration merging allows marking bindings as exported:
https://www.typescriptlang.org/play/?isolatedModules=false#code/HYQwtgpgzgDiDGEAEAxA9mpBvAUE-SEAHjGgE4AuSANhFQEYBcSwArmPRGQNw4C+OHAHohw0SMGhIsBMnSZcBJPSQBeJAGZeAoA

So even namespace Foo { export declare let x: number; x = 3 } could be explained by the "pretend that somebody actually injects the export somewhere" rule 🙃

[nicolo-ribaudo]

I'm happy to close this issue, with the resolution that the compiled output when there is a export declare let a is only consistent if somebody later actually injects the export that they told TS to pretend it's there.

[Andarist]

It's worth noting that the "inconsistency" you have observed here comes from live-binding and not from a variable/export declarations. That's why in the ESM version that assignment "isn't" transformed. If we assume the binding is magically there then a = 2 alone is OK to maintain the live-bindingness but in CJS and other module formats that transformation is needed