Suggestion: target specific runtimes instead of JS versions

[XaveScor]

First advantage is target to browser is native for user than target to js version. Don't need to know what each browser support.
Second is ts can transpilate more effective. Some browser can have partially support of next standard. Ts can transpilate unsupported features only.

[DanielRosenwasser]

So you're asking for something like babel-preset-env. I don't really know how many people actually have targets that end up being drastically different from ES5 and ES2015 to be honest, so I'd be open to hearing more feedback.

[eddiemoore]

I'd like to see this in as well, as browsers are adding more features all the time, if we are able to specify the browsers that we are targeting then it will only need to compile what is required.

Would suggest using https://github.com/ai/browserslist as it's pretty much the standard for this, and used by lots of other projects.

Many people are only targeting the last few versions of browsers, or if you are doing a project specifically for Electron then you only really need to target a specific "browser"

Would love to see this happen.

[ericdrobinson]

@DanielRosenwasser

I don't really know how many people actually have targets that end up being drastically different from ES5 and ES2015 to be honest, so I'd be open to hearing more feedback.

Here goes.

---

Background

As a TypeScrpt user, I do not write code that runs on a standards-compliant JavaScript engine. I do write code that runs on one-or-more custom JavaScript engines. I would like TypeScript to warn me when I make use of an API that does not exist in the target engine at compile time, rather than debug the issue when a problem occurs at runtime.

Today, TypeScript's core lib.d.ts file is not standards compliant. It is based on a spec file generated by the Microsoft Edge browser:

browser.webidl.xml: an XML spec file generated by Microsoft Edge.

While there is movement to replace these specs with specs generated from the standards themselves (see [1], [2], [3]), this still leaves us with a type system that will suggest/allow APIs that would cause runtime errors when run in certain targeted engines.

The following image (taken from this comment by @kitsonk) illustrates the issue well:

The numbers reported by that tool when "Specifications" is replaced with "Mozilla Firefox" (as of 2018/09/25):

• 7537 APIs in Microsoft Edge
• 11764 APIs in Google Chrome
• 10225 APIs in Mozilla Firefox
• 5697 APIs in Microsoft Edge ∩ Google Chrome ∩ Mozilla Firefox

As a TypeScript user, it is those 5697 APIs that I want to use. If I venture outside of the bounds of that set of APIs, at the very least I want TypeScript to warn me. That said, it would be even better if TypeScript could support me in that endeavor.

An extra challenge not addressed by the simplicity of that image is that the shape of the intersection in question changes between browser (JavaScript engine) releases. Some releases will add new APIs; some releases will remove APIs. Browsers are a moving target and that is considered as part of this proposal.

Proposal

Provide a new --target-engines compiler option that accepts a set of version-specific engines (e.g. dom.chrome.64) that TypeScript will use to source type information. Entries in this set may be open or closed ranges (e.g. dom.chrome.64+ or dom.chrome.48-64).

(Note: These examples are for illustrative purposes only and are not deeply considered. The Browserslist package may serve as a better source for format inspiration.)

When the --target-engines option is set, the --lib option is ignored.

Usage

When the --target-engines compiler option is set, TypeScript will retrieve the type libraries for each individual engine specified, as well as each engine within the ranges specified. It will then take the intersection (∩) of those libraries and populate the type system with the results.

Example

Specifying the following in a tsconfig.json file:

"target-engines": [
    "dom.ie.8+",
    "dom.firefox.42+",
    "dom.chrome.45+",
]

would restrict the types available in TypeScript's type system to those common across the ranges of the browsers specified.

Engine Guards and Differentiating Engines

Similar to TypeScript's Type Guards, Engine Guards would allow the developer to create scopes within which TypeScript's type system will adjust the available types based on the specified guard. Typically, implementing an engine guard would result in the type system expanding the set of available APIs within the guarded scope.

If a developer wishes to use FancyAPI but only two of the three engines they've specified support it, then they could use an engine guard to provide a scope within which they have access not just to FancyAPI, but the expanded set of all types that the two engines that support FancyAPI support. The developer can say "within this context, I would like access to every type that is available in engines where FancyAPI is supported."

The //@ts-engine-guard Comment

The // @ts-engine-guard comment is a directive to the TypeScript compiler that the following line should be evaluated as an engine guard and not produce a name-not-found/property-does-not-exist error.

An example:

// Types restricted to those supported in EngineA, EngineB, and EngineC.
let url: string = "https://github.com/Microsoft/TypeScript/issues/19183";

// Fetch is unsupported in EngineB. Using it here would cause TypeScript
//  to emit a helpful error.

// @ts-engine-guard
if (window.fetch !== undefined)
{
    // EngineB's type restrictions are removed. This scope now has
    //  access to all types provided in both EngineA AND EngineC.

    fetch(url); // Safe!
}

Note that if a fetch polyfill existed (or was shadowed locally in the given scope) then the engine guard functionality would not be triggered and a warning about the issue emitted. If a fetch polyfill is added after such a check was used as a guard and caused problems via some other API within the block, then the problematic API would replace the check against fetch to maintain the type expansion.

