Design Meeting Notes, 6/10/2016

[mhegazy]

Automatic type acquisition -- concerns

Some background:

given a type reference, i.e. in tsconfig.json "types" : ["jquery"], or /// <reference types="jquery" />, here are the lookup locations to resolve"jquery"` reference:

• location specified by --typesRoot if defined
• node_modules
• node_module@types

automatic type definition inclusion in compilations, include all "types" packages automatically

• value of --typesRoot if specified
• the first node_modules\@types walking the spine of the project

The idea here is to simplify type acquisition; all what a user needs to do is

npm install @types/jquery
cat $("id") > a.ts
tsc a.ts

The problem here is we include files that may not be intended to be part of the compilation

• perf concerns about the number of files we grok
• unexpected error messaged that would be hard to diagnose

what does typesRoot mean:

• it is a primary location for look up, used to allow the user to override type definitions in node_modules@types

Changes:

• make typesRoot an ordered list of strings
• default is ./node_modules/@types
• change the name to typeRoots
• typeRoots become the location to automatically include definition files
• to disable auto inclusion specify an empty typeRoots, or --typeRoots /dev/null
• an explicit list of types in tsconfig.json will disable auto-inclusion as well

ADT -- updated

a new kind of type guard is allowed, discriminant gard,
some conditions:

• of the form x.prop === expression
• type of x has to be of union type
• type of prop has to be of a literal type, string literal type now, but can be extended to numeric literals in the future
• type if expression has to be of string type (or numeric when numeric literal types is defined)

the type of x is narrowed to be the ones that have prop with type matching that of expression

example:

type Message = 
{ kind: "foo"; foo: string } |
{ kind: "bar" | "baz"l bar: number } |
{ kind: "done" };

declare const x: "foo" | "bar";

function f (m: Message) {

    if (m.kind === "foo") {
       m.foo;
    }
    else if (m.kind === x) {
       m.baz;
    }
    else {
        m.kind // "done"

    }
}

This also works for equality and in switch statements

why only string literals?
yes, string literals are closed. we know the value and the type is the same. we can not make the same assumption about object types.

e.g.

type Message = {kind: X; a: number} | {kind: Y; b: number};
const x: X;

if (m.kind === x) {
    // what about if x is also a Y
}

down-level generators support

• basic level of support, basically for async``await.
• extensive level of support for the rest of generators
• yelid * support
• for..of support for generarots
• spread support for generarots

conclusion start with the basic support first, to get async/await support in do the full support later

runtime library (tslib)

__generator is big enough, we do not want to add it in every file.
we need a new library/module for these helpers

__generator will be generated in each file that uses it as we do today. but we will have an option to write it to a different location

The new helper library should include all our helpers

• __extends helper
• __assign helper
• __decorate helper
• __param helper
• __metadata helper
• __awaiter helper

in addition to the generator ones:

• __generator helper
  • Used by the down-level generator transforms to execute a state machine representation of a generator function.
  • Supports “yield”.
  • Supports “yield*”.
  • Supports “iterator.next(v)”.
  • Supports “iterator.throw(e)”.
  • Supports “iterator.return(v)”.
  • Uses magic “iterator” method as an approximation for “Symbol.iterator” in ES5.
  • Uses “Symbol.iterator” if available.
• __keys helper
  • Creates an Iterator over the keys of an object.
  • Used to support “yield” inside of a “for..in” loop.
• __values helper
  • If “Symbol.iterator” is available and the argument has a “Symbol.iterator” method, invokes it and returns the result.
  • If the argument has a magic iterator method, invokes it and returns the result.
  • If the argument is an array-like, creates an Iterator over the elements of the array.
  • Used to support “yield” inside of a “for..in” loop.
  • Used to support “yield” inside of a “for..of” loop.
  • Used to support “yield*”.
  • Used to support “for..of” for down-level generators.
  • Used to support spread for down-level generators.
• __takeOne helper
  • Takes the next value from an iterator.
  • Used to support array destructuring of down-level generators.
• __takeAll helper
  • Creates an array from the remaining values of an iterator.
  • Used to support array destructuring of down-level generators.
  • Used to support spread for down-level generators.
• __spread helper
  • Spreads arguments using __values.
  • Used to support spread for down-level generators.

The goal for this run time library is to make it available in the following ways:

• Published on npm.
• Published to one or more CDNs.
• Distributed with the compiler?

Using the library with your compilation will be supported with the following compiler options:

• Moodes
  • Inline – Inline helpers (the current default behavior).
  • None – No helpers (--noEmitHelpers).
  • Import – (--importHelpers)Import the helpers runtime from a named module in every external module file. Uses helpers from a global namespace for scripts.
• --helpersImport – Use the provided module/package name to import helpers (default “tslib”).

[born2net]

FYI: looks like its coming soon: https://blogs.msdn.microsoft.com/typescript/2016/06/15/the-future-of-declaration-files/

[TeamworkGuy2]

I stopped by to ask a question about --noEmitHelpers and programmatic access to the helper functions' in build scripts, but you guys already have plans, I'm excited to see the runtime library (tslib) notes and #9097 in a future release! 👍

I hope, based on the last few lines on Moodes - None, that --noEmitHelpers will continue to work the way it currently does (TS 1.8), emitting __extends(A, _super) with no __extends implementation?

[mhegazy]

Noemithelpers will continue to work, a new flag is added to import an external helper.