René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Proposal: Granular Targeting","articleBody":"This proposal is based on a working implementation at:\nhttps://github.com/yortus/TypeScript/tree/granular-targeting\nTo try it out, clone it or install it with `npm install yortus-typescript`\n## Problem Scenario\n\nThe TypeScript compiler accepts a single `target` option of either `ES3`, `ES5` or `ES6`. However, most realistic target environments support a mixture or ES5 and ES6, and even ES7, often known in advance (e.g. when targeting Node.js, and/or using polyfills).\n\nUsing TypeScript with target environments with mixed ES5/5/7 support presents some challenges, many of which have been discussed in other issues. E.g.:\n- (#4389) Support compile targets between ES5 and ES6\n- (#4168) Normalize our lib files by compiler settings\n- (#3215) New APIs added to lib.d.ts may break client codes. Allow duplicated members in interfaces? Make lib.d.ts overridable?\n- (#3005) Using ES6 type default library when targetting ES5 output\n- (#2695) for-of does not work with DOM collections when target is ES6\n- (somewhat related: (#2481) Create DOM-Level specific dom-version.d.ts)\n\nIn summary:\n- The default lib either includes all ES6 types and properties, or none of them.\n- Specifying `--noLib` and/or manually maintaining `lib.b.ts` files brings other problems:\n  - separate core typings are a burden to maintain.\n  - problems of missing symbols and clashing symbols.\n  - burden of manually tracking fixes and additions made in the default libs.\n- Targeting ES5 as the 'lowest common denominator' means some language features known to be supported cannot be used (eg generators in Node.js).\n- Targeting ES6 (e.g. to take advantage of Node.js' support for many ES6 features) leads to further complications:\n  - \u003cdel\u003eCommonJS modules won't compile, even though that's the only module system Node supports.\u003c/del\u003e (fixed by #4811)\n  - The compiler emits ES6 even for features that are known _not_ to be supported, which would fail at runtime.\n  - Adding babel.js to the build pipeline adds complexity.\n## Workarounds\n#### To achieve mixed ES5/ES6 core typings:\n- specify `--target ES5` and selectively add ES6 typings in separately maintained files (eg from DefinitelyTyped).\n- specify `--target ES6` and be careful to avoid referencing unsupported ES6 features (the compiler won't issue any errors).\n- specify `--noLib` and manually maintain custom core typings in your own project.\n#### To use ES6 features supported by the target platform\n- specify `--target ES5` and (a) accept that things will be down-level emitted, and (b) don't use features with no down-level emit yet (ie generators).\n- specify `--target ES6` and (a) \u003cdel\u003econvert everything from CommonJS to ES6 modules\u003c/del\u003e (fixed by #4811), (b) add babel.js to the build pipeline, and (c) configure babel.js to do either pass-through or down-level emit on a feature-by-feature basis.\n## Proposed Solution\n\nThis proposal consists of two parts:\n\n\u003cdel\u003e1. Support for conditional compilation using `#if` and `#endif` directives, so that a single default lib can offer fine-grained typings tailored to a mixed ES3/5/6/7 target environment.\u003c/del\u003e\n\n\n\u003cdel\u003eThe conditional compilation part is detailed in a separate proposal (#4691) with its own [working implementation](https://github.com/yortus/TypeScript/tree/preprocessor-directives).\u003c/del\u003e\n\n\n**1. A mechanism allowing the default lib to offer fine-grained typings tailored to a mixed ES3/5/6/7 target environment.**\n\nThis is really an internal compiler detail, so the mechanism is open to debate. It just has to match the granularity supported by the new compiler options below.\n\nThe [working implementation](https://github.com/yortus/TypeScript/tree/granular-targeting) uses `#if...#endif` conditional compilation proposed in #4691. But this is overkill for this use case and [seems unlikely](https://github.com/Microsoft/TypeScript/issues/4691#issuecomment-138678473) to be considered.\n\nSeveral other mechanisms have been discussed (summarized [here](https://github.com/Microsoft/TypeScript/issues/4692#issuecomment-138750104)).\n\n**2. Support for additional compiler options allowing the target environment to be described on a feature-by-feature basis.**\n\nUnder this proposal, the `target` option remains, but is now interpreted as the 'baseline' target, determining which features the target supports by default. For instance, ES6 symbols and generators are supported by default if `target` is set to `ES6` or higher.\n\nThe additional compiler options have the form `targetHasXYZ`, where `XYZ` designates a feature. These options are used to override the target for a particular language feature. They instruct the compiler that the target environment explicitly does or does not support a particular feature, regardless of what the `target` option otherwise imples.\n\nThe [working implementation](https://github.com/yortus/TypeScript/tree/granular-targeting) currently supports the following additional compiler options (all boolean):\n- `targetHasArrowFunctions`: specify whether the target supports ES6 `() =\u003e {...}` syntax\n- `targetHasBlockScoping`: specify whether the target supports ES6 `let` and `const`\n- `targetHasForOf`: specify whether the target supports ES6 `for..of` syntax\n- `targetHasGenerators`: specify whether the target supports ES6 generators\n- `targetHasIterables`: specify whether the target supports ES6 iterables and iterators\n- `targetHasModules`: specify whether the target supports ES6 modules\n- `targetHasPromises`: specify whether the target supports ES6 promises\n- `targetHasSymbols`: specify whether the target supports ES6 symbols\n\nThese options work both on the command line and in `tsconfig.json` files.\n## Example `tsconfig.json` Files and their Behaviour\n#### A.\n\n``` json\n{\n    \"target\": \"es6\",\n    \"targetHasModules\": false,\n    \"targetHasBlockScoping\": false,\n    \"module\": \"commonjs\"\n}\n```\n\nEmits ES6 JavaScript, except with CommonJS module syntax, and with `let`/`const` down-leveled to `var`. This might match a Node.js environment.\n#### B.\n\n``` json\n{\n    \"target\": \"es5\",\n    \"targetHasSymbols\": true\n}\n```\n\nEmits ES5 JavaScript, except with Symbol references emitted as-is, and with full type support for well-known symbols from the default lib.\n#### C.\n\n``` json\n{\n    \"target\": \"es5\",\n    \"targetHasPromises\": true\n}\n```\n\nEmits ES5 JavaScript, except with full type support for ES6 promises from the default lib. This would work in an ES5 environment with a native or polyfilled `Promise` object.\n## Backward Compatibility, Design Impact, Performance, etc\n- There is no impact on existing TypeScript projects. The additional options and preprocessor directives only modify the compiler's behaviour if they are explicitly used.\n- The preprocessor directives `#if` and `#endif` add new language syntax. No existing language features are affected.\n- There is negligable impact on compiler performance.\n- Only one default lib is needed (`lib.es6.d.ts`). It contains many conditionally compiled sections (ie with `#if` and `#endif`)\n## Remaining Work and Questions\n- Support compiler options for more target features, e.g.:\n  - template strings\n  - classes\n  - `Map`/`Set`/`WeakMap`/`WeakSet`\n  - binary and octal literals\n  - destructuring\n  - default, rest, and optional parameters\n- How granular could/should targets be? Feature support is naturally hierarchical. E.g. block scoping may be separated into (a) `let`, (b) `const` and (c) block-level function declaration. This is true of most features and their realistic implementations (the [Kangax ES6 compatibility table](https://kangax.github.io/compat-table/es6/) has a three-level hierarchy down the left side).\n","author":{"url":"https://github.com/yortus","@type":"Person","name":"yortus"},"datePublished":"2015-09-08T15:54:37.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":51},"url":"https://github.com/4692/TypeScript/issues/4692"}