Support/ignore export as namespace TypeScript syntax

[niklashigi]

Recently I've come across multiple packages which use the (admittedly poorly documented) export as namespace syntax in their declaration files to declare that they provide both CommonJS exports and a global namespace object. Searching DefinitelyTyped alone brings up 706 occurrences of this pattern.

When bundling a script importing one of these packages ESBuild reports the following error:

✘ [ERROR] Unexpected "as"

    node_modules/@types/mapbox__polyline/index.d.ts:15:7:
      15 │ export as namespace polyline;
         ╵        ~~

It seems like ESBuild simply doesn't know the export as namespace syntax yet, so the as keyword is flagged as unexpected in that context.

Proposal

Since (as far as I know) ESBuild only supports actual module formats (and not global namespace objects), I think it would be a good enough solution to just completely ignore that line. Modules containing it would then be treated solely according to their remaining export declarations.

[magic-akari]

It is weird.
IIRC, esbuild doesn't read .d.ts.

[niklashigi]

@magic-akari

IIRC, esbuild doesn't read .d.ts.

I thought so too, but this comment from the changelog seems to suggest the opposite.

[evanw]

You aren't supposed to feed esbuild .d.ts files, so esbuild shouldn't ever even see them in the first place. However, esbuild sometimes ends up seeing them, so it does still try to parse their different syntax to avoid build errors. But the syntax is parsed and discarded because .d.ts files only contain type definitions (at least they are supposed to be used that way) and esbuild ignores all type definitions. I can change esbuild to parse and ignore this code.

[niklashigi]

Thanks for the help @magic-akari and @evanw!

I've spent some more time looking into this issue and realized that it was partly caused by the following setting in my project's tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@mapbox/polyline": ["node_modules/@types/mapbox__polyline/index.d.ts"]
    }
  }
}

I initially set this up to work around an issue with TypeScript's experimental NodeNext module resolution mode which seems to have been fixed in the meantime. What I didn't know at that time was that ESBuild respects the paths option as well but for resolving actual source files.

Maybe the real fix here isn't to add support for export as namespace, but instead to ignore any paths entries ending in .d.ts because those are only added to fix typing issues. 🤔

I've created a little reproduction repo (with regular TypeScript module resolution because that doesn't seem to be part of the issue) here which has two scripts (bundle and bundle:paths) which bundle the index.ts file once with and once without the paths option.

[magic-akari]

Maybe the real fix here isn't to add support for export as namespace, but instead to ignore any paths entries ending in .d.ts because those are only added to fix typing issues.

agree with you.