Our application data comes in all shapes and sizes. We choose the best data structures for our problem, but when we need to put a variety of our data through the same pipeline, we have to manage safely distinguishing our data types and handling all their possible variations.

In this post, I want to share a pattern I’ve discovered for working with different data types in a homogenous way. You can think of it as a functional programming version of the adapter pattern. I’ll introduce the concept of pattern matching, generic enums, and look at how we can leverage the power of TypeScript to mimic these patterns.

The code examples here are hosted in a more fully functioning version at github.com/alexsasharegan/colorjs.

What Is Pattern Matching?

At its simplest, it’s a control flow structure that allows you to match type/value patterns against a value. Pattern matching is usually a feature of functional programming languages like Haskell, Elixir, Elm, Reason, and more. Some languages, like Rust, offer pattern matching while not fitting neatly into the functional category. Consider this Rust code:

let x = 1;

match x {
    1 => println!("One"),
    2 | 3 => println!("Two or Three"),
    4 .. 10 => println!("Four through Ten"),
    _ => println!("I match everything else"),
}

Here the match expression evaluates x against the patterns inside the block and then executes the corresponding match arm’s expression/block. Patterns are evaluated and matched in top-down order. The first pattern is the literal value 1; the second matches either a 2 or a 3; the third describes a range pattern from 4 to 10; the last pattern is a curious bit of syntax shared by many pattern matching systems that denotes a “catch-all” pattern that matches anything.

Most pattern matching systems also come with compile-time exhaustiveness checking. The compiler checks all the match expressions and evaluates them to guarantee that one of the arms will be matched. If the compiler cannot guarantee the match expression is exhaustive, the program will fail to compile. Some compilers can also lint your match expressions to warn when a match arm shadows a subsequent match arm because it is more general than a later, more specific arm. Exhaustiveness checks are a really powerful tool to avoid bugs in our code.

Pattern Matching With Enums

Enums exist in various languages, but apart from enumerating a named set, Rust’s enum members are capable of holding values. Here’s an example from the rust book:

enum IpAddr {
    V4(u8, u8, u8, u8),
    V6(String),
}

let home = IpAddr::V4(127, 0, 0, 1);
let loopback = IpAddr::V6(String::from("::1"));

The IpAddr enum type has two members: V4 and V6. Note that each can hold different types. This is a really powerful way to model real-world problems. Different cases often come with different data modeling concerns. An IPv4 can be easily modeled with a tuple of 4 bytes (u8), while an IPv6 has many valid expressions that a string covers. Combining enums with values affords us a type-safe way to model each case with the optimal data structure.

Applying Pattern Matching In TypeScript

Now let’s see if we can implement some Rust-like enum and pattern matching capabilities. For our example, we’re going to implement a color enum capable of matching against three distinct color types–RGB, HSL, and Hex. We’ll start by stubbing out some classes. We could also use plain JavaScript objects, but we’ll use classes for a little extra convenience.

class RGBColor {
  constructor(public r: number, public g: number, public b: number) {}
}
class HSLColor {
  constructor(public h: number, public s: number, public l: number) {}
}
class HexColor {
  constructor(public hex: string) {}
}

If you’re unfamiliar with the empty-looking constructor syntax, it’s a shorthand to initialize properties. By declaring an access modifier (public, protected, private), typescript automatically generates the code to assign the name of the constructor argument as a class property. It might feel a little like magic (which I normally avoid), but it’s such a common pattern that I prefer to let the TS compiler reliably do the work for me.

Step 1: Enum

To start, we need to represent all our possible states. In our case, this will be the three color types. TypeScript has an enum type, but it does not hold generic values like in Rust. TS enums create a set of named constants of numbers or strings. We’ll want to use string enums since they will play nicer later on when used as object keys.

enum ColorFormat {
  Hex = "hex",
  RGB = "rbg",
  HSL = "hsl",
}

Since enum is not available in JS, I think it’s worth looking at how TypeScript implements enum.

