[Feature Suggestion] File satisfies interface

[jeengbe]

Suggestion

🔍 Search Terms

File implements interface, file satisfies, file interface

✅ 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 behaviour 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.

⭐ Suggestion

A way to declare the export signature of a whole file.

Consider, for instance, NextJS pages. Every page must default-export a React Component that satisfies a certain type and may export additional methods, such as getStaticProps. Currently, every export in every file must be explicitly annotated, which is repetitive and error- and inconsistency-prone.

Instead, (on a per-file-basis?; with glob src/pages/**/*?) exports for the entire file can be declared at once, which comes with the added benefit of automatic type inference for parameters, return types etc. for exported stuff.

📃 Motivating Example

When writing pages for NextJS, annotate page files with

/// <exports satisfy="next#NextPageExports" />

// Return type automatically checked
export default () => { ... };

// Parameters automatically inferred
export const getStaticProps = (ctx) => { ... };

---

💻 Use Cases

Many systems (both backend and frontend) use a modularized approach for declaring essentially anything. Consider a CMS whose individual components are found under something like:

└── src/
    └── components/
        ├── Box.tsx
        ├── Textarea.tsx
        ├── FancyWhatnot.tsx
        └── index.ts

A component can be described with the following interface:

interface CMSComponent {
  ID: string;
  description?: string;
  render(...): ...;
  renderEdit(...): ...;
}

with the index file re-exporting components with

// src/components/index.ts

import * as Box from "./Box";
import * as ... from "./...";

export interface CMSComponent {
  ID: string;
  description?: string;
  render(...): ...;
  renderEdit(...): ...;
}

Box satisfies CMSComponent;
// ^^^ Property 'renderEdit' is missing in type '{ ID: string; render: (...) => ... }' but required ...
... satisfies CMSComponent;

export {
  Box,
  ...,
};

The X satisfies CMSComponent is currently the best way to check the exported types. The problem of this is that if a component were, for instance, missing props, the error would be thrown in the wrong place. It would be the file that exported properties incorrectly, not the index file that used a file incorrectly.

With this proposal, an incorrect file would throw an error something like the following:

// src/components/Box.tsx

/// <exports satisfy=".#CMSComponent" />
//  ^^^ This file does not satisfy its export types. Property 'renderEdit' is missing in type '{ ID: string; render: (...) => ... }' but required ...

export const ID =  ...;

export const render = (...) => { ... };

Consider a server-side project, in which such an index file may not even exist, with files being imported dynamically. Here, the user would need to make sure that all files would be set up correctly to not run into runtime errors.

With some way to declare to declare glob-based export patterns, this could be prevented entirely:

// src/components/index.tsx

/// <exports satisfy="#CMSComponent" in="./**/*" />

export interface CMSComponent {
  ID: string;
  description?: string;
  render(...): JSX.Element;
  renderEdit(...): ...;
}

[MartinJohns]

Sounds like a duplicate of #38511.