Nanoprogrammed Penultimate Musicianship

    unreachable
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    unreachable

    travis package downloads styled with prettier

    Utility function for exhaustiveness checking with (typed) JS (Be it TypeScript or Flow)

    Problem

    Exhaustiveness checking for Tagged Unions

    Tagged unions are present in both in Flow reffered as Disjoint Unions and in TypeScript referred as Discriminated Unions. Unfortunately both utilize JS switch statements for pattern matching that comes with inherent limitations.

    Consider following example that is both flow & typescript code:

    type Shape =
      | { kind: "square", size: number }
      | { kind: "rectangle", width: number, height: number }
      | { kind: "circle", radius: number }
     
    const area = (shape: Shape):number => {
      switch (shape.kind) {
        case "square":
          return shape.size * shape.size
        case "rectangle":
          return shape.height * shape.width
        case "circle":
          return Math.PI * shape.radius ** 2
      }
    }

    Exhaustiveness problem (Flow)

    As of this writing Flow (0.49.1) fails to typecheck as it's still unable to detect exhaustive type refinements and there requires default case:

    /* @flow */
     
    type Shape =
      | { kind: "square", size: number }
      | { kind: "rectangle", width: number, height: number }
      | { kind: "circle", radius: number }
     
    const area = (shape: Shape):number => {
      switch (shape.kind) {
        case "square":
          return shape.size * shape.size
        case "rectangle":
          return shape.height * shape.width
        case "circle":
          return Math.PI * shape.radius ** 2
        default:
          throw new TypeError(`Unsupported shape was passed: ${JSON.stringify(shape)}`)
      }
    }

    But that is not ideal as type checker will no longer be able to catch errors if we add variant to our Shape union:

    type Shape =
      | { kind: "square", size: number }
      | { kind: "rectangle", width: number, height: number }
      | { kind: "circle", radius: number }
      | { kind: "triangle", a:number, b:number, c:number } // <- added variant

    Last version of area function will still type check and accept triangles but type checker will not be able to report an error instead we'll get one at runtime.

    JS call site problem

    As of this writing TypeScript (2.4) with strictNullChecks has a proper [exhaustiveness checking][] support and there for is free of the [Exhaustiveness problem][#Exhaustiveness_problem_flow] & original code type checkes fine, it also will not type check if more variants are added to Shape union and unless area funciton is also modified to handle that.

    Still original code is not ideal if call site (of area) function is not type checked, if say call site is JS like code below:

    area({ kind:"circl", radius:7 }) // => undefined

    There will be no erros reported by area function it will just return undefined instead of number and likely causing error down the line that is harded to track down. And that is where this library can help, in fact it just provides a function that TypeScript Handbook recommends as a good practice.

    Solution

    This library provides default export function that takes single argument of the bottom type, which denotes type of the value that can never occur and throws a TypeError with helpful message when invoked. In TypeScript it is referred as never and in Flow it (is not yet documented, but) is referred as empty.

    import unreachable from "unreachable"
     
    type Shape =
      | { kind: "square", size: number }
      | { kind: "rectangle", width: number, height: number }
      | { kind: "circle", radius: number }
     
    const area = (shape: Shape):number => {
      switch (shape.kind) {
        case "square":
          return shape.size * shape.size
        case "rectangle":
          return shape.height * shape.width
        case "circle":
          return Math.PI * shape.radius ** 2
        default:
          return unreachable(shape)
      }
    }

    Above code type checks both in Flow and TypeScript. While following code does not type check:

    import unreachable from "unreachable"
     
    type Shape =
      | { kind: "square", size: number }
      | { kind: "rectangle", width: number, height: number }
      | { kind: "circle", radius: number }
      | { kind: "triangle", a:number, b:number, c:number } // <- Added variant
     
    const area = (shape: Shape):number => {
      switch (shape.kind) {
        case "square":
          return shape.size * shape.size
        case "rectangle":
          return shape.height * shape.width
        case "circle":
          return Math.PI * shape.radius ** 2
        default:
          return unreachable(shape)
      }
    }

    Flow will report that shape:Shape is incompatible with expected empty type. TypeScript will report that { kind: "triangle"; a: number; b: number; c: number; } is incompatible with never.

    Obviously type checker won't help with incorrect call from JS call site, but at least it will throw an exception from the shape function with helpful message and stack trace leading to the source of the error:

    area({ kind:"circl", radius:7 })
    //> TypeError('Internal error: Encountered impossible value: { kind:"circl", radius:7 }')

    Install

    npm install unreachable
    

    Prior Art

    Somewhat inspired by Rust unreachable macro.

    Install

    npm i unreachable

    DownloadsWeekly Downloads

    227

    Version

    0.2.0

    License

    MIT

    Last publish

    Collaborators

    • gozala