DEV Community: Alex Regan

Build An Intersection Observer Directive In Vue

Alex Regan — Thu, 06 Jun 2019 13:56:42 +0000

In this post, I want to share my experience integrating the IntersectionObserver API into a Vue app. By the end, we'll have a custom directive that abstracts dynamically registering and unregistering DOM elements with an observer.

Intersection Observer

When you need to track an element coming into view, watching document scroll and calculating element offsets used to be the only way. The math isn't particularly complex, but knowing which layout properties to use and just how to calculate position relative to the right elements is a painful task. In addition, since scroll fires a large amount of events very rapidly, it's easy to cause jank if your calculations and subsequent processing exceeds the frame budget--most likely because too many events are being processed within a single frame.

Enter the IntersectionObserver. Aptly named, an instance of IntersectionObserver can observe many elements and invoke a callback when elements intersect or stop intersecting with the viewport or another element (usually some scrollable container). The built-in class is able to efficiently calculate intersection, and it does so with much simpler code (no math!). On top of this nice abstraction, IntersectionObserver also handles scenarios that are often forgotten (like resize events) as well as extra difficult scenarios (like <iframe> elements).

Before we start integrating this API into Vue, here are resources for more background on Vue directives and IntersectionObserver:

Getting Started

One of the first challenges of using IntersectionObserver in Vue is that our component's DOM is an artifact of our template and state. Declarative, component UI aims to keep us away from the DOM, but working with our observer requires plugging it into our real elements, not our template. This means we have to get our hands dirty, dig into our components raw elements, and be wary of the component lifecycle.

Quick And Dirty

First things first: let's just prototype something and make it work. I'm going to start with a codesandbox vue project, and replace the App.vue component with a big list of items to overflow the viewport. With some scrollable dummy content, we can task ourselves with detecting when an item comes in/out of view.

Make A Big List

Let's start by making our overflowing list. To create a list of dummy elements, we'll use a computed property called range. This property doesn't use any fields from the component instance, so it's effectively a constant. The shortest way to create a range-like array of numbers 1-100 is to use a trick based on iterables.

Vue.extend({
  computed: {
    range() {
      return Array.from({ length: 100 }, (_, i) => i + 1);
    },
  },
});

Array.from accepts any iterable as it's first parameter, and then an optional mapping function to transform each item yielded from the iterable. In what feels like a total cheat, we create a 100 item iterable by simply creating an object with a numeric length property: { length: 100 }. Our transform skips the values yielded from our iterable (since they are void) and instead returns the index plus 1. You can imagine the internals of Array.from starting up an old fashioned for loop and calling our transform function on each iteration:

// The default transform just returns whatever is yielded from the iterable.
const identity = x => x;

const Array = {
  from(iterable, transform = identity) {
    let list = [];
    for (let i = 0; i < iterable.length; i++) {
      list.push(transform(iterable[i], i));
    }
    return list;
  },
};

To render the list, we can use a v-for directive. We'll place a data attribute referencing our id so later we can reference the element from the intersection observer's callback. We'll also place a ref here so we can pass these elements to our observer to be observed. Placing a ref on an element with v-for will give us an array of elements at vm.$refs.items.

<template>
  <ul class="list">
    <li ref="items" v-for="i in range" :key="i" class="item" :data-id="i">
      Item Number #{{i}}
    </li>
  </ul>
</template>

Managing State

Now we need to figure out how to store which items are in view. We could fill an array with ids that are in view, but when reacting to changes from the observer, we would have to filter the list on each entry that is not intersecting, and push each entry that is intersecting. That makes additions cheap, but deletions potentially expensive.

To improve the performance implications of the array we could use a set. The Set#has, Set#add and Set#delete methods would make it fast and easy to remove items leaving view and add items entering view. The problem with a set is that Vue 2.x cannot observe its changes. We'll have to wait for Vue 3.x to leverage Set and other newer built-ins.

