.TS File Format – Narrowing

Control-flow analysis

Since 2.0 the compiler follows if, return, throw, break, loops and assignments, and gives each use of a variable the type that is possible at that point.

function pad(value: string | number) {
  if (typeof value === "number") {
    return value.toFixed(2);     // number here
  }
  return value.trim();           // string here: the number case returned
}

function reassign() {
  let x: string | number = "a";  // narrowed to string by the assignment
  x.toUpperCase();
  x = 1;                         // now number
  x.toFixed();
  x = true;                      // error: the declared type still applies
}

Narrowing applies to a variable, a parameter, or a path of property accesses such as a.b.c. A property’s narrowing lasts until the code assigns to any part of that path. A function call does not end it, even though the function could change the property.

function urls(url: string | undefined, names: string[]) {
  if (url === undefined) url = "/";         // last assignment
  return names.map(name => url.length);     // string in 5.4 and later
}

function later(x: string | undefined) {
  if (x === undefined) return;
  function hoisted() {
    x.length;                               // error: possibly undefined
  }
}

function f(x: unknown) {
  const isString = typeof x === "string";
  if (isString) x.toUpperCase();   // fine
}

Type guards

function t(x: string[] | null) {
  if (typeof x === "object") {
    x.length;          // error: null is also "object" in JavaScript
  }
}

function e(a: string | number, b: string | boolean) {
  if (a === b) {
    a.toUpperCase();   // both are string here
  }
}

function q(o: Record<string, unknown>, k: string) {
  if (typeof o[k] === "string") {
    o[k].toUpperCase();   // 5.5: narrows when o and k do not change
  }
}

Discriminated unions

A union of object types with a common property of literal type can be narrowed by testing that property. The property, called a discriminant, may be a string, number or boolean literal, a template pattern (4.5), or undefined.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.radius ** 2;
    case "square": return s.side ** 2;
    default: {
      const unreachable: never = s;   // an error here if a case is missing
      return unreachable;
    }
  }
}

type Result =
  | { ok: true; value: number }
  | { ok: false; error: Error };

function use(r: Result) {
  if (r.ok) r.value; else r.error;
}

Since 4.6, destructured parameters and const variables narrow together: after function f({ kind, v }: Action), testing kind narrows v.

Type predicates

A function whose return type is x is T tells the compiler that when it returns true, the argument is a T, and when it returns false, it is not. The type must be assignable to the parameter’s type. The compiler does not verify the body, so a wrong predicate is as unsafe as an assertion.

function isString(x: unknown): x is string {
  return typeof x === "string";
}

class Shape {
  isCircle(): this is Circle { return this instanceof Circle; }
}
class Circle extends Shape { radius = 1; }

function f(s: Shape) {
  if (s.isCircle()) s.radius;
}

Since 5.5 the compiler can infer a predicate for a function with no return annotation, when it has a single return of a boolean expression that tests the parameter, does not change the parameter, and the false result also means the parameter is not that type.

const isNumber = (x: unknown) => typeof x === "number";
// inferred: (x: unknown) => x is number

const nums = [1, null, 3].filter(x => x !== null);   // number[]

Assertion functions

An assertion function (3.7) throws when a condition fails, and narrows the code that follows it. The call must be an expression statement, and the function must be reachable through names with explicit type annotations. A const arrow function needs an annotation on the variable.

AssertsReturnType:
    asserts ParameterName [is Type]
    asserts this [is Type]

function assert(condition: unknown, message?: string): asserts condition {
  if (!condition) throw new Error(message);
}

function assertString(x: unknown): asserts x is string {
  if (typeof x !== "string") throw new TypeError();
}

function f(x: unknown) {
  assert(typeof x === "string");
  x.toUpperCase();          // string from here on
}

const arrow = (c: unknown): asserts c => {};
function g(x: unknown) {
  arrow(typeof x === "string");   // error: arrow needs an annotation on its name
}

const typed: (c: unknown) => asserts c = assert;   // fine

A call to a function declared to return never also ends the path, under the same rule about annotations.

Type assertions

x as T tells the compiler to treat x as T, and produces no code. T must be more or less specific than the type of x; otherwise the assertion is an error and must go through unknown. The older form <T>x means the same but cannot be used in .tsx files.

const a = "x" as string;
const b = "x" as number;              // error: not related
const c = "x" as unknown as number;   // allowed, and unsafe

const el = document.getElementById("a") as HTMLCanvasElement;

const a = ["x", 1] as const;       // readonly ["x", 1]
const b = { p: { q: 1 } } as const; // { readonly p: { readonly q: 1 } }
const c = -1 as const;             // -1
const d = (1 + 1) as const;        // error
const e = (() => 1) as const;      // error

type RGB = [number, number, number];

const palette = {
  red: [255, 0, 0],
  green: "#00ff00",
} satisfies Record<string, string | RGB>;

palette.green.toUpperCase();   // fine: green stays string
palette.red.map(n => n);       // fine: red is RGB

const wrong = { red: 1 } satisfies Record<string, string>;    // error

const t = [1, 2] satisfies [number, number];   // [number, number], not number[]
const k = { kind: "a" } satisfies { kind: "a" | "b" };  // kind is "a"

Checks on constant conditions

Since 5.6, a condition that is known from its syntax alone to be always truthy or always nullish is an error, such as if (/x/) with the .test() forgotten, or if (x => 0). true, false, 0 and 1 are exempt. Since 5.7, a variable that is never assigned anywhere is reported as an error even if it is read inside a nested function.