Detailed explanation of TS numeric separators and stricter class attribute checks

Overview

TypeScript 2.4 implements spelling correction for identifiers. Even if we slightly misspell a variable, property, or function name, TypeScript can suggest the correct spelling in many cases.

TypeScript 2.7 supports the ECMAScript number separator proposal. This feature allows users to group numbers by using underscores (_) between them (just like using commas and periods to group numbers).

const worldPopulationIn2017 = 7_600_000_000;
const leastSignificantByteMask = 0b1111_1111;
const papayawhipColorHexCode = 0xFF_EF_D5;

The digit separators do not change the value of the numeric literal, but the grouping makes the number easier for people to read at a glance.

These separators are also useful for binary and hexadecimal.

let bits = 0b0010_1010;
let routine = 0xC0FFEE_F00D_BED;
let martin = 0xF0_1E_

Note that, although it may be counterintuitive, numbers in JavaScript are not appropriate for credit card and phone numbers; strings are better for this.

When we set the target to the above code compiled by es2015, TypeScript will generate the following js code:

const worldPopulationIn2017 = 7600000000;
const leastSignificantByteMask = 255;
const papayawhipColorHexCode = 16773077;

in operator refinement and precise instanceof

TypeScript 2.7 brings two changes to type refinement - the ability to determine more detailed types by enforcing "type guards".

First, the instanceof operator now utilizes the inheritance chain rather than relying on structural compatibility, which more accurately reflects the behavior of the instanceof operator at runtime. This can help avoid some complications when using instanceof to refine structurally similar (but unrelated) types.

Second, the in operator now acts as a type guard, narrowing down property names that are not explicitly declared.

interface A { a: number };
interface B { b: string };

function foo(x: A | B) {
    if ("a" in x) {
        return xa;
    }
    return xb;
}

Smarter object literal inference

There is a pattern in JS where users will omit some properties, and later when they are used, the value of those properties will be undefined.

let foo = someTest ? { value: 42 } : {};

Previously TypeScript would look for the best supertype of { value: number } and {}, which was {}. This is technically correct, but not very useful.

Starting with version 2.7, TypeScript will “normalize” each object literal type record for each property, insert an optional property for each undefined type property, and union them together.

In the example above, the final type of foo is { value: number } | { value?: undefined }. Combined with TypeScript's fine-grained typing, this allows us to write more expressive code that TypeScript can understand. Let’s look at another example:

// Has type
// | { a: boolean, aData: number, b?: undefined }
// | { b: boolean, bData: string, a?: undefined }
let bar = Math.random() < 0.5 ?
    { a: true, aData: 100 } :
    { b: true, bData: "hello" };

if (bar.b) {
    // TypeScript now knows that 'bar' has the type
    //
    // '{ b: boolean, bData: string, a?: undefined }'
    //
    // so it knows that 'bData' is available.
    bar.bData.toLowerCase()
}

Here, TypeScript can refine the type of bar by inspecting the b property, and then allow us to access the bData property.

Unique symbol type and constant name attributes

TypeScript 2.7 has a deeper understanding of ECMAScript symbols, giving you more flexibility in how you use them.

A highly requested use case is using symbols to declare a well-typed property. For example, consider the following example:

const Foo = Symbol("Foo");
const Bar = Symbol("Bar");

let x = {
    [Foo]: 100,
    [Bar]: "hello",
};

let a = x[Foo]; // has type 'number'
let b = x[Bar]; // has type 'string'

As you can see, TypeScript can track that x has properties declared with the symbols Foo and Bar because Foo and Bar are declared as constants. TypeScript takes advantage of this and gives Foo and Bar a new type: unique symbols.

Unique symbols are subtypes of symbols and can only be generated by calling Symbol() or Symbol.for() or by explicit type annotations. They appear only in constant declarations and read-only static properties, and in order to refer to an existing unique symbol type, you must use the typeof operator. Each reference to a unique symbol implies a completely unique declared identity.

// Works
declare const Foo : unique symbol;

// Error! 'Bar' isn't a constant.
let Bar: unique symbol = Symbol();

// Works - refers to a unique symbol, but its identity is tied to 'Foo'.
let Baz: typeof Foo = Foo;

// Also works.
class C {
    static readonly StaticSymbol: unique symbol = Symbol();
}

Because each unique symbol has a completely independent identity, two unique symbol types cannot be assigned or compared.

const Foo = Symbol();
const Bar = Symbol();

// Error: can't compare two unique symbols.
if (Foo === Bar) {
    // ...
}

Another possible use case is to use symbols as joint markers.

// ./ShapeKind.ts
export const Circle = Symbol("circle");
export const Square = Symbol("square");

// ./ShapeFun.ts
import * as ShapeKind from "./ShapeKind";

interface Circle {
    kind: typeof ShapeKind.Circle;
    radius: number;
}

interface Square {
    kind: typeof ShapeKind.Square;
    sideLength: number;
}

