Stronger existence guarantees for `declare`

[500-internal-server-error]

🔍 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.

[RyanCavanaugh]

I don't quite understand the scenario here; some samples might be illustrative.

In the analogous situation in C++, the missing extern target is detected by the linker, but TS doesn't have any step corresponding to linking. One could imagine writing something that did the same validation as a linker, though - something that had information as to whether a given .d.ts file was authoritative (e.g. lib.dom.d.ts) vs speculative (userland should-be-there.d.ts)

[500-internal-server-error]

some samples might be illustrative

Build info injection just happens to be what I'm currently working on (SO question here), but there's probably more uses I haven't thought of yet. Perhaps library interfaces could make use of this too, to ensure its JS and .d.ts does not drift apart, if for some reason it does not use tsc to generate its TS types.

One could imagine writing something that did the same validation as a linker, though

That is what I did for the moment, but it would be nice if tsc could do it for me. It just lacks a way to differentiate between the user saying "I promise it will exist, fail the build if it doesn't, because it should exist" (C/C++ extern can only do this) and "I promise it will exist, but I know it can't be checked, so just trust me and never fail the build over it" (TS declare can only do this).

something that had information as to whether a given .d.ts file was authoritative (e.g. lib.dom.d.ts) vs speculative (userland should-be-there.d.ts)

My suggestion is to duplicate the existing declare keyword into perhaps, e.g., extern. The former deals with cases where it cannot be checked (e.g., lib.dom.d.ts), while the latter deals with cases where the user knows it can be checked (e.g., should-be-there.d.ts).