We can use an object to store the which ids are in view by using the id as the key and a boolean as the value--true indicating it is in view, false or no key present indicating out of view. This makes adding items as simple as adding a new property with a value of true, and removing items can be excluded from the object or simply toggled to false. This has one caveat: Vue cannot observe changes to new or deleted properties. We'll have to be careful to either use Vue.set or replace our object with a new one so Vue will trigger its reactivity system to observe the new object with additional properties.

Vue.extend({
  data() {
    return {
      // Record<string, boolean>
      inViewById: {},
    };
  },
});

In addition to the reactivity caveats, we'll need to take into account the fact that our numeric ids will be cast to strings when used as object keys. This will just be for a ticker display of the items currently in view. We will want to sort entries so we aren't looking at a confusing jumble of item ids.

Vue.extend({
  computed: {
    inView() {
      return Object.entries(this.inViewById)
        .filter(this.isInView)
        .map(this.pluckId)
        .sort(this.sortAtoi);
    },
  },
  methods: {
    // Destructure the Object Entry of key, value (dropping the key)
    isInView([, inView]) {
      return inView;
    },
    pluckId([i]) {
      return i;
    },
    // Sort ascii to int (a to i) is a sort function
    // that properly sorts numbers when passed as strings.
    sortAtoi(a, b) {
      return Number(a) - Number(b);
    },
  },
});

Create The Observer

Finally, we can instantiate an IntersectionObserver. We could do this in our component data, but we don't need it to be reactive, and I'm not even sure how much of the observer's properties are Vue can make reactive. We could use the created lifecycle hook, but our component DOM won't be accessible. We'll use the mounted lifecycle hook so we have everything at our fingertips and also because that hook is not run in SSR contexts.

We'll instantiate the IntersectionObserver, which accepts a callback to handle changes on its observed elements. We'll set that up as a method we'll create next. We could also pass an object of options as the second parameter, but let's just go with the defaults for now.

After creating the observer, we'll iterate through our list of elements using the ref placed on the v-for. We tell our new observer to observe each element, and then we'll save a handle to our observer so we can disconnect it and release it's resources before our component is destroyed.

Vue.extend({
  mounted() {
    let observer = new IntersectionObserver(this.handleIntersection);
    for (let el of this.$refs.items) {
      observer.observe(el);
    }
    this.observer = observer;
  },
  beforeDestroy() {
    this.observer.disconnect();
  },
});

So here's where it gets a little interesting. Our observer callback is invoked with an array of IntersectionObserverEntry objects and a reference to our observer (which we have saved on our component instance). We're going to get one entry for each element we observed--so every element in our list. We can iterate through this list and use the entry's isIntersecting property to determine whether or not it's in view.

The interesting part is managing our state since we have to give Vue fresh objects if we want to add or remove properties from our map of what is in view. Here we've created a method to clone our map, but only adding items to the map if they're in view. We can keep the object smaller this way which benefits our clone process as well as our sorted list of ids in view.

Once we have a fresh map of what is in view, we can iterate the entries and sync up visibility with our state. If an item is intersecting, we set that id to true. If it's not intersecting, we need to check if it's visible in the old map and set it to false. Those will be the items leaving view. By only setting it to false when true, we continue to preserve the smallest size map we can.

The last thing to do is to assign the new map on our component instance. This will trigger Vue to observe the new object, detect changes and re-render.

Vue.extend({
  methods: {
    handleIntersection(entries, observer) {
      let inViewById = this.cloneInViewById();

      for (let entry of entries) {
        let id = entry.target.dataset.id;
        if (entry.isIntersecting) {
          // You could check if this was not already true
          // to determine the item just came into view.
          inViewById[id] = entry.isIntersecting;
        } else if (inViewById[id]) {
          // Leaving view.
          inViewById[id] = false;
        }
      }

      this.inViewById = inViewById;
    },
    cloneInViewById() {
      let inViewById = {};
      for (let [id, inView] of Object.entries(this.inViewById)) {
        if (inView) {
          inViewById[id] = true;
        }
      }
      return inViewById;
    },
  },
});