Further, if the guarded API happened to be one that existed only for a sub-range of a specified range of a given engine, then that sub-range would influence the expanded type intersection. This could happen if an API was added in one version and then removed in a later version within the range. Note that this could conceivably help developers running Automated/Continuous Integration systems identify issues resulting from API removal in new engine releases.

Generating Engine Library Files

There are several options for generating engine library files. A few to consider:

• Generate from vendor-specific WebIDL specs. It looks like some vendors (e.g. Google, Mozilla, Microsoft) support WebIDL in some manner.
• For each engine runtime, traverse the type system [as is done by Microsoft's API Catalog].
  • The FAQ claims that the API data is "obtained from enumerating each browser's DOM".
• Generate browser engine libraries from caniuse data or Mozilla's browser-compat-data.
  • Other engines would benefit from support tooling.
• Request engine vendor buy-in and support. Provide vendors with tools to assist them in generating the library files themselves such that it can simply become a part of their build/distribution process.

Distributing Engine Library Files

Distribution of engine library files could (should?) be done via Definitely Typed as is done with normal declaration files.

Beyond Browsers

Browsers aren't the only "JavaScript" (ECMAScript) engines that would benefit from such a system. Applications are frequently developed using embedded JavaScript engines, typically using some version of Chromium Embedded Framework or Webkit/JavaScript Core). Being able to specify a single engine version (e.g. dom.chrome.58) would allow developers to safely use all APIs provided in those platforms without restriction (other than quirks, of course).

A "Complex" Use Case

Another example includes Adobe's Creative Suite applications which support the Adobe Common Extensibility Platform (CEP). CEP extensions run multiple independent ECMAScript engines:

• Chromium Embedded Framework (via NW.js integration)
• Node (via NW.js integration)
• ExtendScript (runs in the host application)
  • Application-specific Extensions - Photoshop, InDesign, Illustrator, and Premiere Pro all provide different APIs in their respective environments.

Broadly, a project can be thought of as having two overarching engines:

1. A specific version of NW.js (Chrome+Node)
2. ExtendScript + Application extensions (e.g. the Photoshop API).

While the ExtendScript language has not seen updates in many years, the application APIs and NW.js integrations change with almost every application release. For developers working in this environment who frequently wish to support more than a single application (or version of an application), it is very desirable to have a programming environment where types are properly restricted to specific, targeted engines/contexts.

In other words, developers could specify dom.aftereffects.13+ and have their type system restricted to APIs consistently available across After Effects 13 to latest. (Such developers would similarly restrict their Node/Chromium versions to those supported by the platform for those contexts as well.)

Generating Libraries for CEP Applications

Adobe provides custom XML files that describe the ExtendScript API with their ExtendScript Toolkit (ESTK). Further, there are mechanisms by which to produce similar XML files for application-specific extensions. A simple conversion step between these files and TypeScript declaration files can be achieved. Any extra tooling would presumably assist in such conversions.

Universal Application Coding

This system could also assist developers writing "universal code" (e.g. with certain Server Side Rendering frameworks). From the Vue.js Server-Side Rendering Guide:

Universal code cannot assume access to platform-specific APIs, so if your code directly uses browser-only globals like window or document, they will throw errors when executed in Node.js, and vice-versa.

With this feature, the TypeScript language services could identify such errors at edit-time, rather than during execution. Further, TypeScript enabled IDEs/editors could be configured to understand such "universal" contexts and only show APIs (autocompletion/IntelliSense) that are supported by the intersection of the target engines in the first place (in the case quoted above, some set of NodeJS versions and some set of Browsers [and their versions]). This would help developers program with greater confidence and fewer bugs.

Wrap Up

At the heart of this proposal is the desire to restrict the type system to resolving only common types from amongst a set of versioned declarations for a single library. While this is most clearly understood in terms of browser support, one could also say "I would like to create a utility that works with every version of jQuery 2.x." TypeScript could take the intersection of the declaration files for 2.0, 2.1, and 2.2 and restrict the type system to only resolve APIs consistently available across those versions.

[MadaraUchiha]

I would definitely like to see this feature in TypeScript. It's incredibly useful in Babel.

[dgoldstein0]

Love this idea! The website I work on compiles to ES5, but practically, we are not shipping a website for ES5 compliant browsers; rather we ship a website that needs to work in a whole set of browsers. Which for me is currently last 2 versions of Edge, Safari, Firefox, Chrome, and IE 11, and a few mobile browsers too. An interesting anecdote here: we recently dropped IE 10 and noticed that our supported browsers now all have support for ES6 Set and Map... but not without some quirks in IE11, so we've forked the standard declarations to make a version that bans the stuff that won't work in IE11, and include our custom declaration file for our typechecking. So we are sort of already hacking our own version of this.

As far as implementation... I think @ericdrobinson gave an excellent in depth proposal. That said, I also think it looks like a lot to implement for a first version. My suggestions:

• make engine definitions - the data that defines which features are available in which browsers - pluggable. Then focus on getting a good canonical set for modern browsers (and servers, e.g. nodejs) and expanding from there; that way snowflakes like Adobe CEP could provide their own if they aren't supported out of the box.
• I also like the idea of supporting some sort of type intersection for joining different engine defintions together. I don't know how this would be best expressed in the language, but if we can figure out a good way for it, then engine declarations are just normal declarations that get fed into an intersection operation.
• ts-engine-guard seems unnecessary to me. At the least, the example given does not seem compelling, as I would expect regular feature detection to just do the trick. E.g. if some targets have window.fetch and others don't, isn't wrapping usage of fetch with if (window.fetch) {...} enough to convince the normal null checks that it exists? Perhaps there is a use case for the proposed ts-engine-guard but I don't find the given one compelling, and think until there is a more compelling one, we should avoid the complexity.

[XaveScor]

@ericdrobinson good proposal. thanks. But "usage" part have a bad idea. JS world already have tool for this problem. Browserlist. We don't need reinvent existing tool.

Next suggestion is compile multiple targets. It is great idea because IE11 has far less APIs. Binary size for IE11 and Chrome/FF/Edge/Safari can vary 2 or more times. Modern browser users can download binary much faster.

[ericdrobinson]

@//ts-engine-guard is About API Scope Expansion

@dgoldstein0 Some questions for clarification:

ts-engine-guard seems unnecessary to me. At the least, the example given does not seem compelling, as I would expect regular feature detection to just do the trick. E.g. if some targets have window.fetch and others don't, isn't wrapping usage of fetch with if (window.fetch) {...} enough to convince the normal null checks that it exists? Perhaps there is a use case for the proposed ts-engine-guard but I don't find the given one compelling, and think until there is a more compelling one, we should avoid the complexity.

Perhaps a closer read would be useful here? The point of //@ts-engine-guard is not to guarantee that window.fetch is usable - to "convince the normal null checks that it exists". Rather, it is about API resolution scope expansion. As explained in the comments in the example script, "Engine B" does not have window.fetch. "Engine B" would never process the code in that if-block. The purpose of //@ts-engine-guard in this case is to act as a hint to the TypeScript language service that you would like it to re-evaluate the API intersection for the following context based on the specified conditions. In essence, the guard would allow the TypeScript language service to resolve (through IntelliSense, say) APIs that both "Engine A" and "Engine C" have without having to consider "Engine B"'s restrictions.

The hint was added under the assumption that evaluating every context against all engines could either be an expensive process or confusing to the user if used globally. That said, if this could be entirely inferred by the TypeScript language service automatically and it simply became something that developers could rely upon, then great!

Does that make sense?

Browserlist is Insufficient for this Proposal

But "usage" part have a bad idea. JS world already have tool for this problem. Browserlist. We don't need reinvent existing tool.

@XaveScor We're not reinventing the existing tool. Some information:

• As it stands today, Browserlist does not work in a useful way with TypeScript. By "useful" I mean with respect to IntelliSense autocompletion features.
• Browserlist is limited to Web Browsers. There are other ECMAScript (JS) environments that Browserlist does not support.
• Browserlist checks for API existence. This proposal goes much, much further in that it would replace the default declaration files (e.g. lib.d.ts) with a set of environment-specific (JavaScript 'contexts', of which Browsers may be one) declaration files that might then undergo an intersection merge. Declaration files aren't just about "existence" as they also provide documentation that systems like IntelliSense use to provide useful information to programmers during autocomplete operations and the like.

Browserlist is a good source for inspiration but using it directly for this feature would not work. This is not a reimplementation but a completely different feature.

Binary Size?

Next suggestion is compile multiple targets. It is great idea because IE11 has far less APIs. Binary size for IE11 and Chrome/FF/Edge/Safari can vary 2 or more times. Modern browser users can download binary much faster.

@XaveScor Can you please expand upon what you mean by "binary"? Do you mean WebAssembly?

[dgoldstein0]

The purpose of //@ts-engine-guard in this case is to act as a hint to the TypeScript language service that you would like it to re-evaluate the API intersection for the following context based on the specified conditions.

Ah that makes some sense.

That said I would love to use browser / server targets even without ts-engine-guard; it feels like a nice add-on rather than a required part of this proposed feature. Perhaps in part because my use case is mostly pure browsers and it's very rare for us to want to write code that won't work universally; I could see it coming more in handy if we have stuff that's more like if (process /* detect nodejs */) {...} else {...} as that's a use case where I could see wanting code to diverge in behavior and acceptable apis to use.

[ericdrobinson]

it feels like a nice add-on rather than a required part of this proposed feature.

Yes, that is true as written. It would be a "more complete" implementation with //@ts-engine-guard or an automatic version. I don't have any specific examples, but the thought was that some features (e.g. Promises) may also imply additional support APIs beyond the root class. With an engine guard feature, all APIs supported by the newly expanded area that support a 'guarded feature' (e.g. APIs that make use of or return a Promise) might also become available.

But, yes, this would be a secondary feature implementation - to be implemented once the core mechanisms of specifying a set of target runtime environments were in place. :)