strictBindCallApplyTypeScript 3.2 introduces a new --strictBindCallApply compiler option (in the --strict family of options) with which the bind, call, and apply methods on function objects are strongly typed and strictly checked.
\ntsfunction foo(a: number, b: string): string {\n return a + b;\n}\n\nlet a = foo.apply(undefined, [10]); // error: too few argumnts\nlet b = foo.apply(undefined, [10, 20]); // error: 2nd argument is a number\nlet c = foo.apply(undefined, [10, \"hello\", 30]); // error: too many arguments\nlet d = foo.apply(undefined, [10, \"hello\"]); // okay! returns a string
This is achieved by introducing two new types, CallableFunction and NewableFunction, in lib.d.ts. These types contain specialized generic method declarations for bind, call, and apply for regular functions and constructor functions, respectively. The declarations use generic rest parameters (see #24897) to capture and reflect parameter lists in a strongly typed manner. In --strictBindCallApply mode these declarations are used in place of the (very permissive) declarations provided by type Function.
Since the stricter checks may uncover previously unreported errors, this is a breaking change in --strict mode.
Additionally, another caveat of this new functionality is that due to certain limitations, bind, call, and apply can’t yet fully model generic functions or functions that have overloads.\nWhen using these methods on a generic function, type parameters will be substituted with the empty object type ({}), and when used on a function with overloads, only the last overload will ever be modeled.
In TypeScript 3.2, object literals now allow generic spread expressions which now produce intersection types, similar to the Object.assign function and JSX literals. For example:
\ntsfunction taggedObject<T, U extends string>(obj: T, tag: U) {\n return { ...obj, tag }; // T & { tag: U }\n}\n\nlet x = taggedObject({ x: 10, y: 20 }, \"point\"); // { x: number, y: number } & { tag: \"point\" }
Property assignments and non-generic spread expressions are merged to the greatest extent possible on either side of a generic spread expression. For example:
\n\ntsfunction foo1<T>(t: T, obj1: { a: string }, obj2: { b: string }) {\n return { ...obj1, x: 1, ...t, ...obj2, y: 2 }; // { a: string, x: number } & T & { b: string, y: number }\n}
Non-generic spread expressions continue to be processed as before: Call and construct signatures are stripped, only non-method properties are preserved, and for properties with the same name, the type of the rightmost property is used. This contrasts with intersection types which concatenate call and construct signatures, preserve all properties, and intersect the types of properties with the same name. Thus, spreads of the same types may produce different results when they are created through instantiation of generic types:
\n\ntsfunction spread<T, U>(t: T, u: U) {\n return { ...t, ...u }; // T & U\n}\n\ndeclare let x: { a: string, b: number };\ndeclare let y: { b: string, c: boolean };\n\nlet s1 = { ...x, ...y }; // { a: string, b: string, c: boolean }\nlet s2 = spread(x, y); // { a: string, b: number } & { b: string, c: boolean }\nlet b1 = s1.b; // string\nlet b2 = s2.b; // number & string
TypeScript 3.2 also allows destructuring a rest binding from a generic variable. This is achieved by using the predefined Pick and Exclude helper types from lib.d.ts, and using the generic type in question as well as the names of the other bindings in the destructuring pattern.
\ntsfunction excludeTag<T extends { tag: string }>(obj: T) {\n let { tag, ...rest } = obj;\n return rest; // Pick<T, Exclude<keyof T, \"tag\">>\n}\n\nconst taggedPoint = { x: 10, y: 20, tag: \"point\" };\nconst point = excludeTag(taggedPoint); // { x: number, y: number }
BigInts are part of an upcoming proposal in ECMAScript that allow us to model theoretically arbitrarily large integers.\nTypeScript 3.2 brings type-checking for BigInts, as well as support for emitting BigInt literals when targeting esnext.
BigInt support in TypeScript introduces a new primitive type called the bigint (all lowercase).\nYou can get a bigint by calling the BigInt() function or by writing out a BigInt literal by adding an n to the end of any integer numeric literal:
\ntslet foo: bigint = BigInt(100); // the BigInt function\nlet bar: bigint = 100n; // a BigInt literal\n\n// *Slaps roof of fibonacci function*\n// This bad boy returns ints that can get *so* big!\nfunction fibonacci(n: bigint) {\n let result = 1n;\n for (let last = 0n, i = 0n; i < n; i++) {\n const current = result;\n result += last;\n last = current;\n }\n return result;\n}\n\nfibonacci(10000n)
While you might imagine close interaction between number and bigint, the two are separate domains.
\ntsdeclare let foo: number;\ndeclare let bar: bigint;\n\nfoo = bar; // error: Type 'bigint' is not assignable to type 'number'.\nbar = foo; // error: Type 'number' is not assignable to type 'bigint'.
As specified in ECMAScript, mixing numbers and bigints in arithmetic operations is an error.\nYou’ll have to explicitly convert values to BigInts.
\ntsconsole.log(3.141592 * 10000n); // error\nconsole.log(3145 * 10n); // error\nconsole.log(BigInt(3145) * 10n); // okay!
Also important to note is that bigints produce a new string when using the typeof operator: the string \"bigint\".\nThus, TypeScript correctly narrows using typeof as you’d expect.
\ntsfunction whatKindOfNumberIsIt(x: number | bigint) {\n if (typeof x === \"bigint\") {\n console.log(\"'x' is a bigint!\");\n }\n else {\n console.log(\"'x' is a floating-point number\");\n }\n}
We’d like to extend a huge thanks to Caleb Sander for all the work on this feature.\nWe’re grateful for the contribution, and we’re sure our users are too!
\nAs we mentioned, BigInt support is only available for the esnext target.\nIt may not be obvious, but because BigInts have different behavior for mathematical operators like +, -, *, etc., providing functionality for older targets where the feature doesn’t exist (like es2017 and below) would involve rewriting each of these operations.\nTypeScript would need to dispatch to the correct behavior depending on the type, and so every addition, string concatenation, multiplication, etc. would involve a function call.
For that reason, we have no immediate plans to provide downleveling support.\nOn the bright side, Node 11 and newer versions of Chrome already support this feature, so you’ll be able to use BigInts there when targeting esnext.
Certain targets may include a polyfill or BigInt-like runtime object.\nFor those purposes you may want to add esnext.bigint to the lib setting in your compiler options.
TypeScript 3.2 makes narrowing easier by relaxing rules for what it considers a discriminant property.\nCommon properties of unions are now considered discriminants as long as they contain some singleton type (e.g. a string literal, null, or undefined), and they contain no generics.
As a result, TypeScript 3.2 considers the error property in the following example to be a discriminant, whereas before it wouldn’t since Error isn’t a singleton type.\nThanks to this, narrowing works correctly in the body of the unwrap function.
\ntstype Result<T> =\n | { error: Error; data: null }\n | { error: null; data: T };\n\nfunction unwrap<T>(result: Result<T>) {\n if (result.error) {\n // Here 'error' is non-null\n throw result.error;\n }\n\n // Now 'data' is non-null\n return result.data;\n}
tsconfig.json inheritance via Node.js packagesTypeScript 3.2 now resolves tsconfig.jsons from node_modules. When using a bare path for the \"extends\" field in tsconfig.json, TypeScript will dive into node_modules packages for us.
\njson{\n \"extends\": \"@my-team/tsconfig-base\",\n \"include\": [\"./**/*\"]\n \"compilerOptions\": {\n // Override certain options on a project-by-project basis.\n \"strictBindCallApply\": false,\n }\n}
Here, TypeScript will climb up node_modules folders looking for a @my-team/tsconfig-base package. For each of those packages, TypeScript will first check whether package.json contains a \"tsconfig\" field, and if it does, TypeScript will try to load a configuration file from that field. If neither exists, TypeScript will try to read from a tsconfig.json at the root. This is similar to the lookup process for .js files in packages that Node uses, and the .d.ts lookup process that TypeScript already uses.
This feature can be extremely useful for bigger organizations, or projects with lots of distributed dependencies.
\n--showConfig flagtsc, the TypeScript compiler, supports a new flag called --showConfig.\nWhen running tsc --showConfig, TypeScript will calculate the effective tsconfig.json (after calculating options inherited from the extends field) and print that out.\nThis can be useful for diagnosing configuration issues in general.
Object.defineProperty declarations in JavaScriptWhen writing in JavaScript files (using allowJs), TypeScript now recognizes declarations that use Object.defineProperty.\nThis means you’ll get better completions, and stronger type-checking when enabling type-checking in JavaScript files (by turning on the checkJs option or adding a // @ts-check comment to the top of your file).
","headings":[{"value":"strictBindCallApply","depth":2},{"value":"Caveats","depth":2},{"value":"Generic spread expressions in object literals","depth":2},{"value":"Generic object rest variables and parameters","depth":2},{"value":"BigInt","depth":2},{"value":"Caveats","depth":2},{"value":"Non-unit types as union discriminants","depth":2},{"value":"tsconfig.json inheritance via Node.js packages","depth":2},{"value":"The new --showConfig flag","depth":2},{"value":"Object.defineProperty declarations in JavaScript","depth":2}],"frontmatter":{"permalink":"/docs/handbook/release-notes/typescript-3-2.html","title":"TypeScript 3.2"}}},"pageContext":{"slug":"/docs/handbook/release-notes/typescript-3-2.html","isOldHandbook":true}}}js// @ts-check\n\nlet obj = {};\nObject.defineProperty(obj, \"x\", { value: \"hello\", writable: false });\n\nobj.x.toLowercase();\n// ~~~~~~~~~~~\n// error:\n// Property 'toLowercase' does not exist on type 'string'.\n// Did you mean 'toLowerCase'?\n\nobj.x = \"world\";\n// ~\n// error:\n// Cannot assign to 'x' because it is a read-only property.