Feature Request: Make ES module exports conform to an interface using triple slash directive

Search Terms

ESM, ES module, EcmaScript Module, Interface, Exports, triple slash directive, module

Suggestion

I want to be able to enforce and ESM's exports to conform to an interface.

Here's an ESM that exports some values:

This ESM is going to be consumed by some system; the ESM acts as configuration for that system.

The system could expose interfaces/types for all possible exports, and users apply them manually:

But this is manual work, and thus error-prone.

I propose to be able to do:

The exact syntax TBD.

Adding

/// <exports name="ConfigInterface" from="system-that-needs-configuration" />

will tell typescript about which interface the ESM exports should adhere to and where to find it.

If this is implemented in a triple slash directive this can also work for non-ts files.

Use Cases

I want users of storybook to be able to configure it with ease using modern code.
CommonJS isn't tree-shake-able, which is important to us. There's a pretty detailed RFC for this feature for storybook here: https://docs.google.com/document/d/15aAALZBl0GTBEKgJN219ebzJ8LUJf2TVJ3hQdkNdLvQ/edit#

Tools like babel, eslint & webpack currently are or can be configured using CommonJS modules; as the ecosystem for ESM is improving, being able to add an interface to an ESM becomes really useful.

Tools could start using ESM for configuration more, which has clear benefits over CommoNJS.

Examples

Here's a config file that is annotated with the triple slash directive:

Here's the interface that's being referred to:

This should warn the user that logLevel = 'any' is not a valid value.

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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

No source file or test entry point is named. Start by reviewing the proposed triple-slash directive and the ESM export/interface examples; done would require an agreed syntax and validation that reports invalid exports such as logLevel = 'any'.