Module annotation for functions that return dynamic ESM imports

[sinclairzx81]

Suggestion

async function dynamicImport(): module { 
   switch(environment()) {
     case 'browser': return await import('./browser/index.mjs')
     case 'node': return await import('./node/index.mjs')
     default: throw Error('Environment not supported')
   }
} 

export { Foo } = await dynamicImport() // use semantics of static import

Hi, I'm not sure if this an issue, feature request or general inquiry, but I am currently having some difficulties importing and exporting class definitions through ESM dynamic imports. I have provided a minimal reproduction of the issue I'm facing at the repository link below. This setup attempts to dynamically ex-export one of many sub-modules based on information returned for the environment at runtime.

https://github.com/sinclairzx81/esm-dynamic-class-export

With the main issues shown in the code below with associated comments.

import { Agent } from '@lib/agent'

async function dynamicImport() {
    switch(Agent.resolve()) {
        case 'chrome': return await import('./chrome/index.mjs')
        case 'firefox': return await import('./firefox/index.mjs')
        case 'node': return await import('./node/index.mjs')
        default: 'Foo: Agent not supported'
    }
}

// Here we dynamically import one of the constructors using the dynamicImport()
// function above. However by importing as `const` we lose the semantics of the 
// class being imported. This means FooConstructor can not be used as a type 
// annotation in the importers implementation.
//
// example:
//
//    import { FooConstructor } from '@lib/foo'
//
//    const foo = new FooConstructor()      // ok
//
//    function test(foo: FooConstructor) {} // error: not a class
//
const { Foo: FooConstructor } = await dynamicImport()

// To address this, we create the actual intended class to be exported by 
// extending the imported FooConstructor const value. Because Foo is 
// exported as a class definition, this enables importers to observe 
// Foo with the semantics of a class.
//
// example:
//
//   import { Foo } from '@lib/foo'
//
//   const foo = new Foo()                   // ok
//
//   function test(foo: Foo) { }             // ok
//
export class Foo extends FooConstructor {}

// However, using this approach results in problems when compiling `@lib/foo` with declarations.
//
// command:
//
//   tsc -p libs/foo/tsconfig.json --outDir target/build --declaration
//
// error:
//
//  libs/foo/index.mts:13:26 - error TS4020: 'extends' clause of exported class 'Foo' has or 
//  is using private name 'FooConstructor'.   
//
//    export class Foo extends FooConstructor {}
//                             ~~~~~~~~~~~~~~

Compiled with the following.

$ tsc -p libs/foo/tsconfig.json --outDir target/build --declaration

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

🔍 Search Terms

esm dynamic export class

⭐ Suggestion

I guess it would be good if TypeScript could provide a way to hint that a functions role is to dynamically import modules and that TypeScript should use the same semantics for static imports. I think the core of the issue currently is that (afaik) the dynamically imported module needs to be imported into a const before re-export.

const { FooConstructor } = await dynamicImport() // FooConstructor is not a class from TS's perspective

export class Foo extends FooConstructor {} // this doesn't seem right 

So I guess one idea I may be to have a module return type annotation that hints to TypeScript that it should treat the functions return type similar to a static import (where imported classes are observed as class definitions, and not typeof definitions). Allowing for something like the following.

async function dynamicImport(): module {} // <-- perhaps an assertion could be added to imply that TS should treat
                                          //     the return value as a kind of static import. This would mitigate
                                          //     the need to export a runtime class definition.

export { Foo } = await dynamicImport()

📃 Motivating Example

See https://github.com/sinclairzx81/esm-dynamic-class-export

💻 Use Cases

To be able to use ESM dynamic imports to implement functionality for multiple JavaScript environments and to have TypeScript treat the dynamic import using the same semantics as a static import.

[thw0rted]

I think you're overcomplicating your example. This Workbench should get the point across, but it already seems to work as expected for me.

I don't understand what the proposed module keyword is supposed to do here. In my example, the compiler successfully resolves the meaning of typeof import ("./a") (and "./f"), and uses that to create an implied return type for the dyn function. It uses top level await to dynamically return one or the other, so the resulting default-export is typed as typeof import ("./a") | typeof import ("./f")`. What would explicit typing add here?

[sinclairzx81]

@thw0rted See links below for minimal reproductions inside the Bug Workbench

Variation 1

Attempts to directly export dynamically imported class. This results in annotation errors at the importer.

Bug Workbench

Variation 2

Attempts to export a class definition by extending the dynamically imported class. This results in errors at the exporter.

Bug Workbench

Variation 3

Uses a different destructuring technique to mitigate the 'Foo' has or is using private name 'FooConstructor' error in Variation 2 (suggested by @thw0rted)

Bug Workbench

[thw0rted]

I think maybe there's just an error in your destructuring syntax? I slightly modified your second example here and it does not have any errors:

const FooConstructor = (await dynamicImport()).Foo;

export class Foo extends FooConstructor {}

[sinclairzx81]

@thw0rted Thanks, that works, but is there a way to avoid the extends ?

export class Foo extends FooConstructor {}

Noting the above definition only exists to have TS see Foo as a class (where it could in theory infer from the import)

[thw0rted]

Unfortunately you're at the limits of my understanding here. (await import("./firefox")).Foo operates entirely in value-space, not type-space, as opposed to the way that import {Foo} from "./firefox" captures both sides. There might be a good way to export it without the extraneous class but you'll have to find somebody with more expertise. Sorry!

[fatcerberus]

(typeof import("./firefox"))["Foo"]?

[thw0rted]

The problem is that only gets the type side, so if you want to export one identifier that can be imported and used like a class (as a type, for new, for static methods, etc) you have to do a bunch of legwork to glue the bits back together, I think. If there's a one-liner to re-export whole the dynamically-imported class, as a class, I couldn't come up with it.

[sinclairzx81]

I think im going to close this issue. Variation 3 seems to be a good viable solution. @thw0rted Btw, thank you very much for the suggestion to destructure using that technique, it's a good one.

I do actually think TS could probably provide a better experience in this regard (dynamic imports are a little non-trivial and still don't understand if the class re-export is an oversight or something planned to be addressed in the future), but as there's a way to dynamically export in this way, this sorta resolves the issue for me this side.

Will close, thanks again!

[darkomtc11]

Is there any way to do it without top-level await?