var ColorFormat;
(function(ColorFormat) {
  ColorFormat["Hex"] = "hex";
  ColorFormat["RGB"] = "rbg";
  ColorFormat["HSL"] = "hsl";
})(ColorFormat || (ColorFormat = {}));

The TS compiler constructs a lookup table from our enum keys to their values using a plain JavaScript object. In the case of numeric enums, it also constructs a reverse lookup from values to keys in the same object. JS objects can only have strings, numbers (which are cast to strings), and symbols as keys, but TS only supports using string or number enums.

Step 2: Discriminated Unions

While the name sounds complex, the concept is straightforward. It’s essentially a set of different object shapes that, while different, all share a common key. This key, the discriminant, enables TypeScript to distinguish between the object types because its value is a literal value. A literal value would be something like "foo" instead of string, or 1 instead of number.

Here’s an example taken from Marius Schulz’s TypeScript blog (which you should definitely check out):

interface Cash {
  kind: "cash";
}
interface PayPal {
  kind: "paypal";
  email: string;
}
interface CreditCard {
  kind: "credit";
  cardNumber: string;
  securityCode: string;
}

// PaymentMethod is the discriminated union of Cash, PayPal, and CreditCard
type PaymentMethod = Cash | PayPal | CreditCard;

Each interface has a unique shape, but all share the key kind. Notice the literal string values like "credit" used in the discriminant. When you receive the type PaymentMethod, TypeScript will not let you access any of the unique properties until you “discriminate” which shape it is by asserting the kind is "cash", "paypal", or "credit".

We can use POJO’s (Plain Old JavaScript Objects) for our object types, or we can use classes. I’m going to use classes, but we’re going to look at examples of both. Using classes will allow us to implement a more ergonomic match later on. We need to use the readonly modifier on our discriminant key so the TS compiler knows the format value won’t change.

// previous code omitted for brevity
class RGBColor {
  readonly format = ColorFormat.RGB;
}
class HSLColor {
  readonly format = ColorFormat.HSL;
}
class HexColor {
  readonly format = ColorFormat.Hex;
}

type Color = HexColor | RGBColor | HSLColor;

Now we’ve defined our union of possible colors. We used the classes as types here for brevity, but defining the colors as interfaces (which our classes satisfy) would make our union more flexible.

Step 3: Matcher Objects

Next we’re going to create an object that behaves like our rust pattern match. The keys of our object will correspond with the values of our enum–this is why we needed to use string enums. Our values can’t be expressions because in JavaScript they will be evaluated immediately. To ensure lazy evaluation only when a condition is matched, we need the values to be functions.

type ColorMatcher<Out> = {
  [ColorFormat.Hex]: (color: HexColor) => Out;
  [ColorFormat.HSL]: (color: HSLColor) => Out;
  [ColorFormat.RGB]: (color: RGBColor) => Out;
};

The ColorMatcher object requires us to pass an object with all the keys present. This forces our code to handle all the possible states. Its also generic over a single return value type. This can feel limiting at first, but in practice reduces code complexity and bugs.

Step 4: Match Implementation

Since we don’t have real match semantics in JavaScript, we can make use of a switch statement. Our function will need to accept as arguments: our Color union type with the discriminant from step 2, and our matcher object from step 3. We’ll switch on our color’s discriminant property, and once the discriminant is matched by a case, TypeScript can infer the sub-type of Color to be Hex, HSL, or RGB. The compiler will also make sure we invoke the correct matcher function based on the inferred type. The implementation looks like this:

function matchColor<Out>(color: Color, matcher: ColorMatcher<Out>): Out {
  switch (color.format) {
    default:
      return expectNever(color);
    case ColorFormat.Hex:
      return matcher[ColorFormat.Hex](color);
    case ColorFormat.HSL:
      return matcher[ColorFormat.HSL](color);
    case ColorFormat.RGB:
      return matcher[ColorFormat.RGB](color);
  }
}

