microsoft / microsoft/TypeScript

Support for all type features in declaration files.

Open
#35,822 29 comments 86 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Awaiting More Feedback Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

I'm on TS 3.7.3 at time of writing this.

It seems like this issue should simply be focused on and fixed before continuing to add more and more features to the language and widening the source vs declaration gap.

This is quite a problem!

Search terms

"typescript declaration file limitations"
"has or is using private name"
"exported class expression may not be private or protected"
"Property 'foo' of exported class expression may not be private or protected. ts(4094)"
"Return type of exported function has or is using private name 'foo'. ts(4060)"

Related issues (a small fraction of the results on Google) in no particular order:

Workaround

One way to work around all of the above issues, for libraries, is to have library authors point their types field in package.json to their source entrypoint. This will eliminate the problems in the listed issues, but has some big downsides:

  1. If a downstream consumer of a library without declaration files (f.e. without dist/index.d.ts) but with types pointing to a source file (f.e. src/index.ts) then if the consumer's tsconfig.json settings are not the same as the library's, this may cause type errors (f.e. the library had strict set to false while being developed, but the consumer sets strict to true and TypeScript picks up all the strict type errors in the library code).
  2. If skipLibCheck is set to true, the consumer project's compilation will still type-check the (non-declaration) library code regardless.

With those two problems detailed, if you know you will be working in a system where you can guarantee that all libraries and consumers of those libraries will be compiled with the same compiler (tsconfig.json) settings (i.e. similar to Deno that defines compiler options for everyone), then pointing the package.json types field to a source file (because declaration output is not possible) is currently the workaround that allows all the unsupported features of declaration files to be usable. But this will fail badly if a library author does not know what compiler settings library consumers will have: everything may work fine during development and testing within external examples, but a downstream user will eventually report type errors if they compile their program with different settings while depending on the declaration-less libraries!

Suggestion

Support for all type features in declaration files.

Please. 🙏 I love you TS team, you have enabled so much better code dev with TypeScript. ❤️ 😊 TS just needs declaration love for support of all features of the language.

Some work is being done, f.e. https://github.com/microsoft/TypeScript/issues/23127, but overall I feel that too much effort is being put onto new language features while declaration output is left behind.

This creates a poor developer experience when people's working code doesn't work (the moment they wish to publish it as a library and turn on declaration: true).

I hope the amazing and wonderful TS team realize how frustrating it may feel for someone to work on a project for months, only to end with un-fixable type errors the moment they want to publish the code as a library with declaration: true, then having to abandon features and re-write their code, or try to point package.json "types" to .ts files only to face other issues.

I wish every new feature of the language came paired with working tests for equivalent declaration emit. Can this be made a requirement for every new language feature, just like unit tests are a requirement?

Use Case

Use any language feature, publish your code, then happily move along, without facing issues like

src/html/DeclarativeBase.ts:25:10 - error TS4094: Property 'onChildSlotChange' of exported class expression may not be private or protected.

25 function makeDeclarativeBase() {
            ~~~~~~~~~~~~~~~~~~~

src/html/WebComponent.ts:32:10 - error TS4060: Return type of exported function has or is using private name 'WebComponent'.

32 function WebComponentMixin<T extends Constructor<HTMLElement>>(Base: T) {
            ~~~~~~~~~~~~~~~~~

I worked hard for months to get the typings in the above code working, then I turned on "declaration": true and TypeScript said "today's not the day!".

I hope you the team can see that these issues are a pain, and realize the need to bring declaration emit to parity with language features and not letting the gap between language features and declaration output widen.

Examples

The issue that sparked me to write this was https://github.com/microsoft/TypeScript/issues/35744.

In that issue there's an example of what implicit return types might look like:

export declare function AwesomeMixin<T extends Constructor>(Base: T) {
  type Foo = SomeOtherType<T> // only types allowed in here.
  
  // only special return statements allowed, or something.
  return declare class Awesome extends Base {
    method(): Foo
  }
}

We'd need solutions for other problems like the protected/private error above, etc.

Of course it'll take some imagination, but more importantly it will take some discipline: disallow new features without declaration parity.

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No repository files, tests, or implementation entry points are named. Start by narrowing the request to a specific declaration-emit limitation, such as TS4094 or TS4060, then identify the relevant compiler behavior and define declaration-output tests that demonstrate parity for that feature.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.