microsoft / microsoft/TypeScript

Stronger existence guarantees for `declare`

Offen
#62,290 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Awaiting More Feedback Suggestion
Vorherrschende Sprache
Go
Sterne
111k
Forks
14.3k
Ø Merge
2 T. 4 Std.
Gemergte PRs (30 T.)
132

Beschreibung

### 🔍 Search Terms

"declare", "exist", "extern equivalent", "generate"

### ✅ Viability Checklist

- [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [x] This wouldn't change the runtime behavior of existing JavaScript code
- [x] This could be implemented without emitting different JS based on the types of the expressions
- [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [x] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

### ⭐ Suggestion

Some sort of `extern` keyword, similar to `declare` but with stronger existence checks, intended to remove the need to generate "ephemeral" code (e.g., making build information available at runtime) at least once to get the editor to not complain while still maintaining type safety.

### 📃 Motivating Example

In, e.g., C/C++, one way to inject build information into a final build of a binary is simply to write a header to let the editor know about it and then generate a file containing the data at build time. This is safe, since in C/C++ the compiler will ensure that `extern const char *version;` is backed up by an actual `const char *version = "";` somewhere else, otherwise the build will fail. This process can be more manual (e.g., handwrite the header, handwrite a script to generate the file) or somewhat automated (e.g., autoconf, CMake).

In TS, the equivalent of header files is `.d.ts` or `declare` statements. However, it is a promise that doesn't get checked, which, to my understanding, is to allow type checking of libraries not written in TS, without having to run the entire library through `tsc`, which might not be possible anyway (e.g., closed source minified scripts at a CDN).

Since the TS compiler (currently) doesn't perform that check, my options are:
- Remove the `.d.ts` "header" and require the file to be generated before opening the project in an editor to avoid errors about importing a non-existent file. Probably the simplest way to go, but this sacrifices in ergonomics.
- Find some way to let a `.ts` override a `.d.ts` file. Probably breaks some existing use case, thus not desirable.
- Perform the check manually, e.g., in addition to running `tsc`, write a script that uses the TS Compiler API to parse `.d.ts` files and ensure it has a matching `.ts` file, and that the stuff the "header" `export declare`s are actually what they say they are. This is the rabbit hole I've been going down.
- Find some other way to express "I promise this thing will exist at build time, and thus its type can be checked later" in TS. Currently, `.d.ts` only expresses "I promise it will exist at runtime", but it has no way to perform a build time check.

### 💻 Use Cases

1. _What do you want to use this for?_ Generating ephemeral but important information (e.g., build information), or otherwise ensuring something exists when it is possible to check, i.e., it is expected to exist at build time, even if not all the time.
2. _What shortcomings exist with current approaches?_ The check must be peformed manually (complex plumbing to get the compiler to do something it already can do, but doesn't) or not at all (sacrificing in ergonomics, as it requires generation to be run, even if the results are instantly stale, just to satisfy the editor and type checker).
3. _What workarounds are you using in the meantime?_ Running the check manually.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

No source file or test is named. Start by reviewing how TypeScript currently handles declare statements and .d.ts files, then compare that behavior with the listed Compiler API workaround; the work would need a settled design for stronger build-time existence checks without changing emitted JavaScript.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript, typescript
Bereich
compilers
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.