It’s worth mentioning that when the Color type is defined as a union of interfaces, the argument value can be either a POJO or a class instance–both types would satisfy the expected properties. Also note the helper func, expectNever. The function leverages the never type in a clever way to give us compile-time exhaustiveness checking. In short, the never type is how TypeScript expresses an impossible state. If you’d like to know more, Marius Schulz has another great blog post going deeper into the subject.

function expectNever(_: never, message = "Non exhaustive match."): never {
  throw new Error(message);
}

Since we opted to use classes, we can improve upon the matchColor function by implementing a match method each color class in our Color union. Since the method is defined on the class, our match method implementation will only need the ColorMatcher argument–a nice bonus for ergonomics. It can then call the correct the match “arm” with itself.

class RGBColor {
  match<Out>(matcher: ColorMatcher<Out>): Out {
    return matcher[ColorFormat.RGB](this);
  }
}
class HSLColor {
  match<Out>(matcher: ColorMatcher<Out>): Out {
    return matcher[ColorFormat.HSL](this);
  }
}
class HexColor {
  match<Out>(matcher: ColorMatcher<Out>): Out {
    return matcher[ColorFormat.Hex](this);
  }
}

Step 5: Usage

We’ve got all the pieces in place to finally start making using our color classes. We can start adding/refactoring functions to accept a Color. This will allow callers to use whatever is most convenient to them–HSL, RGB, or Hex.

We could use our Color as a prop in components:

interface Props {
  color: Color;
}

function BgColor(props: Props) {
  let backgroundColor = props.color.match({
    hsl: color => `hsl(${color.h}, ${color.s}%, ${color.l}%)`,
    rgb: color => `rgb(${color.r}, ${color.g}, ${color.b})`,
    hex: color => `#${color.hex}`,
   });

   return <div style={{backgroundColor}}>{{props.children}}</div>
}

We could also implement some color conversion helpers and create some sass-like helpers like this:

function lighten(color: Color, percent: number): HSL {
  let hsl = color.match({
    // Already our preferred type, so just return it.
    hsl: c => c,
    rgb: c => convertRGBToHSL(c),
    hex: c => convertHexToHSL(c),
  });

  hsl.l = Math.min(100, hsl.l + percent);

  return hsl;
}
function darken(color: Color, percent: number): HSL {
  let hsl = color.match({
    hsl: c => c,
    rgb: c => convertRGBToHSL(c),
    hex: c => convertHexToHSL(c),
  });

  hsl.l = Math.max(0, hsl.l - percent);

  return hsl;
}

The HSL format is the easiest to lighten or darken, so these functions just convert to HSL, and then raise/lower the lightness. Notice that while the argument we accept is of type Color, we return an HSL instance. We could have chosen to return Color.

A best practice when using these tagged unions is to accept the widest (practical) range of types, but return the most exact type. If we returned Color to our callers, they would need to match yet again to determine that we returned an HSL color–something we already knew.

Pros & Cons

Matching custom data types with this pattern can be really powerful. Our code clearly documents all the possible states in our enums–a benefit for newcomers to our code as well as ourselves down the road. Our matcher objects also force us to acknowledge every possible state whenever we interact with our data. If we’re in a hurry to implement a feature, the compiler is there to make sure we didn’t forget anything. The matcher object’s consistent return type will help us avoid bugs. It’s hard to explain just how important this is, but in my experience, it’s changed a lot about the way I code and reduced a lot of needless bugs.

All the benefits don’t come without a cost though. This pattern is quite verbose and requires a lot of boilerplate. We are mimicking syntax that doesn’t exist in JavaScript, so the verbosity is an understandable trade-off, but one you’ll have to consider when deciding whether or not your situation will be improved by using this pattern. As a library author, I find this to be a solid foundation on which to build my custom data types. I push the verbosity down to the library level so I can provide convenience and clarity to the library consumer.

For further reading on this subject, you can check out a similar post by another community member, Manual Alabor: https://pattern-matching-with-typescript.alabor.me/.

In my next couple of posts (TBD), I’m going explain some more functional programming-inspired patterns that leverage this matching pattern under the hood to provide an abstraction and a framework for handling nullable types, robust error handling, and creating robust, chainable task pipelines.