Quick And Dirty Result

Now to see the code in action! I've built the codesandbox using our snippets. Our component is correctly tracking which items are visible on screen and updating our ticker. This means we set up the observer properly and that we're managing our state in a Vue 2.x friendly way.

Problems

Now that we have a working implementation, what are we missing?

Our example shows a static list of elements, but what happens if we have a
dynamic list? Items may be added or removed by user interaction, but our observer will still be watching the original set of items. What happens if we render an empty list when the component is loaded, then we get supplied a long list from a data fetch? Our observer will sit idle and not observe anything.

What if we want to use an observer passed as a prop from a parent component? We'll need to be reactive to that observer changing. We might also need to be prepared for not being given an observer at first, or the observer disappearing during the component's lifecycle.

Observe Directive

What we need is a way to hook into the lower level Vue mechanics of when elements are added and removed from a component's DOM. Thankfully there's a way to do this, and it's a first-class Vue API: custom directives.

Refactor To Directive

Now we need to see what we should extract from our prototype and into a directive. Our directive won't have any control over the observer except that it will be given as a directive prop. We're going to want to cover use cases for element insertion, update, and directive unbind. Using the directive should be a one-line change to pass our observer to our directive. Here it is in the context of our big list:

<template>
  <ul class="list">
    <li
      v-observe="observer"
      ref="items"
      v-for="i in range"
      :key="i"
      class="item"
      :data-id="i"
    >
      Item Number #{{i}}
    </li>
  </ul>
</template>

Insertion

When an element is inserted, if we are given an observer, register the element with the observer.

Update: Not Observed

If we are given an observer, register the element with observer.

Update: Already Observed

If we are given an observer, check to see if it's the same observer. If it's different, attempt to unregister with the old observer and register with the new observer. It it's the same observer, do nothing.

If we aren't given an observer, attempt to unregister with the old observer.

Directive Unbind

If we are being observed, attempt to unregister with the old observer.

Implementation

As you can see, there are a painful amount of use cases to support for a seamless abstraction. After listing the requirements, I can see that we are going to need to cache two pieces of state: the observer and whether or not we are currently being observed. We can use the observer's existence to derive whether or not we are being observed, but I find adding a data attribute makes it easier to peek in and see if things are working or not.

To track state, we'll cache the observer directly on the element. To ensure we don't conflict with any DOM properties both present and future, we can create a local symbol that will give us exclusive access to our cached observer. We'll make the data attribute appear in the DOM as data-v-observed="yes|no" by using the element's dataset in camelcase: element.dataset.vObserved = "yes|no" (read the pipe character as an "or").

What follows is a full directive implementation that seems too tedious to go through line-by-line. The insert and unbind cases are relatively easy to follow, but update is tricky. I've done my best to reduce the complexity of the many possible cases by leveraging early returns and using names that hopefully make things more readable.

const yes = "yes";
const no = "no";
const kObserver = Symbol("v-observe");

function markObserved(el) {
  el.dataset.vObserved = yes;
}
function markNotObserved(el) {
  el.dataset.vObserved = no;
}
function cacheObserver(el, observer) {
  el[kObserver] = observer;
}
function removeCachedObserver(el) {
  el[kObserver] = undefined;
}

