Stronger existence guarantees for `declare`

🔍 Search Terms

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

✅ Viability Checklist

• 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, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• 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 declares 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.

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.