function area(shape: Circle | Square) {
    if (shape.kind === ShapeKind.Circle) {
        // 'shape' has type 'Circle'
        return Math.PI * shape.radius ** 2;
    }
    // 'shape' has type 'Square'
    return shape.sideLength ** 2;
}

Stricter class attribute checking

TypeScript 2.7 introduces a new compiler option for strict property initialization checking in classes. If the --strictPropertyInitialization flag is enabled, the type checker will verify that each instance property declared in a class

• Is there a type that contains undefined?
• There is an explicit initializer
• Definitely assigned in the constructor

The --strictPropertyInitialization option is part of the family of compiler options and is automatically enabled when the --strict flag is set. As with all other strict compiler options, we can set --strict to true and selectively opt out of strict property initialization checking by setting --strictPropertyInitialization to false.

Note that the --strictNullCheck flag must be set (either directly or indirectly via --strict) in order for --strictPropertyInitialization to have any effect.

Now, let's look at strict property initialization checking. Without the --strictpropertyinitialized flag enabled, the following code will type check fine, but will generate a TypeError at runtime:

class User {
  username: string;
}

const user = new User();

// TypeError: Cannot read property 'toLowerCase' of undefined
const username = user.username.toLowerCase();

The reason for the runtime error is that the username property value is undefined because no value has been assigned to the property. Therefore, the call to the toLowerCase() method fails.

If you enable --strictpropertyinitialize, the type checker will report an error:

class User {
  // Type error: Property 'username' has no initializer
  // and is not definitely assigned in the constructor
  username: string;
}

Next, let’s look at four different ways that we can correctly type our User class to eliminate type errors.

Solution 1: Allow definition

One way to eliminate the type error is to give the username property a type that includes undefined:

class User {
  username: string | undefined;
}

const user = new User();

Now, it is perfectly valid for the username property to hold the value undefined. However, when we want to use the username property as a string, we first have to make sure that it actually contains a string and not an undefined value, for example using typeof

// OK
const username = typeof user.username === "string"
  ? user.username.toLowerCase()
  : "n/a";

Solution 2: Explicit property initialization

Another way to eliminate the type error is to add an explicit initializer to the username property. This way the property will immediately hold a string value and won’t be undefined :

class User {
  username = "n/a";
}

const user = new User();

// OK
const username = user.username.toLowerCase();

Solution 3: Use constructor assignment

Perhaps the most useful solution is to add a username parameter to the constructor, and then assign it to the username property. Thus, whenever an instance of the User class is constructed, the caller must provide the username as an argument:

class User {
  username: string;

  constructor(username: string) {
    this.username = username;
  }
}

const user = new User("mariusschulz");

// OK
const username = user.username.toLowerCase();

We can also simplify the User class by removing the explicit assignment to the class fields and adding the public modifier to the username constructor parameter, as follows:

class User {
  constructor(public username: string) {}
}

const user = new User("mariusschulz");

// OK
const username = user.username.toLowerCase();

Note that strict property initialization requires that every property be explicitly assigned in all possible code paths within the constructor. Therefore, the following code is not type correct because in some cases we are assigning the username property to an uninitialized state:

class User {
  // Type error: Property 'username' has no initializer
  // and is not definitely assigned in the constructor.
  username: string;

  constructor(username: string) {
    if (Math.random() < 0.5) {
      this.username = username;
    }
  }
}

Solution 4: Explicit Assignment Assertions

If a class property is neither explicitly initialized nor has a type of undefined , the type checker requires that the property be initialized directly in the constructor; otherwise, the strict property initialization check fails. This is problematic if we want to initialize properties in helper methods or have a dependency injection framework initialize properties for us. In these cases, we must add an explicit assignment assertion (!) to the property's declaration:

class User {
  username!: string;

  constructor(username: string) {
    this.initialize(username);
  }

  private initialize(username: string) {
    this.username = username;
  }
}

const user = new User("mariusschulz");

// OK
const username = user.username.toLowerCase();

By adding a definite assignment assertion to the username property, this tells the type checker that it expects the username property to be initialized, even if it cannot detect this on its own. It is now our responsibility to ensure that we explicitly assign the property to it after the constructor returns, so we must be careful; otherwise, the username property may be explicitly undefined or a TypeError may be raised at runtime.

Explicit Assignment Assertions

While we try to make the type system as expressive as possible, we know that sometimes users understand types better than TypeScript does.

As mentioned above, explicit assignment assertions are a new syntax that you use to tell TypeScript that a property will be explicitly assigned a value. But in addition to using it on class properties, with TypeScript 2.7 you can also use it on variable declarations!

let x!: number[];
initialize();
x.push(4);

function initialize() {
    x = [0, 1, 2, 3];
}

If we hadn’t put an exclamation mark after x, TypeScript would have reported that x had never been initialized. It is convenient to use in scenarios where lazy initialization or reinitialization is required.

The above is a detailed explanation of TS numeric separators and stricter class attribute checks. For more information about TS, please pay attention to other related articles on 123WORDPRESS.COM!