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

[ndelangen]

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.

[orta]

Ideally the answer would work in both JS and TS files, a current technique for applying types to these sorts of config files is to use JSDoc types in a JS file:

/** @type import("webpack").Configuration */
module.exports = {
    entry: "./src/app.ts",
}

That only works when you have a single object to export (and doesn't work with the splitting constraints )

[strogonoff]

In my case, I want to be able to allow users of a framework (in early development stages) to specify configuration in “Django style” by simply declaring (exporting) some constants. It would actually be better than with Django, since many configuration errors would be eliminated at compile time thanks to typing.

Framework could then take control, import settings as needed and rely on particular exported names having specific types. Meanwhile, declarative configuration code would be more straightforward to read and reason about compared to, e.g., exporting one big object of complex type with all configuration settings at once (my current temporary way of doing it), or inverting control and calling framework initialization functions.

I wish this was possible without the triple-slash magic, but I can see that TS doesn’t offer any other options syntax-wise.

[clshortfuse]

Setting a @type on module.exports only works for CommonJS, but not ES Modules.

If @module [[{<type>}] <moduleName>] JSDoc syntax were supported, that would solve the issue.

See example at: #30744 (comment)

[fregante]

I was thinking that declare module would do this, but no

declare module './components/*' {
	export const logLevel: 'silent' | 'error';
}