TypeScript 3.0 introduces a new concept of project references. Project references allow TypeScript projects to depend on other TypeScript projects - specifically, allowing tsconfig.json files to reference other tsconfig.json files. Specifying these dependencies makes it easier to split your code into smaller projects, since it gives TypeScript (and tools around it) a way to understand build ordering and output structure.
TypeScript 3.0 also introduces a new mode for tsc, the --build flag, that works hand-in-hand with project references to enable faster TypeScript builds.
See Project References handbook page for more documentation.
\nTypeScript 3.0 adds support to multiple new capabilities to interact with function parameter lists as tuple types.\nTypeScript 3.0 adds support for:
\nWith these features it becomes possible to strongly type a number of higher-order functions that transform functions and their parameter lists.
\nWhen a rest parameter has a tuple type, the tuple type is expanded into a sequence of discrete parameters.\nFor example the following two declarations are equivalent:
\n\ntsdeclare function foo(...args: [number, string, boolean]): void;
\ntsdeclare function foo(args_0: number, args_1: string, args_2: boolean): void;
When a function call includes a spread expression of a tuple type as the last argument, the spread expression corresponds to a sequence of discrete arguments of the tuple element types.
\nThus, the following calls are equivalent:
\n\ntsconst args: [number, string, boolean] = [42, \"hello\", true];\nfoo(42, \"hello\", true);\nfoo(args[0], args[1], args[2]);\nfoo(...args);
A rest parameter is permitted to have a generic type that is constrained to an array type, and type inference can infer tuple types for such generic rest parameters. This enables higher-order capturing and spreading of partial parameter lists:
\n\ntsdeclare function bind<T, U extends any[], V>(f: (x: T, ...args: U) => V, x: T): (...args: U) => V;\n\ndeclare function f3(x: number, y: string, z: boolean): void;\n\nconst f2 = bind(f3, 42); // (y: string, z: boolean) => void\nconst f1 = bind(f2, \"hello\"); // (z: boolean) => void\nconst f0 = bind(f1, true); // () => void\n\nf3(42, \"hello\", true);\nf2(\"hello\", true);\nf1(true);\nf0();
In the declaration of f2 above, type inference infers types number, [string, boolean] and void for T, U and V respectively.
Note that when a tuple type is inferred from a sequence of parameters and later expanded into a parameter list, as is the case for U, the original parameter names are used in the expansion (however, the names have no semantic meaning and are not otherwise observable).
Tuple types now permit a ? postfix on element types to indicate that the element is optional:
\ntslet t: [number, string?, boolean?];\nt = [42, \"hello\", true];\nt = [42, \"hello\"];\nt = [42];
In --strictNullChecks mode, a ? modifier automatically includes undefined in the element type, similar to optional parameters.
A tuple type permits an element to be omitted if it has a postfix ? modifier on its type and all elements to the right of it also have ? modifiers.
When tuple types are inferred for rest parameters, optional parameters in the source become optional tuple elements in the inferred type.
\nThe length property of a tuple type with optional elements is a union of numeric literal types representing the possible lengths.\nFor example, the type of the length property in the tuple type [number, string?, boolean?] is 1 | 2 | 3.
The last element of a tuple type can be a rest element of the form ...X, where X is an array type.\nA rest element indicates that the tuple type is open-ended and may have zero or more additional elements of the array element type.\nFor example, [number, ...string[]] means tuples with a number element followed by any number of string elements.
\ntsfunction tuple<T extends any[]>(...args: T): T {\n return args;\n}\n\nconst numbers: number[] = getArrayOfNumbers();\nconst t1 = tuple(\"foo\", 1, true); // [string, number, boolean]\nconst t2 = tuple(\"bar\", ...numbers); // [string, ...number[]]
The type of the length property of a tuple type with a rest element is number.
unknown top typeTypeScript 3.0 introduces a new top type unknown.\nunknown is the type-safe counterpart of any.\nAnything is assignable to unknown, but unknown isn’t assignable to anything but itself and any without a type assertion or a control flow based narrowing.\nLikewise, no operations are permitted on an unknown without first asserting or narrowing to a more specific type.
\nts// In an intersection everything absorbs unknown\n\ntype T00 = unknown & null; // null\ntype T01 = unknown & undefined; // undefined\ntype T02 = unknown & null & undefined; // null & undefined (which becomes never)\ntype T03 = unknown & string; // string\ntype T04 = unknown & string[]; // string[]\ntype T05 = unknown & unknown; // unknown\ntype T06 = unknown & any; // any\n\n// In a union an unknown absorbs everything\n\ntype T10 = unknown | null; // unknown\ntype T11 = unknown | undefined; // unknown\ntype T12 = unknown | null | undefined; // unknown\ntype T13 = unknown | string; // unknown\ntype T14 = unknown | string[]; // unknown\ntype T15 = unknown | unknown; // unknown\ntype T16 = unknown | any; // any\n\n// Type variable and unknown in union and intersection\n\ntype T20<T> = T & {}; // T & {}\ntype T21<T> = T | {}; // T | {}\ntype T22<T> = T & unknown; // T\ntype T23<T> = T | unknown; // unknown\n\n// unknown in conditional types\n\ntype T30<T> = unknown extends T ? true : false; // Deferred\ntype T31<T> = T extends unknown ? true : false; // Deferred (so it distributes)\ntype T32<T> = never extends T ? true : false; // true\ntype T33<T> = T extends never ? true : false; // Deferred\n\n// keyof unknown\n\ntype T40 = keyof any; // string | number | symbol\ntype T41 = keyof unknown; // never\n\n// Only equality operators are allowed with unknown\n\nfunction f10(x: unknown) {\n x == 5;\n x !== 10;\n x >= 0; // Error\n x + 1; // Error\n x * 2; // Error\n -x; // Error\n +x; // Error\n}\n\n// No property accesses, element accesses, or function calls\n\nfunction f11(x: unknown) {\n x.foo; // Error\n x[5]; // Error\n x(); // Error\n new x(); // Error\n}\n\n// typeof, instanceof, and user defined type predicates\n\ndeclare function isFunction(x: unknown): x is Function;\n\nfunction f20(x: unknown) {\n if (typeof x === \"string\" || typeof x === \"number\") {\n x; // string | number\n }\n if (x instanceof Error) {\n x; // Error\n }\n if (isFunction(x)) {\n x; // Function\n }\n}\n\n// Homomorphic mapped type over unknown\n\ntype T50<T> = { [P in keyof T]: number };\ntype T51 = T50<any>; // { [x: string]: number }\ntype T52 = T50<unknown>; // {}\n\n// Anything is assignable to unknown\n\nfunction f21<T>(pAny: any, pNever: never, pT: T) {\n let x: unknown;\n x = 123;\n x = \"hello\";\n x = [1, 2, 3];\n x = new Error();\n x = x;\n x = pAny;\n x = pNever;\n x = pT;\n}\n\n// unknown assignable only to itself and any\n\nfunction f22(x: unknown) {\n let v1: any = x;\n let v2: unknown = x;\n let v3: object = x; // Error\n let v4: string = x; // Error\n let v5: string[] = x; // Error\n let v6: {} = x; // Error\n let v7: {} | null | undefined = x; // Error\n}\n\n// Type parameter 'T extends unknown' not related to object\n\nfunction f23<T extends unknown>(x: T) {\n let y: object = x; // Error\n}\n\n// Anything but primitive assignable to { [x: string]: unknown }\n\nfunction f24(x: { [x: string]: unknown }) {\n x = {};\n x = { a: 5 };\n x = [1, 2, 3];\n x = 123; // Error\n}\n\n// Locals of type unknown always considered initialized\n\nfunction f25() {\n let x: unknown;\n let y = x;\n}\n\n// Spread of unknown causes result to be unknown\n\nfunction f26(x: {}, y: unknown, z: any) {\n let o1 = { a: 42, ...x }; // { a: number }\n let o2 = { a: 42, ...x, ...y }; // unknown\n let o3 = { a: 42, ...x, ...y, ...z }; // any\n}\n\n// Functions with unknown return type don't need return expressions\n\nfunction f27(): unknown {\n}\n\n// Rest type cannot be created from unknown\n\nfunction f28(x: unknown) {\n let { ...a } = x; // Error\n}\n\n// Class properties of type unknown don't need definite assignment\n\nclass C1 {\n a: string; // Error\n b: unknown;\n c: any;\n}
defaultProps in JSXTypeScript 2.9 and earlier didn’t leverage React defaultProps declarations inside JSX components.\nUsers would often have to declare properties optional and use non-null assertions inside of render, or they’d use type-assertions to fix up the type of the component before exporting it.
TypeScript 3.0 adds support for a new type alias in the JSX namespace called LibraryManagedAttributes.\nThis helper type defines a transformation on the component’s Props type, before using to check a JSX expression targeting it; thus allowing customization like: how conflicts between provided props and inferred props are handled, how inferences are mapped, how optionality is handled, and how inferences from differing places should be combined.
In short using this general type, we can model React’s specific behavior for things like defaultProps and, to some extent, propTypes.
\ntsxexport interface Props {\n name: string;\n}\n\nexport class Greet extends React.Component<Props> {\n render() {\n const { name } = this.props;\n return <div>Hello {name.toUpperCase()}!</div>;\n }\n static defaultProps = { name: \"world\"};\n}\n\n// Type-checks! No type assertions needed!\nlet el = <Greet />
defaultPropsThe default-ed properties are inferred from the defaultProps property type. If an explicit type annotation is added, e.g. static defaultProps: Partial<Props>; the compiler will not be able to identify which properties have defaults (since the type of defaultProps include all properties of Props).
Use static defaultProps: Pick<Props, \"name\">; as an explicit type annotation instead, or do not add a type annotation as done in the example above.
For function components (formerly known as SFCs) use ES2015 default initializers:
\n\ntsxfunction Greet({ name = \"world\" }: Props) {\n return <div>Hello {name.toUpperCase()}!</div>;\n}
@types/ReactCorresponding changes to add LibraryManagedAttributes definition to the JSX namespace in @types/React are still needed.\nKeep in mind that there are some limitations.
/// <reference lib=\"...\" /> reference directivesTypeScript adds a new triple-slash-reference directive (/// <reference lib=\"name\" />), allowing a file to explicitly include an existing built-in lib file.
Built-in lib files are referenced in the same fashion as the \"lib\" compiler option in tsconfig.json (e.g. use lib=\"es2015\" and not lib=\"lib.es2015.d.ts\", etc.).
For declaration file authors who relay on built-in types, e.g. DOM APIs or built-in JS run-time constructors like Symbol or Iterable, triple-slash-reference lib directives are the recommended. Previously these .d.ts files had to add forward/duplicate declarations of such types.
Using /// <reference lib=\"es2017.string\" /> to one of the files in a compilation is equivalent to compiling with --lib es2017.string.
","headings":[{"value":"Project References","depth":2},{"value":"Tuples in rest parameters and spread expressions","depth":2},{"value":"Rest parameters with tuple types","depth":2},{"value":"Spread expressions with tuple types","depth":2},{"value":"Generic rest parameters","depth":2},{"value":"Example","depth":5},{"value":"Optional elements in tuple types","depth":2},{"value":"Example","depth":5},{"value":"Rest elements in tuple types","depth":3},{"value":"Example","depth":5},{"value":"New unknown top type","depth":2},{"value":"Example","depth":5},{"value":"Support for defaultProps in JSX","depth":2},{"value":"Caveats","depth":2},{"value":"Explicit types on defaultProps","depth":3},{"value":"Changes to @types/React","depth":4},{"value":"///ts/// <reference lib=\"es2017.string\" />\n\n\"foo\".padStart(4);