Y
Published on

Understanding Control Flow Analysis in TypeScript

Authors
  • avatar
    Name
    Yinhuan Yuan
    Twitter

Introduction

TypeScript's type system is not just about static type checking. It also performs sophisticated control flow analysis to understand how types change throughout your code. This analysis allows TypeScript to make intelligent decisions about types based on the structure and flow of your program. In this blog post, we'll explore various aspects of control flow analysis in TypeScript, including Narrowing, Widening, Type Guards, Type Predicates, Discriminated Unions, and Assertion Functions.

1. Narrowing

Narrowing is the process where TypeScript refines types to more specific types than declared. This happens when TypeScript analyzes your code and can guarantee that a variable is of a more specific type.

function padLeft(padding: number | string, input: string) {
  if (typeof padding === 'number') {
    // TypeScript knows padding is a number here
    return ' '.repeat(padding) + input
  }
  // TypeScript knows padding is a string here
  return padding + input
}

In this example, TypeScript narrows the type of padding based on the typeof check.

2. Widening

Widening is the opposite of narrowing. It's when TypeScript expands a type to a more general type. This often happens with literal types:

let x = 3 // TypeScript infers x as number, not 3
let y = 'hello' // TypeScript infers y as string, not "hello"

const z = 3 // TypeScript infers z as 3 (literal type)

3. Type Guards

Type guards are expressions that perform a runtime check that guarantees the type in some scope. TypeScript uses these to narrow types.

function isString(test: any): test is string {
  return typeof test === 'string'
}

function example(x: string | number) {
  if (isString(x)) {
    // TypeScript knows x is a string here
    console.log(x.toUpperCase())
  } else {
    // TypeScript knows x is a number here
    console.log(x.toFixed(2))
  }
}

4. Type Predicates

Type predicates are the return types of type guard functions. They take the form parameterName is Type.

interface Bird {
  fly(): void
  layEggs(): void
}

interface Fish {
  swim(): void
  layEggs(): void
}

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined
}

function move(pet: Fish | Bird) {
  if (isFish(pet)) {
    // TypeScript knows pet is Fish here
    pet.swim()
  } else {
    // TypeScript knows pet is Bird here
    pet.fly()
  }
}

5. Discriminated Unions

Discriminated unions are a pattern in TypeScript where you use a common property to narrow down the possible types of a value.

interface Square {
  kind: 'square'
  size: number
}

interface Rectangle {
  kind: 'rectangle'
  width: number
  height: number
}

type Shape = Square | Rectangle

function area(s: Shape) {
  switch (s.kind) {
    case 'square':
      // TypeScript knows s is Square here
      return s.size * s.size
    case 'rectangle':
      // TypeScript knows s is Rectangle here
      return s.width * s.height
  }
}

6. Assertion Functions

Assertion functions are functions that throw an error if a condition is not met. TypeScript uses these to narrow types.

function assert(condition: any, msg?: string): asserts condition {
  if (!condition) {
    throw new AssertionError(msg)
  }
}

function yell(str: any) {
  assert(typeof str === 'string')
  // TypeScript knows str is a string here
  return str.toUpperCase()
}

You can also use type predicates with assertion functions:

function assertIsString(val: any): asserts val is string {
  if (typeof val !== 'string') {
    throw new AssertionError('Not a string!')
  }
}

function yell(str: any) {
  assertIsString(str)
  // TypeScript knows str is a string here
  return str.toUpperCase()
}

7. The as const Assertion

The as const assertion, also known as the const assertion, is a powerful feature in TypeScript that allows you to signal to the compiler that it should infer the most specific type possible for an expression.

Basic Usage

When you use as const on a value, TypeScript will:

  1. Infer literal types instead of wider primitive types
  2. Make all properties readonly
  3. Make arrays readonly tuples
// Without as const
let x = 'hello' // Inferred as string
let y = 42 // Inferred as number
let z = true // Inferred as boolean

// With as const
let a = 'hello' as const // Inferred as "hello"
let b = 42 as const // Inferred as 42
let c = true as const // Inferred as true
Objects and Arrays

as const is particularly useful with objects and arrays:

// Without as const
const obj = { x: 10, y: [20, 30], z: 'hello' }
// Inferred as: { x: number; y: number[]; z: string; }

// With as const
const objConst = { x: 10, y: [20, 30], z: 'hello' } as const
// Inferred as: { readonly x: 10; readonly y: readonly [20, 30]; readonly z: "hello"; }

In the objConst example, all properties become readonly, and the array y becomes a readonly tuple.

Use in Control Flow Analysis

The as const assertion can be particularly useful in control flow analysis scenarios, especially when working with discriminated unions:

type Action =
  | { type: 'INCREMENT'; amount: number }
  | { type: 'DECREMENT'; amount: number }
  | { type: 'RESET' }

// Without as const
const incrementAction = { type: 'INCREMENT', amount: 5 }
// Inferred as: { type: string; amount: number }

// With as const
const incrementActionConst = { type: 'INCREMENT', amount: 5 } as const
// Inferred as: { readonly type: "INCREMENT"; readonly amount: 5 }

function reducer(state: number, action: Action) {
  switch (action.type) {
    case 'INCREMENT':
      return state + action.amount
    case 'DECREMENT':
      return state - action.amount
    case 'RESET':
      return 0
  }
}

// This works
reducer(0, incrementActionConst)

// This doesn't work - TypeScript error
reducer(0, incrementAction)
// Argument of type '{ type: string; amount: number; }' is not assignable to parameter of type 'Action'.

In this example, using as const ensures that the incrementActionConst object matches the Action type exactly, allowing it to be used with the reducer function without any type errors.

Limitations and Considerations

While as const is powerful, it's important to use it judiciously:

  1. Once a value is marked with as const, it becomes deeply readonly. This can be limiting if you need to modify the value later.
  2. For large objects or arrays, using as const can lead to very verbose inferred types, which might impact editor performance and readability.
  3. as const doesn't work with let declarations in the same way it does with const. The value can still be reassigned, even if its type is narrowed.
let x = 'hello' as const // x is still of type "hello"
x = 'world' // Error: Type '"world"' is not assignable to type '"hello"'.

The as const assertion is a powerful tool in TypeScript's type system, allowing for more precise type inference and enabling stricter type checking in many scenarios. When used appropriately, it can significantly enhance the type safety of your code, especially in scenarios involving literal types and discriminated unions.

Conclusion

Control flow analysis in TypeScript is a powerful feature that allows the type system to make intelligent decisions based on the structure and flow of your code. By understanding and leveraging narrowing, widening, type guards, type predicates, discriminated unions, and assertion functions, you can write more type-safe code and catch more errors at compile-time.

Remember, while these features are powerful, they should be used judiciously. Overuse can lead to complex type logic that can be hard to understand and maintain. Always strive for a balance between type safety and code readability.

Discuss on Twitter • View on GitHub