--incremental flagTypeScript 3.4 introduces a new flag called --incremental which tells TypeScript to save information about the project graph from the last compilation.\nThe next time TypeScript is invoked with --incremental, it will use that information to detect the least costly way to type-check and emit changes to your project.
\njson// tsconfig.json\n{\n \"compilerOptions\": {\n \"incremental\": true,\n \"outDir\": \"./lib\"\n },\n \"include\": [\"./src\"]\n}
By default with these settings, when we run tsc, TypeScript will look for a file called .tsbuildinfo in the output directory (./lib).\nIf ./lib/.tsbuildinfo doesn’t exist, it’ll be generated.\nBut if it does, tsc will try to use that file to incrementally type-check and update our output files.
These .tsbuildinfo files can be safely deleted and don’t have any impact on our code at runtime - they’re purely used to make compilations faster.\nWe can also name them anything that we want, and place them anywhere we want using the --tsBuildInfoFile flag.
\njson// front-end.tsconfig.json\n{\n \"compilerOptions\": {\n \"incremental\": true,\n \"tsBuildInfoFile\": \"./buildcache/front-end\",\n \"outDir\": \"./lib\"\n },\n \"include\": [\"./src\"]\n}
Part of the intent with composite projects (tsconfig.jsons with composite set to true) is that references between different projects can be built incrementally.\nAs such, composite projects will always produce .tsbuildinfo files.
outFileWhen outFile is used, the build information file’s name will be based on the output file’s name.\nAs an example, if our output JavaScript file is ./output/foo.js, then under the --incremental flag, TypeScript will generate the file ./output/foo.tsbuildinfo.\nAs above, this can be controlled with the --tsBuildInfoFile flag.
TypeScript 3.4 can now produce generic function types when inference from other generic functions produces free type variables for inferences.\nThis means many function composition patterns now work better in 3.4.
\nTo get more specific, let’s build up some motivation and consider the following compose function:
\ntsfunction compose<A, B, C>(f: (arg: A) => B, g: (arg: B) => C): (arg: A) => C {\n return x => g(f(x));\n}
compose takes two other functions:
f which takes some argument (of type A) and returns a value of type Bg which takes an argument of type B (the type f returned), and returns a value of type Ccompose then returns a function which feeds its argument through f and then g.
When calling this function, TypeScript will try to figure out the types of A, B, and C through a process called type argument inference.\nThis inference process usually works pretty well:
\ntsinterface Person {\n name: string;\n age: number;\n}\n\nfunction getDisplayName(p: Person) {\n return p.name.toLowerCase();\n}\n\nfunction getLength(s: string) {\n return s.length;\n}\n\n// has type '(p: Person) => number'\nconst getDisplayNameLength = compose(\n getDisplayName,\n getLength,\n);\n\n// works and returns the type 'number'\ngetDisplayNameLength({ name: \"Person McPersonface\", age: 42 });
The inference process is fairly straightforward here because getDisplayName and getLength use types that can easily be referenced.\nHowever, in TypeScript 3.3 and earlier, generic functions like compose didn’t work so well when passed other generic functions.
\ntsinterface Box<T> {\n value: T;\n}\n\nfunction makeArray<T>(x: T): T[] {\n return [x];\n}\n\nfunction makeBox<U>(value: U): Box<U> {\n return { value };\n}\n\n// has type '(arg: {}) => Box<{}[]>'\nconst makeBoxedArray = compose(\n makeArray,\n makeBox,\n)\n\nmakeBoxedArray(\"hello!\").value[0].toUpperCase();\n// ~~~~~~~~~~~\n// error: Property 'toUpperCase' does not exist on type '{}'.
In older versions, TypeScript would infer the empty object type ({}) when inferring from other type variables like T and U.
During type argument inference in TypeScript 3.4, for a call to a generic function that returns a function type, TypeScript will, as appropriate, propagate type parameters from generic function arguments onto the resulting function type.
\nIn other words, instead of producing the type
\n\nts(arg: {}) => Box<{}[]>
TypeScript 3.4 produces the type
\n\nts<T>(arg: T) => Box<T[]>
Notice that T has been propagated from makeArray into the resulting type’s type parameter list.\nThis means that genericity from compose’s arguments has been preserved and our makeBoxedArray sample will just work!
\ntsinterface Box<T> {\n value: T;\n}\n\nfunction makeArray<T>(x: T): T[] {\n return [x];\n}\n\nfunction makeBox<U>(value: U): Box<U> {\n return { value };\n}\n\n// has type '<T>(arg: T) => Box<T[]>'\nconst makeBoxedArray = compose(\n makeArray,\n makeBox,\n)\n\n// works with no problem!\nmakeBoxedArray(\"hello!\").value[0].toUpperCase();
For more details, you can read more at the original change.
\nReadonlyArray and readonly tuplesTypeScript 3.4 makes it a little bit easier to use read-only array-like types.
\nReadonlyArrayThe ReadonlyArray type describes Arrays that can only be read from.\nAny variable with a reference to a ReadonlyArray can’t add, remove, or replace any elements of the array.
\ntsfunction foo(arr: ReadonlyArray<string>) {\n arr.slice(); // okay\n arr.push(\"hello!\"); // error!\n}
While it’s good practice to use ReadonlyArray over Array when no mutation is intended, it’s often been a pain given that arrays have a nicer syntax.\nSpecifically, number[] is a shorthand version of Array<number>, just as Date[] is a shorthand for Array<Date>.
TypeScript 3.4 introduces a new syntax for ReadonlyArray using a new readonly modifier for array types.
\ntsfunction foo(arr: readonly string[]) {\n arr.slice(); // okay\n arr.push(\"hello!\"); // error!\n}
readonly tuplesTypeScript 3.4 also introduces new support for readonly tuples.\nWe can prefix any tuple type with the readonly keyword to make it a readonly tuple, much like we now can with array shorthand syntax.\nAs you might expect, unlike ordinary tuples whose slots could be written to, readonly tuples only permit reading from those positions.
\ntsfunction foo(pair: readonly [string, string]) {\n console.log(pair[0]); // okay\n pair[1] = \"hello!\"; // error\n}
The same way that ordinary tuples are types that extend from Array - a tuple with elements of type T1, T2, … Tn extends from Array< T1 | T2 | … Tn > - readonly tuples are types that extend from ReadonlyArray. So a readonly tuple with elements T1, T2, … Tn extends from ReadonlyArray< T1 | T2 | … Tn >.
readonly mapped type modifiers and readonly arraysIn earlier versions of TypeScript, we generalized mapped types to operate differently on array-like types.\nThis meant that a mapped type like Boxify could work on arrays and tuples alike.
\ntsinterface Box<T> { value: T }\n\ntype Boxify<T> = {\n [K in keyof T]: Box<T[K]>\n}\n\n// { a: Box<string>, b: Box<number> }\ntype A = Boxify<{ a: string, b: number }>;\n\n// Array<Box<number>>\ntype B = Boxify<number[]>;\n\n// [Box<string>, Box<number>]\ntype C = Boxify<[string, boolean]>;
Unfortunately, mapped types like the Readonly utility type were effectively no-ops on array and tuple types.
\nts// lib.d.ts\ntype Readonly<T> = {\n readonly [K in keyof T]: T[K]\n}\n\n// How code acted *before* TypeScript 3.4\n\n// { readonly a: string, readonly b: number }\ntype A = Readonly<{ a: string, b: number }>;\n\n// number[]\ntype B = Readonly<number[]>;\n\n// [string, boolean]\ntype C = Readonly<[string, boolean]>;
In TypeScript 3.4, the readonly modifier in a mapped type will automatically convert array-like types to their corresponding readonly counterparts.
\nts// How code acts now *with* TypeScript 3.4\n\n// { readonly a: string, readonly b: number }\ntype A = Readonly<{ a: string, b: number }>;\n\n// readonly number[]\ntype B = Readonly<number[]>;\n\n// readonly [string, boolean]\ntype C = Readonly<[string, boolean]>;
Similarly, you could write a utility type like Writable mapped type that strips away readonly-ness, and that would convert readonly array containers back to their mutable equivalents.
\ntstype Writable<T> = {\n -readonly [K in keyof T]: T[K]\n}\n\n// { a: string, b: number }\ntype A = Writable<{\n readonly a: string;\n readonly b: number\n}>;\n\n// number[]\ntype B = Writable<readonly number[]>;\n\n// [string, boolean]\ntype C = Writable<readonly [string, boolean]>;
Despite its appearance, the readonly type modifier can only be used for syntax on array types and tuple types.\nIt is not a general-purpose type operator.
\ntslet err1: readonly Set<number>; // error!\nlet err2: readonly Array<boolean>; // error!\n\nlet okay: readonly boolean[]; // works fine
You can see more details in the pull request.
\nconst assertionsTypeScript 3.4 introduces a new construct for literal values called const assertions.\nIts syntax is a type assertion with const in place of the type name (e.g. 123 as const).\nWhen we construct new literal expressions with const assertions, we can signal to the language that
\"hello\" to string)readonly propertiesreadonly tuples\nts// Type '\"hello\"'\nlet x = \"hello\" as const;\n\n// Type 'readonly [10, 20]'\nlet y = [10, 20] as const;\n\n// Type '{ readonly text: \"hello\" }'\nlet z = { text: \"hello\" } as const;
Outside of .tsx files, the angle bracket assertion syntax can also be used.
\nts// Type '\"hello\"'\nlet x = <const>\"hello\";\n\n// Type 'readonly [10, 20]'\nlet y = <const>[10, 20];\n\n// Type '{ readonly text: \"hello\" }'\nlet z = <const>{ text: \"hello\" };
This feature means that types that would otherwise be used just to hint immutability to the compiler can often be omitted.
\n\nts// Works with no types referenced or declared.\n// We only needed a single const assertion.\nfunction getShapes() {\n let result = [\n { kind: \"circle\", radius: 100, },\n { kind: \"square\", sideLength: 50, },\n ] as const;\n\n return result;\n}\n\nfor (const shape of getShapes()) {\n // Narrows perfectly!\n if (shape.kind === \"circle\") {\n console.log(\"Circle radius\", shape.radius);\n }\n else {\n console.log(\"Square side length\", shape.sideLength);\n }\n}
Notice the above needed no type annotations.\nThe const assertion allowed TypeScript to take the most specific type of the expression.
This can even be used to enable enum-like patterns in plain JavaScript code if you choose not to use TypeScript’s enum construct.
\ntsexport const Colors = {\n red: \"RED\",\n blue: \"BLUE\",\n green: \"GREEN\",\n} as const;\n\n// or use an 'export default'\n\nexport default {\n red: \"RED\",\n blue: \"BLUE\",\n green: \"GREEN\",\n} as const;
One thing to note is that const assertions can only be applied immediately on simple literal expressions.
\nts// Error! A 'const' assertion can only be applied to a\n// to a string, number, boolean, array, or object literal.\nlet a = (Math.random() < 0.5 ? 0 : 1) as const;\n\n// Works!\nlet b = Math.random() < 0.5 ?\n 0 as const :\n 1 as const;
Another thing to keep in mind is that const contexts don’t immediately convert an expression to be fully immutable.
\ntslet arr = [1, 2, 3, 4];\n\nlet foo = {\n name: \"foo\",\n contents: arr,\n} as const;\n\nfoo.name = \"bar\"; // error!\nfoo.contents = []; // error!\n\nfoo.contents.push(5); // ...works!
For more details, you can check out the respective pull request.
\nglobalThisTypeScript 3.4 introduces support for type-checking ECMAScript’s new globalThis - a global variable that, well, refers to the global scope.\nUnlike the above solutions, globalThis provides a standard way for accessing the global scope which can be used across different environments.
\nts// in a global file:\n\nvar abc = 100;\n\n// Refers to 'abc' from above.\nglobalThis.abc = 200;
Note that global variables declared with let and const don’t show up on globalThis.
\ntslet answer = 42;\n\n// error! Property 'answer' does not exist on 'typeof globalThis'.\nglobalThis.answer = 333333;
It’s also important to note that TypeScript doesn’t transform references to globalThis when compiling to older versions of ECMAScript.\nAs such, unless you’re targeting evergreen browsers (which already support globalThis), you may want to use an appropriate polyfill instead.
For more details on the implementation, see the feature’s pull request.
","headings":[{"value":"Faster subsequent builds with the --incremental flag","depth":2},{"value":"Composite projects","depth":3},{"value":"outFile","depth":3},{"value":"Higher order type inference from generic functions","depth":2},{"value":"Improvements for ReadonlyArray and readonly tuples","depth":2},{"value":"A new syntax for ReadonlyArray","depth":3},{"value":"readonly tuples","depth":3},{"value":"readonly mapped type modifiers and readonly arrays","depth":3},{"value":"Caveats","depth":3},{"value":"const assertions","depth":2},{"value":"Caveats","depth":3},{"value":"Type-checking for globalThis","depth":2}],"frontmatter":{"permalink":"/docs/handbook/release-notes/typescript-3-4.html","title":"TypeScript 3.4"}}},"pageContext":{"slug":"/docs/handbook/release-notes/typescript-3-4.html","isOldHandbook":true}}}