[Typescript] Tuple type usage example & Discriminated Unions

function flipCoin(): "heads" | "tails" {
  if (Math.random() > 0.5) return "heads"
  return "tails"
}

function maybeGetUserInfo():
  | ["error", Error]
  | ["success", { name: string; email: string }] {
  if (flipCoin() === "heads") {
    return [
      "success",
      { name: "Mike North", email: "mike@example.com" },
    ]
  } else {
    return [
      "error",
      new Error("The coin landed on TAILS :("),
    ]
  }
}

Working with union types

Let’s continue with our example from above and attempt to do something with the “outcome” value.

const outcome = maybeGetUserInfo()
 
const [first, second] = outcome

first  // const first: "error" | "success"
second // const second: Error | {
       //    name: string;
       //    email: string;
       // }

We can see that the autocomplete information for the first value suggests that it’s a string. This is because, regardles of whether this happens to be the specific "success" or "error" string, it’s definitely going to be a string.

The second value is a bit more complicated — only the name property is available to us. This is because, both our “user info object, and instances of the Error class have a name property whose value is a string.

What we are seeing here is, when a value has a type that includes a union, we are only able to use the “common behavior” that’s guaranteed to be there.

Narrowing with type guards

Ultimately, we need to “separate” the two potential possibilities for our value, or we won’t be able to get very far. We can do this with type guards.

const outcome = maybeGetUserInfo()
const [first, second] = outcome

if (second instanceof Error) {
  // In this branch of your code, second is an Error
  second
} else {
  // In this branch of your code, second is the user info
  second
}

TypeScript has a special understanding of what it means when our instanceof check returns true or false, and creates a branch of code that handles each possibility.

It gets even better…

Discriminated Unions

const outcome = maybeGetUserInfo()
if (outcome[0] === "error") {
  // In this branch of your code, second is an Error
  outcome // const outcome: ["error", Error]
} else {
  outcome 
  /*
  const outcome: ["success", {
    name: string;
    email: string;
  }]*/
}

TypeScript understands that the first and second positions of our tuple are linked. What we are seeing here is sometimes referred to as a discriminated or “tagged” union type.