Assertion functions & user-defined type guards

Intro

Assertion function

function assertIsString(x: unknown): asserts x is string {
  if (typeof x !== "string") {
    throw new Error("Expected string");
  }
}

let v: unknown = Math.random() > 0.5 ? "ok" : 42;
assertIsString(v); // after this, v is string
console.log(v.toUpperCase());

Type guard function

type Circle = { kind: "circle"; radius: number };
type Square = { kind: "square"; size: number };

type Shape = Circle | Square;

function isCircle(s: Shape): s is Circle {
  return s.kind === "circle";
}

function area(s: Shape): number {
  if (isCircle(s)) {
    return Math.PI * s.radius ** 2; // s is Circle here
  }
  return s.size * s.size; // s is Square here
}

console.log(area({ kind: "circle", radius: 2 }));

Guards in filter

type Item = { id: number } | null | undefined;

function isPresent<T>(x: T | null | undefined): x is T {
  return x != null;
}

const items: Item[] = [{ id: 1 }, null, undefined, { id: 2 }];
const present = items.filter(isPresent);
// present has type { id: number }[]
console.log(present.map(i => i.id));

Assert on runtime data

function parseJson(s: string): unknown {
  return JSON.parse(s);
}

try {
  const data = parseJson("{\"name\":\"Ada\"}");
  assertIsString(data); // will throw, because data is object
} catch (e) {
  console.log("Handled:", e instanceof Error ? e.message : e);
}

Guidelines

Assertion function check

Recap