export default {
  inserted(el, { value: observer }) {
    if (observer instanceof IntersectionObserver) {
      observer.observe(el);
      markObserved(el);
      cacheObserver(el, observer);
    } else {
      markNotObserved(el);
      removeCachedObserver(el);
    }
  },

  update(el, { value: observer }) {
    let cached = el[kObserver];
    let sameObserver = observer === cached;
    let observed = el.dataset.vObserved === yes;
    let givenObserver = observer instanceof IntersectionObserver;

    if (!observed) {
      if (givenObserver) {
        observer.observe(el);
        markObserved(el);
        cacheObserver(el, observer);
      }

      return;
    }

    if (!givenObserver) {
      markNotObserved(el);
      if (cached) {
        cached.unobserve(el);
        removeCachedObserver(el);
      }
      return;
    }

    if (sameObserver) {
      return;
    }

    if (cached) {
      cached.unobserve(el);
    }

    observer.observe(el);
    markObserved(el);
    cacheObserver(el, observer);
  },

  unbind(el) {
    let cached = el[kObserver];
    if (cached instanceof IntersectionObserver) {
      cached.unobserve(el);
    }
    markNotObserved(el);
    removeCachedObserver(el);
  },
};

Final Result

And here you have it--our prototype converted to use our custom v-observe directive! She still works as before, but now you should be able to hot swap items in the list as well as change out intersection observers.

Idle Map

Alex Regan — Mon, 03 Jun 2019 15:26:32 +0000

When you have code to run that's async, you have a few options. You can work with a Promise, schedule something to run at a later time with setTimeout, or schedule in coordination with the browser's render cycle via requestAnimationFrame. Each has its own strength, but now there's a new tool in our async toolkit: requestIdleCallback. I want to show off a trick to mix up promise-based tasks against the new requestIdleCallback API (we'll just call it rIC).

If you want a primer on rIC, check out the Google article from Paul Lewis. You can also get the full API rundown on MDN as well as browser support information from caniuse.

The idea is to run a list of items through a processing function--essentially like Array#map--except we want to ensure we intermittently yield control back to the main thread to remain responsive for user events. We can use rIC to schedule each item's processing and check the IdleDeadline to see if there is more time to process another item. If not, we can schedule another idle callback. We'll continue this process until every item in the list has been processed.

function idleMap(iterable, processCallback) {
  return new Promise(resolve => {
    let results = [];
    let iterator = iterable[Symbol.iterator]();

    async function processList(idleDeadline) {
      do {
        let iterResult = iterator.next();
        if (iterResult.done) {
          return resolve(results);
        }

        results.push(await processCallback(iterResult.value));
      } while (!idleDeadline.didTimeout);

      requestIdleCallback(processList);
    }

    requestIdleCallback(processList);
  });
}

This function, idleMap takes your list (iterable) and a callback (processCallback), and it applies the callback to every item in the list just like Array#map. Internally, it uses recursion by defining a closure (processList) that it first schedules with an idle callback. Once that function is invoked by the browser, it uses the iterator to pull out items from the list and applies the processing callback on them. After each item, the do..while control will evaluate whether or not the idle deadline has expired. If it hasn't, the function is free to process another item. If the deadline has expired, the do..while control breaks and schedules another idle callback to continue processing the list. Once the list iterator has been consumed, the promise returned from idleMap resolves with the results of each item's processing.

I find that using the iterator interface works well with the do..while control flow by removing the need to managing array indexes. As a major bonus, it also means we can map anything that satisfies the iterable interface. This could be doubly useful since it would allow the use of generator functions, custom objects, and various other non-array types to supply the items to be processed.

Wrapping Errors

Alex Regan — Thu, 14 Feb 2019 15:55:34 +0000

When performing I/O in Node.js servers, there is a lot of error handling to deal
with. I always look to add as much context to errors as I can because it greatly
reduces the time it takes me to find, understand, and fix bugs.

We won't go into an error propagation strategy here (that will be part of some
of the upcoming material), but I wanted to share a quick idea for how to
decorate errors with context as they propagate through the stack.

Native Error

JavaScript comes with a few built-in error classes. They include:

