Type annotation for all exports in the module

[mohsen1]

Search Terms

Export, typed exports, modules, Next.js, Redwood.js

Suggestion

Allow a new syntax From issue #420 that will allow typing all of exports in a module.

export implements {
  default: string
  foo: (bar: boolean) => number
}

export default "Hello world!";
export function foo(bar) { return 1 }

Use Cases and Examples

Increasingly frameworks are using named module exports as a way of organizing their code. For instance Next.js is using named exports to specify things like exported component and functions for fetching data:

import { PageModule } from 'next'

type Post = { title: string };
export implements PageModule<{ posts: Posts[] }>;

function Blog({ posts }) {
  return (
    <ul>
      {posts.map(post => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

export async function getStaticProps() {
  return { props: { posts: [] } }
}

export default Blog

Frameworks relying on named export

• Next.js
• Redwood.js
• Remix.js
• SevlteKit
• StroryBook
• CloudFlare Workers

• please suggest more

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.

Related issues

• Allow a module to implement an interface #420
• Type annotations for default export #13626

[balazsorban44]

You can add Remix to this category

https://blog.remix.run/p/remix-preview

It will export a load function similar to Next.js's getServerSideProps

[kentcdodds]

I didn't notice this issue when I opened: #46942

There are a few more details for use cases and an alternative syntax, but I don't really care too much about the specific syntax. I just want the feature. :) You've got a 👍 from me!

[Rich-Harris]

Adding SvelteKit to the list of frameworks that follows this pattern — this would be hugely beneficial to us as well.

An even better outcome for users would be if modules could be typed implicitly — for example if certain files (either with a particular naming convention or because the framework generates a config that lists them) were known to implement a particular interface, the export implements (or whatever) would be unnecessary (unless you needed to specify type variables). For example a typical SvelteKit endpoint looks like this:

// src/routes/echo.ts
import { RequestHandler } from '@sveltejs/kit';

export const get: RequestHandler = (request) => {
  return {
    status: 200,
    headers: {},
    body: JSON.stringify(request)
  };
}

Converting that to an explicitly typed module...

// src/routes/echo.ts
-import { RequestHandler } from '@sveltejs/kit';
+import { Endpoint } from '@sveltejs/kit';
+
+export implements Endpoint;

-export const get: RequestHandler = (request) => {
+export function get(request) {
  return {
    status: 200,
    headers: {},
    body: JSON.stringify(request)
  };
}

...would only really start paying dividends once you had multiple exports, whereas an implicitly-typed module would provide significant benefits even to people who see the red squigglies but otherwise have no idea what TypeScript is:

// src/routes/echo.ts
-import { RequestHandler } from '@sveltejs/kit';

-export const get: RequestHandler = (request) => {
+export function get(request) {
  return {
    status: 200,
    headers: {},
    body: JSON.stringify(request)
  };
}

[kentcdodds]

Hey @Rich-Harris 👋

I'd also love implicit types based on a convention and the tsconfig-based configuration of that convention (😆). That would be a big benefit for Remix users as well.

I'm concerned that this would stall the feature. If there's some way to have both and start with the explicit that's the future I would prefer personally. I think explicit has a place in the TS ecosystem as well, so both make sense to me. So if we could get the explicit finished and start benefitting from that then work on the implicit that would be super :)

[Rich-Harris]

Indeed. If feature B depends on feature A, it's better to implement feature A first rather than waiting to implement both.

Nevertheless, it's very useful in my experience to understand the rough shape of feature B (and any other dependent features you have in mind) before designing feature A, lest you end up with a design that for whatever reason makes those follow-ups hard or impossible. For that reason it's often worthwhile to include those considerations in the initial discussion.

[GregBrimble]

+1 from Cloudflare Pages as well!

We declare this PagesFunction type in our @cloudflare/workers-types package, and encourage people to include it in their types in tsconfig.json:

{
  "compilerOptions": {
    "types": ["@cloudflare/workers-types"]
  }
}

With support for type-checking of modules, we could declare a PagesFunctions or similar:

export implements PagesFunctions

export const onRequestPost = async ({ request }) => {
  const { name } = await request.json()
  return new Response(`Hello, ${name}!`)
}

export const onRequestGet = () => {
  return new Response("Hello, user!")
}

But this API would do exactly what we'd need! Thanks everyone for suggesting it :)

[geelen]

@Rich-Harris love your idea of implicit naming based on file pattern, imo in tsconfig something like:

{
  "compilerOptions": {
    "exportTypings: {
      "*.svelte.ts": "@sveltejs/kit::Endpoint"
    }
  }
}

Maybe with something less c++-y than :: but you get the idea.

I think <module-name>.<exports-types>.ts could become a fairly common convention. But equally, for all-one-type projects you could just set *.ts to be any type you like, or for Pages we could set a subdir like:

"functions/**/*.ts":"@cloudflare/workers-types::PagesFunctions"

I'm liking this idea more and more...

[orta]

Notes from the last time we talked about this: #38713 and some of the possible consensus #420 (comment)

[kentcdodds]

Thanks @orta. Looks like there's community interest and team appetite for the idea. So where do we go from here? How do we push things forward?

[shilman]

Mentioned in other threads on the topic, Storybook's Component Story Format also heavily relies on this pattern, where the default export includes metadata about a component, and each named export is a component example, or story:

import { Meta, Story } from '@storybook/react';
import { Button } from './Button';

const meta: Meta = {
  title: 'Demo/Button',
  component: Button;
};
export default meta;

export const Primary: Story = () => <Button primary>Primary</Button>;

export const Disabled: Story = () => <Button disabled>Disabled</Button>;

In our case, users also want more type safety and better autocompletion than the general types provide, so they will parameterize them by the props of the component that is being documented. So at the top of each file they might make specific versions at the top of each file:

type Meta = ComponentMeta<typeof Button>;
type Story = ComponentStory<typeof Button>;

const meta: Meta = { ... };
export default meta;

export const Primary: Story = // ...;

Ideally a solution would be powerful enough to express this kind of specificity.

So this would fit the bill in each file:

export implements CSF<typeof Button>;

But this proposal in its current form would not:

"src/**/*.stories.tsx":"@storybook/react::CSF"

A combination of the former (for users who want more control) and the latter (for convenience) would be amazing. 💯

[hollandThomas]

Nevertheless, it's very useful in my experience to understand the rough shape of feature B (and any other dependent features you have in mind) before designing feature A, lest you end up with a design that for whatever reason makes those follow-ups hard or impossible. For that reason it's often worthwhile to include those considerations in the initial discussion.

In this spirit, I just wondered about the following as a possible future extension of this proposal:
A module that implements named exports may infer the types of any imports that originate from the same module that provides the named export interface.

I am not sure about the syntax and how to implement this but maybe someone can come up with something smart.

Taking Remix as an example, this would enable e.g.

// Internal Remix code
interface EntryRouteModule<LoaderData = Response | AppData> {
  CatchBoundary?: CatchBoundaryComponent;
  ErrorBoundary?: ErrorBoundaryComponent;
  default?: RouteComponent;
  handle?: RouteHandle;
  links?: LinksFunction;
  meta?: MetaFunction | HtmlMetaDescriptor;
  action?: ActionFunction;
  headers?: HeadersFunction | { [name: string]: string };
  loader?: LoaderFunction<LoaderData>;
}

Then, in a route

// routes/posts.tsx
import type { EntryRouteModule } from 'Remix'
import { useLoaderData } from 'Remix';

type Post = { title: string };
export implements EntryRouteModule<{ posts: Post[] }>;

// this is typed correctly because of the line above
export const loader = async () => {
  return {
    posts: await postsQuery()
  }

export default function Blog() {
  // Have TypeScript figure this out automatically somehow:
  // useLoaderData now knows that `LoaderData === Post[]`. There is no need to `useLoaderData<Post[]>`
  const { posts } = useLoaderData()

  return (
    <ul>
      {posts.map(post => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

This is a slightly different use case than the one outlined in the initial Next.js example, where the inference of posts === Post[] does not rely on any additional imports.

import { PageModule } from 'next'

type Post = { title: string };
export implements PageModule<{ posts: Post[] }>;

// Here, `posts` is being inferred correctly as per proposal
function Blog({ posts }) {
  return (
    <ul>
      {posts.map(post => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

export async function getStaticProps() {
  return {posts: []}
}

export default Blog

[mohsen1]

@DanielRosenwasser just let me know that it's possible to import self to simulate what we're asking for. Just in case you're curious this is how it would look like in Next.js for instance:

// @file pages/posts.tsx

import React from 'react';

// This can be more complex to cover getServerSideProps etc
type InferPropTypes<T> = T extends { getStaticProps: () => Promise<{ props: infer U }> }
  ? U
  : never;

import * as self from './posts';
const Posts: React.FC<InferPropTypes<typeof self>> = ({ posts }) => {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  );
};

export async function getStaticProps() {
  const posts: Array<{ title: string }> = [];
  return { props: { posts } };
}

export default Posts;

This is less automatic than typing all exports using something like export implements but it's possible to do today.

[ivanhofer]

I would also love to see such a feature in TypeScript.
Probably every project that has file conventions would benefit from such a feature. My project typesafe-i18n could also benefit from it.

I don't think that there is a new syntax needed. What if TypeScript could use a .d.ts file to check what variables and exports a file should have?

Currently e.g. a file.d.ts would tell every other file that imports file.js what values it exports and what shape those variables and functions have. But in that file.js no type-check happens. The file.js could also export something totally different and TypeScript would not throw an error:

file.d.ts

declare export someVariable: number

file.js

export someVariable = 'Hello'

So if TypeScript would use the information from the d.ts file to check if the .js file was implemented correctly, we could have a solution to the typed export problem. Of course this should also work with .ts files.

With a solution like we can see in SvelteKit where types are generated and then linked with the real source files via the rootDirs compiler option, those .d.ts files could be generated without adding declaration files inside the actual src folder.

Having those checks enabled would probably break a few existing code bases if they manually create .d.ts files. Or actually they would get notified that they defined something wrong ;)
But this is a topic for a later discussion. I just want to propose an alternative to this thread.

[Rich-Harris]

That's a stroke of genius @ivanhofer — it solves the problem very elegantly. I've often wondered why .d.ts files don't already work that way.

My conclusion was that TypeScript probably assumes that foo.d.ts is generated from foo.ts and as such represents a snapshot of its declarations the last time tsc was run, but even though emitting .d.ts files as siblings to their inputs is the default behaviour if "declaration" is true and "declarationDir" is unset, I've never seen a case where it's actually desirable.

I wonder if a new compiler option like "selfDeclaration": true could solve this problem?

[ivanhofer]

Yes usually the .d.ts should be genereated from the actual source file. But there exist a lot of libraries that are written in plain JavaScript and types are added by manually creating the .d.ts file or there are also all the @types packages were the types come from a 3rd party.

Using the declaration files to type the corrresponding source file makes only sense for your own source files (everything that matches "include" from your tsconfig.json).
The more I think about this topic, the less I understand the skipLibCheck option. Why should I want TypeScript to check files from my node_modules folder I don't use in my code? (maybe I also don't fully unserstand what it really does)

A compiler option where someone could opt-in into the .d.ts typechecking behaviour would be a good solution. I could also immagine this beeing one of the "strict" options since it potentially warns you about big mistakes in your code base.

Such a feature would also make it possible to have "scoped global types" (not sure how to call them). A concrete example for SvelteKit would be the GET type you can use to type endpoints. Currently you have to manually import the type and also be sure you import the generated type and not the generic type. With the .d.ts file the GET type could be "just there". No need to import it. Like the interface HTMLElement can be used everywhere without importing it directly. But in this case the type would be scoped to a single file.

[camjackson]

@ivanhofer With your suggested solution, would that I mean I need to create a .d.ts file for every module that I want to type? So with Remix as an example, for every single one of my route .ts files I would need to create a corresponding .d.ts file, all of which would have identical contents (seeing as all route modules follow the same pattern)?

[ivanhofer]

@camjackson I haven't used Remix yet, so I don't fully know how route files work there. I just looked at some examples in the comments above.
If you want all your route files beeing typed without a user having to import the correct type, then with the solution I have suggested probably yes.
But those files don't have to contain a dozen of lines. I can imagine having a file where you define how a route should look like and then just writing export * from '@framework/common-route' for all other files.
Having those files located in your normal src folder is probably not a good user experience. I really like the solution of auto-generating and hiding those files via the rootDirs option like SvelteKit does.

[geelen]

With your suggested solution, would that I mean I need to create a .d.ts file for every module that I want to type?

Surely there's a halfway point here? I think @ivanhofer's thought of using .d.ts as an assertion format is absolutely genius, but I agree having to have one-per-input file is cumbersome. So why not apply it a different way?

// tsconfig.json
{
  compilerOptions: {
    declarationValidations: {
      "**/*.route.ts": "@remix/type-assertions/route.d.ts",
      "**/*.model.ts": "./models/_type.d.ts"
    }
  }
}

What's nice is that you could also do what @ivanhofer's suggesting if you allow a bit more syntax in the tsconfig:

declarationValidations: {
  "src/**/*.ts": "src/$1/$2.d.ts",
  // or, if file-by-file declarations were being generated in a hidden directory:
  "src/**/*.ts": "./svelte/decls/$1/$2.d.ts"
}

This, to me, feels shippable & ergonomic. Any use-cases where it breaks down?

[camjackson]

So instead of exporting each function individually a framework could choose to require to call a provided function that allows to check for type errors.

I suggested this on the Remix discord and it was explained to me that it won't work. In Remix, route modules include both frontend and backend code, and the framework needs to be able to tree shake / code split the code apart. So its conventions must be export-based, they can't be fields of a single object. That's why this proposal is needed.

[ivanhofer]

Surely there's a halfway point here? I think @ivanhofer's thought of using .d.ts as an assertion format is absolutely genius, but I agree having to have one-per-input file is cumbersome. So why not apply it a different way?

I agree, having a config option to choose the behaviour where .d.ts files get applied would be an extension to the solution that makes sense.
The reason why I proposed this soultion with exactly that state is: for me it looks like it is already implemented in the code base. Just not enabled. I don't want to offend any TypeScript maintainer but for me (without ever looking at the code) it just feels like removing an if statement somewhere or adding two lines of code to enable that feature.

I suggested this on the Remix discord and it was explained to me that it won't work.

Well, from a technical perspective Remix could also transform the file and split it up into distinct files during the build process. Maybe a bit overkill, but it could already work with the current TypeScript version.
"Where there is a will, there’s a way" :)

[tigerabrodi]

This would be HUGE 🔥

[nickmccurdy]

This could also be helpful for globals that are only exposed in certain files, like Node environment variables and test frameworks.

[mohsen1]

3 questions:

1. should we allow multiple export implements and treat it like an interface extending multiple other interfaces?
2. if exports is acting like a type identifier then should typeof exports be a valid syntax?
3. Are you accepting pull requests for this?

[kentcdodds]

As an interested user, here are my opinions:

1. Maybe? Personally I'd just do export implements Type1 & Type2
2. Hmmm... I don't know what use cases that would be useful for 🤔
3. I hope they are!

[slorber]

Next.js 13 solution to mitigate for the lack of this feature (+ more):

• TypeScript language service plugin: https://github.com/vercel/next.js/blob/canary/packages/next/server/next-typescript.ts
• Demo: https://twitter.com/delba_oliveira/status/1592209522281439232

[mohsen1]

@kentcdodds typeof exports can be useful to export the type of all exports in a file for some use:

export const foo = 1
export const obj: { bar?: string } = {}

export type Exports = typeof export; // { foo: number; obj: { bar?: string } }

I don't have an immediate use case for it but I'm sure this can be useful

[antl3x]

Put this at your module file and __MODULE_TYPE_CHECK__ will do the job.

File: myModule.ts

/* myModule.ts */

/* ------------------------------- Type Check ------------------------------- */

type _myModule = typeof import('./myModule');
const __MODULE_TYPE_CHECK__: MyModuleInterface = {} as _myModule;

Ugly? Yes, but it works.

If your module does not export const ... and does not respect your interface, you will receive a type error.

There is no cyclical-dependency since the import is "garbage collected" and is not transpiled.

[kentcdodds]

Handy trick to help error if your exported types are wrong. However, it doesn't help with auto-complete nor will it report errors in a convenient location.

[antl3x]

Handy trick to help error if you're exported types are wrong. However, it doesn't help with auto-complete not will it report errors in a convenient location.

Not ideal, but for auto completion:

const MODULE: MyModuleInterface = {
    someProperty: ...,
    someMethod(param) { }
}

export const someMethod = MODULE.someMethod

or

const MODULE: MyModuleInterface = {
    someProperty: ...,
    someMethod(param) { }
}

export const { someProperty, someMethod } = MODULE;

[ggoodman]

I'd like to add another use-case for this feature. We use monaco-editor and its typescript language services to provide an in-browser, IDE-like editing experience for Auth0 Actions. Actions are CJS modules that we execute in a 'serverless' environment on behalf of our customers at specific lifecycle events in our auth pipelines. It is conceivable that we could move to EJS modules if that would be the gateway to having access to this feature if it came to TypeScript.

Currently, we rely on seeding Actions with skeleton templates that use jsdoc annotations to power the intellisense. This works but means that the majority of the template is consumed by non-functional boilerplate. Supporting typed modules such as in this proposal would give us (and I suspect all other serverless-like platforms / tools) an improved way to deliver a more robust and elegant DX for our customers / users.

[jamiebuilds-signal]

One syntax option:

export {} satisfies Type

This would be a shorthand for typing exports of the entire module:

export {} satisfies RemixRoute<{ bookId: string }>

export function action({ requesr }) // Did you mean "request"?
export function loader({ params }) {
  params.bookID // Did you mean "bookId"?
}

It's important to keep in mind that the {} in export {} is not an object literal, and can contain things like export { Component as default }

One benefit of this would be that you are also typing the syntax that marks a module as a module, and TypeScript could emit it export {}

[ggoodman]

One thing I don't like so much about the approaches that involve new syntax is that it requires author of the subject module to opt in. From what I understand of the use-cases that motivate this issue, the types for module exports are not optional. Instead, these types are being enforced by an external factor or framework. I think it would be interesting if the enforcement could thus come from outside too.

From that angle, I wonder if it might be interesting to think about a design where these module-level type signatures are 'attached' to files through the tsconfig.json and equivalent language service constructs.

A straw-man idea follows. Here, we can define a set of mappings from files globs to a module specifier and exported symbol that defines the expected shape of the matching files' exports.

{
  "exportTypes": [{
    "include": ["**/pages/*.ts"],
    "typePath": "@framework/types",
    "typeName": "PageExports",
  }],
}

In other words, any file matching the glob **/pages/*.ts would have the signatures of its exported symbols checked against the PageExports type exported from the @framework/types module. The type checker and language server would be able to enforce the types at compile-time and suggest them at authoring time, respectively.

The side-benefit is that affected files no longer need to include superfluous syntax to benefit from this feature. Many frameworks area already providing default tsconfig.json settings from which applications extends so I could imagine this slotting nicely into that sort of setup.

[kentcdodds]

I like that. Though in Remix at least, you can very dynamically define what files count as routes so I would like an additional capability to define a type for the exports.

I'm a fan of what @jamiebuilds-signal suggests with the satisfies keyword.

[camjackson]

From that angle, I wonder if it might be interesting to think about a design where these module-level type signatures are 'attached' to files through the tsconfig.json and equivalent language service constructs.

I see the benefit of that, especially the idea of it being enforced from the outside, because it's a framework-level expectation. My concern is that it makes the code much less discoverable. To me it's very important that a new developer can look at a piece of code, without any context, and be able to figure out what it does by following the breadcrumbs.

I prefer an API that explicitly establishes a link that says "this code that you're looking at implements this interface", and then you can click through to see what that interface is. As opposed to it being configured somewhere else, with no way of like, naturally discovering it from the code in question. It becomes something that you just have to know.

[ggoodman]

I prefer an API that explicitly establishes a link that says "this code that you're looking at implements this interface", and then you can click through to see what that interface is.

That's a great point. Perhaps the relevant comparison here is what you have defined in your tsconfig.json for the compilerOptions.lib option. This is something defined on the 'outside' that affects which ambient types will show up. For use-cases where you want to be explicit, you can opt into a triple-slash directive to make the dependency explicit.

[btoo]

allowing ambient module declarations to specify relative module names as an alternative to using tsconfig could be a more intuitive and/or powerful way to achieve this by way of using typescript (especially satisfies) rather than json

import { type RemixRoute } from 'remix';

declare module './MyRoute' {
  export {} satisfies RemixRoute<{ bookId: string }>
}

and this could work with wildcards as well

import { type PageExports } from 'next';

declare module './**/pages/*.ts' {
  export {} satisfies PageExports
}

a more drastic change, module declarations themselves could satisfy types

declare module './MyRoute' satisfies RemixRoute<{ bookId: string }>

declare module './**/pages/*.ts' satisfies RemixRoute<{ bookId: string }>

[ggoodman]

Oh nice, @btoo that's very clever!

[mohsen1]

I like export {} satisfies Type because satisfies works better than implements in this case. The only thing is the emitted export {} in runtime space that might not be desired.

[EloB]

@btoo Is that doable at the moment or is that a a feature request?

[mariusGundersen]

I would really like this too, and would be happy with export {} satisfies Type, although some magic with tsconfig and wildcard paths would be very useful.

A workaround while we wait for this feature is to import the module into itself and then check that what is imported satisfies some type. For example:

// myModule.ts
export default function () {
  return "test";
}

import * as __SELF__ from './myModule';
__SELF__ satisfies { default(): string };

This is quite cumbersome though, since you need to specify the name of the file in the file, and you get the error in the satisfies line, not on the export line.