Error: a base class for exceptions.
EvalError: an error regarding the global eval() function.
InternalError: an error that occurred internally in the JavaScript engine.
RangeError: an error when a value is not in the set or range of allowed values.
ReferenceError: an error when a non-existent variable is referenced.
SyntaxError: an error when trying to interpret syntactically invalid code.
TypeError: an error when a value is not of the expected type.
URIError: an error when a global URI handling function was used in a wrong way.

While we may sometimes find usages for specific built-ins like the RangeError,
most user-defined exceptions make use of the base Error class. Its properties
include a name, message, and stack. In Node.js, error instances
additionally contain a code which identifies various error types including
underlying system errors.

Creating our own error (and throwing it) looks something like this:

function parseIntStrict(numLike) {
  let n = parseInt(numLike, 10);
  if (!Number.isInteger(n)) {
    throw new Error(`unable to parse input as integer: ${numLike}`);
  }
  return n;
}

Here we create and throw an error when parseInt returns NaN values. The
message in the error is about as specific as we can make it without more
context. This function might be called to convert user input for updating a
product quantity in a shopping cart, parsing a field from a csv file, etc.--we
can't know how it will be used.

In Context

Let's say we are writing an api that takes a csv file and parses inventory
quantities from its row fields. We're going to use our parseIntStrict function
when we parse a product's inventory count in the file. We might think of our api
call stack like this:

[4] Parse quantity field
[3] Parse csv row
[2] Read file by lines
[1] Map request to csv file on disk
[0] Receive network request

There are a number of steps here before we use the parseIntStrict function.
Ideally, if a call to our function fails, we would like to know our request id,
the name of the csv file on disk, the row index, and the field that caused the
failure. If we have all that information, we can go straight to solving any
broken functionality instead of exhausting valuable time diagnosing the source
of the problem.

Wrapping Errors

In order to achieve our goal of adding context to an error, we need a way to
decorate errors and then bubble them back up the stack. One way we could do this
is by adding a message representing the current context. We don't want our
message to corrupt the original message in any way. This discourages us from
attempting to manipulate the original error's message, but since we aren't
always guaranteed error producers use the Error class to generate exceptions,
this isn't an option in the first place.

Let's extend the Error class so we can add a reference to the untouched,
original error value. This will let us add our contextual message and keep a
reference to the original error value regardless of it being an Error instance
or not.

class WrappedError extends Error {
  constructor(message /* context */, previous /* original error value */) {
    // First we have to call the Error constructor with its expected arguments.
    super(message);
    // We update the error's name to distinguish it from the base Error.
    this.name = this.constructor.name;
    // We add our reference to the original error value (if provided).
    this.previous = previous;
  }
}

We aren't changing much from the base Error class. We'll get the default
Error behaviors for free since we inherit (generating stack traces,
stringification, etc.), but now our error type can reference a previous error.
If we use a WrappedError to generate our first exception, the previous error
will be undefined. If we create an instance passing in an Error or a literal
value, previous will maintain a reference to it. Most interestingly, if we
create an instance passing in another WrappedError instance, we connect a
chain of errors together.

When we start using our WrappedError throughout our application code, we
essentially transform our error values to linked lists. The list head would be
our current error's position in the stack, or its context. We could traverse
the list by checking for the existence of a previous error, and if it exists,
checking to see if it's an instance of WrappedError, which guarantees us a
previous field we can inspect to continue the traversal.

Let's look at how we might perform a traversal to get at the root error
value--be it a WrappedError, Error, or otherwise. We'll use a computed
property--an
object getter method--to
allow us to compute and access the root value like a property.

class WrappedError extends Error {
  // ...

  get root() {
    // Base case, no child === this instance is root
    if (this.previous == null) {
      return this;
    }
    // When the child is another node, compute recursively
    if (this.previous instanceof WrappedError) {
      return this.previous.root;
    }
    // This instance wraps the original error
    return this.previous;
  }
}

let error1 = new Error("the first error");
let error2 = new WrappedError("the second error wraps #1", error1);
let error3 = new WrappedError("the third error wraps #2", error2);

console.assert(
  error2.root === error1,
  "the root of error2 should be strictly equal to error1"
);
console.assert(
  error3.root === error1,
  "the root of error3 should be strictly equal to error1"
);
// Passes if no error appears in the console

You can test this example in
this repl here, but suffice
it to say that the strict equality checks are all true. There's a lot we can do
here, but simply logging with console.error produces this output in Node.js
(from the same repl):

{ WrappedError: the third error wraps #2
    at evalmachine.<anonymous>:27:14
    at Script.runInContext (vm.js:74:29)
    at Object.runInContext (vm.js:182:6)
    at evaluate (/run_dir/repl.js:133:14)
    at ReadStream.<anonymous> (/run_dir/repl.js:116:5)
    at ReadStream.emit (events.js:180:13)
    at addChunk (_stream_readable.js:274:12)
    at readableAddChunk (_stream_readable.js:261:11)
    at ReadStream.Readable.push (_stream_readable.js:218:10)
    at fs.read (fs.js:2124:12)
  name: 'WrappedError',
  previous:
   { WrappedError: the second error wraps #1
    at evalmachine.<anonymous>:26:14
    at Script.runInContext (vm.js:74:29)
    at Object.runInContext (vm.js:182:6)
    at evaluate (/run_dir/repl.js:133:14)
    at ReadStream.<anonymous> (/run_dir/repl.js:116:5)
    at ReadStream.emit (events.js:180:13)
    at addChunk (_stream_readable.js:274:12)
    at readableAddChunk (_stream_readable.js:261:11)
    at ReadStream.Readable.push (_stream_readable.js:218:10)
    at fs.read (fs.js:2124:12)
     name: 'WrappedError',
     previous: Error: the first error
    at evalmachine.<anonymous>:25:14
    at Script.runInContext (vm.js:74:29)
    at Object.runInContext (vm.js:182:6)
    at evaluate (/run_dir/repl.js:133:14)
    at ReadStream.<anonymous> (/run_dir/repl.js:116:5)
    at ReadStream.emit (events.js:180:13)
    at addChunk (_stream_readable.js:274:12)
    at readableAddChunk (_stream_readable.js:261:11)
    at ReadStream.Readable.push (_stream_readable.js:218:10)
    at fs.read (fs.js:2124:12) } }

Not bad, right?

Open For Extension

The contextual references we're able to create with this provide a lot of
opportunities for extension. Depending on the needs of your application, you
might consider:

Add a spans getter to compute an array of all the stringified errors
Memoize the getters by overwriting them after first access using Object.defineProperty
Make the list iterable by implementing WrappedError.prototype[@@iterator]()
Make iterator methods like forEach or map that implement pattern matching for your custom data types (like WrappedError, Error, and any)

I've implemented the spans property in the
repl link if you're
curious. If you think of new applications or features for this idea, you can
find me on Twitter at @alexsasharegan.

Pattern Matching Custom Data Types in Typescript

Alex Regan — Sat, 02 Feb 2019 19:20:00 +0000

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.

Blog Launch

Alex Regan — Sat, 29 Dec 2018 21:33:03 +0000

Welcome to the blog!

I've been eager to start sharing tips, tricks, and the occasional tutorial for
all things software. My business partner, Joel Cunningham, may wish contribute
posts as well in his own field of expertise.

In the spirit of talking shop, this blog has been launched on
Netlify's amazing and free hosting services via our
Github repository. We host most of our work on
DigitalOcean, but I wanted to take advantage of
the continuous deployment perks that Netlify offers for
Hugo static sites. We simply push to the master branch, and
Netlify builds and deploys our site immediately! 🎉🎉🎉

Thanks for stopping by! I'll have more to come soon. I've started what will
probably be a multi-part series of posts about writing more robust JavaScript by
using type systems to employ patterns I've learned from the
Rust programming language.

– Cheers 👋