Kyle Shevlin's Blog RSS Feed

`AsyncData`

Sun, 11 Jan 2026 18:14:40 GMT

Over the years, I've had an interest in modeling state problems as accurately as possible. I submit posts like Enumerate, Don't Booleanate and my many posts on state machines as evidence. I can't stand allowing impossible states or leaking implementation details when there's a better way.

I thought I had reached the zenith of my state representation journey, but I was wrong.

I recently decided to revisit functional programming and really dove into understanding monads, functors, etc. even more than I have in the past. I've been learning Gleam for fun, and writing my own little beginner's functional programming library to help ingrain the concepts. <Marker content="I haven't published it yet. It's not even at version 0.1.0." /> As part of my research, I've been closely studying the Boxed library and the data types it implements. That's how I came across the AsyncData data type.

There is some context that I think would be very helpful for you to understand why I find AsyncData so interesting, but including it here would take a lot of words. Instead, I'm going to list the concepts here for you to look up: <Marker content="Hopefully, I get around to writing my own posts about them some day." />

Discriminated unions, check out here and here
Functors, check out here

Representing async data, imperatively

I'm going to assume that most of you reading this have used the fetch method to get some data from an API.

function getData() {
  return fetch('/some/url').then(res => res.json())
}

const result = await getData()

When we fetch data, we generally need to manage some state about that data fetch so that we can respond to the various states it's in. I'm going to keep using plain JavaScript for my example, but you can imagine what it might look like for your framework of choice.

let loading = false
let error = null
let data = null

async function getData() {
  // reset state from previous fetch
  error = null

  // start managing this loading state
  loading = true

  fetch('/some/url')
    .then(res => res.json())
    .then(d => {
      data = d
    })
    .catch(err => {
      error = err
    })
    .finally(() => {
      loading = false
    })
}

This works, but it's a lot of manual setup (often repeated many times in a codebase) and it allows for possible impossible states if written poorly. The fact that there are three variables to manage the state means that somewhere in our code we might check for loading, data, or error in some incorrect way that leads to us showing an error when we should be loading or already have some data. <Marker content="Notice I didn't reset the data. Maybe you do or don't want to do that." /> It's prone to human error and can be avoided.

We can make this better by enumerating the states. I won't go so far as using a state machine, though I could. Instead, I'll use a discriminated union to represent the possible states instead.

type State<Data> =
  | { status: 'not-asked' }
  | { status: 'loading' }
  | { status: 'failure'; message: string }
  | { status: 'success'; data: Data }

let state: State = { status: 'not-asked' }

async function getData<Data>() {
  state = { status: 'loading' }

  fetch('/some/url')
    .then(res => res.json())
    .then(d => {
      state = { status: 'success', data: d as Data }
    })
    .catch(err => {
      state = { status: 'failure', message: err.message }
    })
}

This is way better than before. We only have one variable that manages all our state. We never have to reset state before fetching, and we can't possibly have an impossible state downstream. The use of the discriminated union also means TypeScript will narrow our types for us based on status, too.

if (state.status === 'success') {
  // TypeScript knows state.data is the type Data here
}

If you stopped at this point, that would be great. Your codebase would improve just from this step. But there's a subtle way that this is inaccurate that I hadn't noticed.

But this is where AsyncData and its friend, Result, come in.

`AsyncData` and `Result`

What if instead of a type, we used a functor to represent our discriminated union? And what if we separated the concerns of the async process from the concerns of which "data" we received at the same time? That could be pretty cool.

Let's start by implementing AsyncData. It's a Sum type made up of three sub-types: NotAsked, Loading and Done. We can setup some classes <Marker content="Ironic. I know." /> to make this work:

type Tag = 'NotAsked' | 'Loading' | 'Done'

class AsyncData<T> {
  #tag: Tag
  #value: T

  constructor(tag: Tag, value: T) {
    this.#tag = tag
    this.#value = value
  }

  static NotAsked() {
    return new NotAsked()
  }

  static Loading() {
    return new Loading()
  }

  static Done<U>(value: U) {
    return new Done(value)
  }
}

class NotAsked extends AsyncData<never> {
  constructor() {
    super('NotAsked', undefined as never)
  }
}

class Loading extends AsyncData<never> {
  constructor() {
    super('Loading', undefined as never)
  }
}

class Done<T> extends AsyncData<T> {
  constructor(value: T) {
    super('Done', value)
  }
}

That's not our full implementation, but let's see how we'd use this instead in our fetch example:

let state = AsyncData.NotAsked()

function getData() {
  state = AsyncData.Loading()

  fetch('/some/url')
    .then(res => res.json())
    .then(data => {
      state = AsyncData.Done(data)
    })
    .catch(error => {
      state = AsyncData.Done(error)
    })
}

Now, if you're paying attention, you might think, "Kyle, that's objectively worse. You're passing data and error to the Done state and we can't discriminate between the two." You'd be right, but stay with me. We're going to make two more changes that will set your mind at ease.

Now, I called AsyncData a functor because it is. We could implement map and map would only interact with the value when it's Done, otherwise it's a noop. But more interesting to our purposes is pattern matching. We're going to implement a match method.

class AsyncData<T> {
  // same as before... new stuff below
  isNotAsked(): this is NotAsked {
    this.#tag === 'NotAsked'
  }

  isLoading(): this is Loading {
    this.#tag === 'Loading'
  }

  isDone(): this is Done<T> {
    this.#tag === 'Done'
  }

  // Here's the good stuff
  match<A, B, C>({
    NotAsked,
    Loading,
    Done,
  }: {
    NotAsked: () => A
    Loading: () => B
    Done: (value: T) => C
  }): A | B | C {
    if (this.isNotAsked()) NotAsked()
    if (this.isLoading()) Loading()
    if (this.isDone()) Done(this.#value)
  }
}

Our match method takes an object with three keys that match our possible sub-types, whose value is the function to call if the data happens to be in that particular state. Now we have a rock-solid way of responding to AsyncData as it changes, such as:

type State = AsyncData<Result<Data, Error>>

function MyDataDisplay() {
  const [state, setState] = React.useState<State>(AsyncData.NotAsked())

  React.useEffect(() => {
    function getData() {
      setState(AsyncData.Loading())

      fetch('/some/url')
        .then(res => res.json())
        .then(data => {
          setState(AsyncData.Done(Result.Ok(data)))
        })
        .catch(error => {
          setState(AsyncData.Done(Result.Error(error)))
        })
    }

    getData()
  }, [])

  return state.match({
    NotAsked: () => null,
    Loading: () => <div>Loading...</div>,
    Done: result =>
      result.match({
        Ok: data => <DataViz data={data} />,
        Error: error => (
          <div>Whoops! Something went wrong: {error.message}</div>
        ),
      }),
  })
}

See what I did there?! Sure, I threw a curveball at you with the Result data type, but I bet you can figure it out. We've now completely separated the async process from that state of the data or error that was returned. That's a wholly separate concern, nicely managed with the Result type. And the pattern matching is just so clean (not to mention type-safe).

Now we have a singular, reusable data type that we can use whenever we have an async process. No more imperative variables or states to setup, and no discriminated TypeScript unions to write either. Just our one, singular AsyncData state. I think that's really cool.

Do I expect to ever use this?

In one of my projects? Sure. But in my day-to-day work, no.

What I find cool and interesting doesn't often make it into the product I'm working on. I find it pretty difficult to convince people to try something like this, so I wouldn't stress about it if you like the pattern and can't use it either. Take satisfaction in knowing an even better way to represent some of the state in your app.

If you do want to try using this, I recommend checking out Boxed. It has the AsyncData and Result types you need as well as some examples. Check it out.

If I ever finish that library I'm writing, I'll let you know.

Nothing is Something

Sat, 20 Dec 2025 00:14:23 GMT

I really need more people to watch "Nothing is Something" by Sandi Metz so I don't get weird looks when I apply its lessons to my code.

I was dealing with a problem like the following today. Imagine you got an object of key/value pairs, where the key is a bit of state and the value transforms that state somehow.

// Just some arbitrary state for our example
type State = {
  count: number
  createdAt: Date
  isActive: boolean
  name: string
}

type Transform = <T>(x: T) => T

const STATE_TRANSFORMS: Partial<Record<keyof State, Transform>> = {
  count: x => x * 2,
  name: x => x.toUpperCase(),
}

The transforms themselves aren't terribly important, but notice that I don't have a transformation for every key in the State type.

Now, if you were to make a function to run those transforms, you might be tempted to do:

function transformStates(state: State) {
  const nextState: State = {}

  for (const key of state) {
    const transform = STATE_TRANSFORMS[key]

    // This handles the condition at the last possible moment
    // and it results in two separate ways of managing the state
    if (transform) {
      nextState[key] = transform(state[key])
    } else {
      nextState[key] = state[key]
    }
  }

  return nextState
}

But I prefer to do this instead:

const identity = x => x

function transformStates(state) {
  const nextState = {}

  for (const key of state) {
    // Condition is handled a step earlier and we've narrowed
    // the type of `transform` from `Transform | undefined`
    // to just `Transform`, simplifying the next step
    const transform = STATE_TRANSFORMS[key] ?? identity

    nextState[key] = transform(state[key])
  }

  return nextState
}

Because, as the title of the talk suggests, doing nothing is doing something.

You might argue that I'm making unnecessary function calls here, but I think it's a worthwhile trade-off for simpler code.

We can use this pattern of identifying the "nothing", aka the default behavior, and providing the functionality for it as a way to simplify our code, primarily by reducing excessive conditionals which tends to be the source of complexity.

Please watch the talk. You'll be a better programmer for it.

`data` Attributes for Testing

Fri, 21 Nov 2025 18:37:54 GMT

I don't know if this is the world's best idea, but given the situation I'm faced with, it's the best one I've got.

At my place of work, we have a design system partially built with custom web components. Given how web components are implemented, occasionally there's an attribute or piece of data we would like to test for that is in the shadow DOM. This poses a small problem for testing.

I want to keep my tests as declarative as possible, but to get that information I have to imperatively reach into the shadow DOM. I don't like this. Especially if there's any chance we might change the implementation of the component. I want the tests to keep passing, so long as we haven't changed the public interface.

As it stands, we sometimes have to search through the shadow DOM to find the right shadow part of an element we want to test. This requires making a special selector for those parts, and means our tests can be break if we make a change to the implementation.

For example, we have a button component that can be passed an href or to prop and it will render as an a tag in the shadow DOM. If I want to look at the resulting href, I have to use our custom shadowPart selector to get that element. I'd rather not have to do that.

The way I've gotten around this is by lifting important attributes that otherwise would be buried in the shadow DOM as data-* attributes on the root element. In the case of that href, I lift it to a data-href attribute.

The dev uses the component like so:

<OurButton href="/some/url">Click me</OurButton>

And the DOM looks something like this:

<our-button data-href="/some/url">
  <!-- in the shadow DOM -->
  <a href="/some/url" part="base">Click me</a>
</our-button>

The tests go from looking like this:

expect(wrapper.getByTestId('our-button').shadowPart('base')).toHaveAttribute(
  'href',
  '/some/url',
)

To something like this:

expect(wrapper.getByTestId('our-button')).toHaveAttribute(
  'data-href',
  '/some/url',
)

Notice I don't need the shadowPart selector anymore. If, like we're considering, we drop the custom web component and revert to regular DOM elements, the test will still pass.

You can do this on a number of components for any number of attributes or props. For example, our button has the following data-* attributes:

data-loading
data-href
data-variant
data-size

And there are more, but that's enough for you to see how the pattern can be implemented.

These data attributes remain stable while other implementation details change. I'll give you another example that might apply to you.

Before I added the data-variant and data-size attributes, our tests would look for specific classnames on the button to ensure that a prop was applied properly. The problem with this was if we migrate our system to use something like Tailwind, then all of these tests would break, even if the public interface hadn't changed.

By verifying that the data attribute is correct (and assuming all functionality remains the same), we can keep our tests passing even if we make changes under the hood.

So give it a try. If you're in a situation where you have some challenging components to test, you might find the data-* attributes pattern to be helpful.

Prefer Gaps To Margins

Mon, 23 Jun 2025 15:20:35 GMT

Preferring gaps to margins is so obvious to me that it's honestly challenging to write about it. What is there to argue? It just makes sense.

Yet experience has taught me that it doesn't "just make sense" to many others, so I'm going to try and make my case.

Margins and gaps are two different ways to space apart adjacent elements, however there are some key differences to note.

Margins are applied to an element, either thru CSS or composition, and create a boundary around it such that the element itself can get no closer to any other element than the boundary. We can think of this relationship as child-to-sibling or child-to-outside-world layout strategy.

Gaps, on the other hand, are a way for a Flex or Grid container to space out the children it contains. Each gap is applied between adjacent sibling elements. We can think of this as a parent-to-children layout strategy.

Both can be used to space out elements, but whether we choose one or the other really depends on how you answer the following question: whose responsibility is it for spacing, the parent or the child?

I'll make no qualms, I fall entirely in the "parents should control the layout of children" camp. I make heavy use of composition in my apps for this very purpose, and I'm perfectly comfortable doing this either with layout components or with utility classes.

Why I dislike margins

There are a few reasons I think margins are a poor choice for laying out sibling components. Let's set aside the fact that any layout achieved with margins can be achieved with Flex + gaps instead and let's focus on issues with margins themselves.

First, margins require us to wrap each child individually, and often with excessive care. Let's say I have three items I want to have in vertical column:

<div>
  <Item1 class="mb-4" />
  <Item2 class="mb-4" />
  <Item3 />
</div>

It may not seem like a lot of code, but we've had to manually add classes and we have to remember not to add it to the final element.

The issue arises should we ever need to add, remove, or move elements in this list. We now have to manually move classes.

But let's say we get wise and instead of hand-writing these components, we choose to derive them from data instead. We'll programmatically render the list, but we'll still have to make a caveat for not adding the final margin:

<div>
  {items.map((item, idx) => (
    <Item
      key={item.id}
      class={idx !== items.length - 1 ? "mb-4" : ""}
      item={item}
    />
  )}
</div>

What a completely unnecessary bit of code to write when we can use gaps instead?

<div class="flex flex-col gap-4">
  {items.map(item => (
    <Item key={item.id} item={item} />
  ))}
</div>

Better still, let's say that list of items should be in a row at a different breakpoint. What's easier? Manually removing and replacing all the margin classes, or simply changing the direction of the parent container?

What code would you prefer, this?

<div>
  {items.map((item, idx) => (
    <Item
      key={item.id}
      // At the medium break point, items should have a right
      // margin now. Ignoring the fact that we'd have to change
      // them to be inline-block or the parent div to a flex
      // row to get them to layout side by side
      class={idx !== items.length - 1 ? "mb-4 md:mb-0 md:mr-4" : ""}
      item={item}
    />
  )}
</div>

Or this?

<div class="flex flex-col gap-4 md:flex-row">
  {items.map(item => (
    <Item key={item.id} item={item} />
  ))}
</div>

The answer should be glaringly obvious.

Let's add one more wrinkle to margins: "vertical margin collapse". I'm not going to spend a lot of time explaining what it is, Josh W. Comeau wrote a fantastic article about it you can read, but I'm not a big fan of relying upon it in component systems.

It's true, you can build systems that use margin collapse as a way to "create sane default spacing", but I'd argue you spend more time making compensatory classes or CSS to undo the margins than having the defaults are worth. If you find yourself writing CSS classes setting margins to 0 or writing a bunch of my-0 classes in your code, you probably have a component system that's really difficult to compose.

Why I love gaps

I don't even think this sections needs a lot of exposition, so I'll give you the bullet points.

Gaps are automatic. No matter how many items you add, they just keep getting added in the right spot. Even if your list is of length 1, you never have to worry about an incorrect gap getting applied.
Gaps are literally less code to write, added once on a parent, no need for children to share classes to share a margin top or bottom, no need for nth-selectors, etc.
Gaps work for both vertical and horizontal spacing. If your items wrap, there's no need to add additional margin classes to make sure they align on rows correctly. And you never need outer negative margins to ensure inner spacing works!

Final thoughts

Gaps are superior to margins in pretty much every way. I'd rather an app be full of tiny stacks and rows with gaps than deal with margins any day of the week. Combine this concept with my No Outer Margin post to make your component system more robust.

“Refactor” is Not a Scary Word

Thu, 27 Feb 2025 16:45:58 GMT

One thing I've struggled with throughout my life is using a word with a specific definition that gets interpreted differently. It causes me a great deal of frustration. <Marker content={In my childhood, I read the book "The Giver" by Lois Lowry. At one point, the main character makes an exaggerated statement, to which the parents admonish him with, "Precision of language!" I felt understood when I read that.} /> It might be unreasonable to expect people to walk around with a Merriam-Webster's dictionary in their pocket, <Marker content="Actually, I can. 📱" /> so mistakes are bound to happen.

I recently lost a potential client and I'm convinced the reason why is because we had different definitions for a single word: “refactor”.

“I'll need to refactor some of these components to support your new use cases.” This was a benign, workaday statement using common jargon for software engineers, yet I could tell it struck fear in this client. I never had a chance after that.

I don't know when it happened, but “refactor” became a scary word, and we need to get it back.

Why is it a scary word?

I have no research to back up what I'm about to claim, but my suspicion is that people recoil at the word “refactor” because it's caused them trauma, primarily in the way of costs.

I think somehow it has become an ambiguous term in the industry roughly meaning "large, time-consuming, and potentially dangerous changes to code." I find this deeply upsetting as it's essentially the opposite of what the word means, which I will discuss shortly.

Without adherence to a strict definition, I imagine there have been many instances where an engineer mentioned "we need to refactor this" to a manager, and next thing you know, the roadmap ends up derailed, or the project is a failure, or even worse, the company goes out of business.

These outcomes shouldn't be the result of refactoring, and we should really get on the same page about the word to avoid this from happening.

What does the word actually mean?

When I use the word “refactor” or "refactoring", I mean these two specific definitions that come from the book "Refactoring" by Martin Fowler:

Refactoring (noun): a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior.
Refactoring (verb): to restructure software by applying a series of refactorings without changing its observable behavior.

The key part of the definition here is “without changing observable behavior”.

If you are refactoring, it does not mean rewriting the code from scratch. It does not mean making some changes while adding new features. It doesn't even mean changing the structure and hoping it's the same. It means changing the structure of the code knowing it's the same.

There should be no equivocation about this.

Implications of the proper definition

The only way to make changes while knowing the observable behavior hasn't changed is to have a testing suite that can confirm or deny this. Honestly, if you've avoided writing tests in your career, you're doing yourself a disservice. Coding is one of the few industries where we can cheaply and easily verify our work is correct. All it takes is writing a few lines of code. Imagine doing something similar in the physical world, where testing might cost just as much as the actual implementation.

Extrapolating from this, if we must keep the tests green as we make our changes, I think it suggests two things:

The changes we make should be small, incremental steps to our goal

We should be able to make each change to our code in an understandable fashion. The way we accomplish big changes is through the composition of many small ones. With each small change, we should keep the tests green.

These small changes reveal algorithmic patterns, aka refactorings, that are repeatable

We can define what are essentially "recipes" for restructuring code, and for those keen on reading the book, they provide over 60 of them to get started. There are more that can be defined as well.

This means that when we're doing a refactoring properly, we should be doing the following:

Tests related to the code we are changing should be running in a watch mode
We should be able to make an atomic commit with each step <Marker content="Some changes, such as <em>Rename Variable</em> are so small it might not warrant a commit, but it's hopefully obvious how one could do so." />

An example

I'm going to make a rudimentary example to demonstrate how we might refactor a function, without changing it's behavior, that will make it much easier to enhance in the future.

Here we have a getTicketPrice function. It receives a Show as an argument. Members get a 15% discount on ticket prices, while non-members pay the full price. Our function looks like this:

type Show = {
  name: string
  /**
   * The price in cents. Typically it's better to store money as an object, but
   * here we'll make the assumption we're working with US currency.
   */
  price: number
}

function getTicketPrice(show: Show, isMember: boolean) {
  return isMember ? show.price * 0.85 : show.price
}

The tests for a function like this are fairly straightforward. I'll write them in a style that's compatible with Vitest or Jest:

describe('getTicketPrice', () => {
  const show: Show = {
    name: 'Test show',
    price: 1000,
  }

  it('should give members a 15% discount', () => {
    expect(getTicketPrice(show, true)).toEqual(850)
  })

  it('should give non-members the full price', () => {
    expect(getTicketPrice(show, false)).toEqual(1000)
  })
})

Running our tests shows that they're working.

Let's say we learn that we now offer different levels of memberships. A member might be a basic member or a premium one. Members of premium status will get an even greater discount of 25%. What does this mean for our function?

The first obvious thing we'll need to refactor is the isMember boolean. Simply put, we won't be able to represent three possible membership levels with a boolean. I haven't come across a name for the refactoring we'll do, but I think Boolean to Variant might be a good one. As we make this change, remember we're trying to keep the same observable behavior.

type Show = {
  name: string
  price: number
}

// We'll add a membership type and represent our two current states
type Membership = 'member' | 'non-member'

// We'll use that type instead of the boolean
function getTicketPrice(show: Show, membership: Membership) {
  // We'll update our implementation to use our membership instead
  switch (membership) {
    case 'member':
      return show.price * 0.85
    case 'non-member':
      return show.price
  }
}

We'll need to make a small change to our tests, but we'll see that they continue to pass. An added benefit is we removed a flag argument in the process:

describe('getTicketPrice', () => {
  const show: Show = {
    name: 'Test show',
    price: 1000,
  }

  it('should give members a 15% discount', () => {
    expect(getTicketPrice(show, 'member')).toEqual(850)
  })

  it('should give non-members the full price', () => {
    expect(getTicketPrice(show, 'non-member')).toEqual(1000)
  })
})

Our tests are still green with that change. I won't share a picture, it's exactly the same as before.

That said, I think we're at a place we can add our new feature. Given the nature of this function, we can write the additional test first, then get it passing:

it('should give premium members a 25% discount', () => {
  expect(getTicketPrice(show, 'premium')).toEqual(750)
})

Our test fails, so let's get it passing. To do so, we'll add a premium variant to Membership and account for it in our function:

type Show = {
  name: string
  price: number
}

type Membership = 'member' | 'non-member' | 'premium'

function getTicketPrice(show: Show, membership: Membership) {
  switch (membership) {
    case 'premium':
      return show.price * 0.75
    case 'member':
      return show.price * 0.85
    case 'non-member':
      return show.price
  }
}

And our tests are passing again.

There might be more that we can do to this function. We could even argue a bit about the best way to do its implementation, but hopefully it gave you some insight into the process of changing code with safe refactorings.

Final thoughts

We need to reclaim “refactor” because this process of restructure, verify, add feature, verify is simply just doing the job. I don't want to have to use euphimisms to describe my work just so managers don't freak out when changes are necessary. I think if refactors remain scary, then we actually make our work more dangerous for ourselves. Avoiding making changes only makes the code more complex and likely more error prone as well.

If we can embrace refactoring as a safe, atomic way to change code and recognize that it's just a part of the day to day work, I think we can drop the stigma and start improving the codebases we work in.

Fun Coding Exercise: Pyramid Slide Down

Mon, 27 Jan 2025 17:15:10 GMT

I was doing some more interview prep this past week, this time using an app called Codewars, when I came across a "kata" <Marker content="That's what they call the exercises." /> that stood out to me.

The reason it caught my eye is not only that the solution is far simpler than I originally thought, but it also involves a little "divergent thinking" (not to be confused with "neurodivergent thinking"). Let's look at the problem. Then I'll give you my original thoughts on the problem, followed by the solution.

The problem

If you want to try out the problem before reading this article, you can find it at: https://www.codewars.com/kata/551f23362ff852e2ab000037/train/javascript

You are given a pyramid. That is a two-dimensional array of length n, where the length of each row is 1 more than the previous row. An example would look like this:

const pyramid = [[3], [7, 4], [2, 4, 6], [8, 5, 9, 3]]

If we "center" those, we can see the pyramid a bit better

Our goal is to calculate the greatest sum of numbers from "sliding" down the pyramid. The slide can only reach adjacent numbers and must always go down one row at a time. In our example here, the best path is 3, 7, 4, 9, like so:

  /3/
  \7\ 4
 2 \4\ 6
8 5 \9\ 3

How do we solve this?

My initial thoughts

When I first saw the problem, because the structure of the values resembled a graph or a tree, I thought perhaps the answer was to use Djikstra's algorithm on a graph of the numbers. We could use sums as the weights on the node's edges. Seems clever enough.

While this approach would eventually work, there are a couple problems with it. First, we'd have to run the algorithm from the top node to every bottom node. Taking up at least n, where n is the length of the last array, time.

It's also likely that we would be recalculating many of the same routes over and over, so we'd need to take extra steps with caching to ensure we had an optimal solution.

But it turns out the solution is much simpler than all of that.

The solution

There's a common strategy in these types of problems called "dynamic programming". It's an intimidating name, but it really means breaking the problem down into much smaller sub-problems, solving them, and then using those solutions to arrive at the solution for our big problem.

In regards to pyramid, what's the smaller problem we need to solve? Hint: this is where "divergent thinking" comes into play.

I'll give you a moment...

The key insight is to realize we don't have to slide down the pyramid like the problem title suggests. We're not actually skiing it. Instead, we can think divergently, coming up with multiple ways to examine and think about the same problem, and realize something can come up the pyramid instead.

Rather than start at the top, what if we break the problem down into solving the greatest sums up the mountain at each level. So our sub problem becomes, "What are the greatest sums we can achieve between the last two rows?"

Let's write this out:

function greatestSlide(pyramid) {
  // We're going to start at the second to last row,
  // By decrementing, we'll work our way _up_ the pyramid rows
  for (let row = pyramid.length - 2; row >= 0; row--) {}
}

Then with each row, we're going to replace the current value with the greatest sum achieved by adding the two possible values from the row below. That looks like this:

function greatestSlide(pyramid) {
  for (let row = pyramid.length - 2; row >= 0; row--) {
    // Iterate over each item in the row
    for (let col = 0; col < pyramid[row].length; col++) {
      // Replace the value with the greatest sum possible
      pyramid[row][col] += Math.max(
        // This is the item down to the left (has the same column index)
        pyramid[row + 1][col],
        // This is the item down to the right
        pyramid[row + 1][col + 1],
      )
    }
  }

  // By the time we've done this for the entire pyramid, the very top
  // is now the value of the greatest sum possible
  return pyramid[0][0]
}

And that's our solution. By finding the greatest sums possible going up the pyramid, by the time we hit the peak, we're guaranteed the answer.

I just love that the solution was simple and literally required flipping the problem on its head.

Sometimes the hardest step in solving a problem is just figuring out how to think about it correctly, and this problem is a good reminder to look at it from all angles.

Optional steps

One of the first things I don't like about this solution is that we modify the pyramid passed in. Assuming your program allowed for it, I would copy the pyramid before doing the work:

function greatestSlide(pyramid) {
  const copy = pyramid.map(row => row.slice())
  // ...
}

Another thing that could be fun if you were building a visualization, or simply trying to debug it would be to turn greatestSlide into a generator function.

By turning it into a generator function, we're able to yield out our pyramid and different stages and see the transformation. Like so:

function* greatestSlide(pyramid) {
  const copy = pyramid.map(row => row.slice())
  yield copy

  for (let row = copy.length - 2; row >= 0; row--) {
    for (let col = 0; col < copy[row].length; col++) {
      copy[row][col] += Math.max(copy[row + 1][col], copy[row + 1][col + 1])
    }

    // This will just show us the modified portion of the pyramid,
    // making it easy to see the sums work their way up from the bottom
    yield copy.slice(0, row + 1)
  }

  return copy[0][0]
}

const generator = greatestSlide([[3], [7, 4], [2, 4, 6], [8, 5, 9, 3]])

for (const state of generator) {
  console.log(state)
}

// [[3], [7, 4], [2, 4, 6], [8, 5, 9, 3]]
// [[3], [7, 4], [10, 13, 15]]
// [[3], [20, 19]]
// [[23]]

Hopefully you can see how the values sum their way up the pyramid.

Conclusion

I recognize that perhaps you might not find that as interesting as I did, but hopefully I didn't bore you either. We don't often face problems quite like this in web development, so I find it a good exercise to stretch the brain from time to time. You never know what you might learn.

Algorithm: Sliding Window

Thu, 16 Jan 2025 18:32:25 GMT

import { SlidingWindowVisual } from './_components'

I've decided to go back on the job hunt and this has me getting prepared for technical interviews. To do this, I've been practicing Leetcode problems. Yes, I'm not a big fan of this style of interviewing either, but you have to be prepared for whatever might come.

I recently ran into a problem that used a technique I've never used before, a "sliding window", and I wanted to write a quick post about it, both to solidify it in my memory and hopefully teach you something new.

The Problem

I'm going to borrow this straight from their site: Given a string s, find the length of the longest substring without repeating characters. Here's an example:

Input: s = "abcabcbb"
Output: 3
Explanation: The answer is "abc", once we get to "a" at index 3, we have a repeating character, and no other substring is longer

Hopefully that makes sense. They have other examples at the link above. Don't scroll down if you want to go and try it for yourself first.

The Solution

We're going to implement a "sliding window". That is, we're going to look at a slice of our string, tracking the left and right sides of our "window" as we go through it. We move the left and right edges of our window to adjust how much of the string we can "view". You can also do this trick with items in an array.

The key is to manage two pointers, a start index and an end index. We're going to loop over the end with a for loop, and then check if we need to advance our start within that loop. This way, the right side of our window keeps expanding, and when necessary, we shrink the left side, too.

Let's write our function:

function lengthOfLongestSubstring(str) {
  // We'll make a map of character and track the index we last saw them
  const lastSeen = new Map()

  // We need to track the longest substring we've found so far that meets our conditions
  let maxLength = 0

  // initialize our start index
  let start = 0

  // Our loop will advance the right side of our window
  for (let end = 0; end < str.length; end++) {
    // get the character at the rightmost side of our window
    // we've already looked at anything left of it
    const char = str[end]

    // We're going to check our Map and see if we have that character
    // And if the index we found it at is inside the left side of our window
    if (lastSeen.has(char) && lastSeen.get(char) >= start) {
      // If we found that character in our window, that's a repeat
      // Because it's a repeat, we can shrink the left side of our window to the
      // index just past that character
      start = lastSeen.get(char) + 1
    }

    // We need to track our current character now
    lastSeen.set(char, end)

    // And we can update our maxLength, keep it if our current length is less
    maxLength = Math.max(maxLength, end - start + 1)
  }

  return maxLength
}

Why is this the best way to handle this solution?

A naive approach might be something like:

Start at the first letter
Expand until we hit a duplicate
Track the maxLength

Something like:

function lengthOfLongestSubstring(str) {
  let maxLength = 0

  for (let i = 0; i < str.length; i++) {
    for (let j = i + 1; j < str.length; j++) {
      const sub = str.slice(i, j)

      // let's at least check a substring longer than our max so far
      if (sub.length < maxLength) continue

      // fastest way I know to get unique characters
      const charsSet = new Set(sub.split(''))

      // Unequal sizes means a repeated character
      if (sub.length !== charsSet.size) {
        // This breaks the inner loop, advancing the outer one
        break
      }

      maxLength = Math.max(maxLength, j - i)
    }
  }

  return maxLength
}

While this will eventually solve our problem, it's inefficient. The issue with this algorithm is that it cycles through substrings we've checked before. Ones that we know won't yield better results.

For example, if I was testing the string abcb using this approach, we'd start at a and get a length of 3 when we hit the second b. Then we would move the i index, starting at the first b and check b, bc and bcb again, failing at the same spot.

With the sliding window technique, we're able to move the left side of our window all the way past the repeated character, ensuring we're never checking a substring we have already seen before.

Summary

Some problems benefit from checking a "window" of the string or array. Manage two pointers. Use a loop for the end pointer, and advance the start pointer as necessary within that loop.

Hope this technique helps you out some time, maybe even lands you a job! Wish me luck on my interviews, too.

The Consciousness Lottery

Tue, 19 Nov 2024 16:24:07 GMT

This will be a departure from my typical topic of writing, but it's something I've been thinking about for well over a decade and would like to finally put into some words. With no better place to publish this, here will have to do. Do not be surprised if I publish more content in a similar vein in the future.

None of us are born of our will. That is, not one of us chose to be born. Rather, each of us is born against our will. We each had parents that conceived us, a mother that birthed us, and here we are, each participating in a world we had no say in entering.

Not only this, but we had no choice in who we came into this world as. One day, "you" suddenly were "you". "You" were a consciousness embodied in a particular physical form. This is the "consciousness lottery".

There's no reason "you" could not have been "you" differently. No reason "you" could not have gained consciousness at a different time in history, a different geographic location, a different sex, a different ethnicity, of a different social and economic class, etc. No reason at all.

Yet, one day, a particular corporeal form gained "you"-ness and there "you" were.

Think about this for a moment.

Why are you you?

There's no sufficient answer, but it doesn't make the question less worthwhile to ask. In fact, because there is no answer, it makes the question all the more important to ask.

If each of us is "us" against our will, through the sheer luck of an invisible universal lottery, awakening conscious in a body one day, this should vastly increase our empathy towards one another.

Just as there is no good reason that you are you, there is no good reason they are them.

The consciousness lottery is why I find patriotism and nationalism confusing. No one chooses where they are born, so what are you actually proud of? Unless you immigrated and chose to take citizenship, what did you actually do?

The consciousness lottery is why I find racism, sexism, homophobia and transphobia confusing. None of us chose our skin color. None of us chose our sexual orientation. Almost none of us chose our sex, and those who do, can you imagine how difficult a life must be to have gained consciousness in a body that never feels like your own? How are we not empathetic to that plight?

Or what if we examine our own lives through the lens of the consciousness lottery. In my case, in some ways I won the lottery. I was born a white, cisgender, heterosexual male in a country where other white, cisgender, heterosexual males hold an excess of power. I have above average intelligence. I am athletic and coordinated. For a portion of my life, reasonably handsome, etc. None of these "wins" can really be ascribed to anything I consciously chose, but are rather emergent properties of the particular genetics that I was lucky enough to gain consciousness in.

In other ways, I may have lost the lottery. I have autism and ADHD and perpetually struggle in personal relationships and work because of this neurodivergence. I was not born to a well-to-do family which has financially impacted my entire life. My parents suffered from alcholism, various mental health disorders, were abusive or completely dysfunctional. I haven't had familial support in over 25 years. We could even count going bald at a young age, in a world that values hair, as a literal loss. I didn't consciously choose any of that either.

What about you? Have you asked yourself in what ways have you won and loss the consciousness lottery?

My hope is you have, and if you haven't, that you will. But when you do so, I want you to remember, the point of the exercise isn't to feel guilt, shame or pride. It is to recognize the complete arbitrariness of some of your wins and losses. You are you by nothing more than chance.

This doesn't mean you haven't worked hard, or haven't made the most of the "hand you were dealt". This takes nothing away from conscious choices you have made. <Marker content="The discussion on free will versus determinism will have to be another day." /> But it does ask you to consider what was out of your power to control entirely and to think of others in the same way.

So please, add this concept to your vernacular. See how it changes how you view yourself and others.

How I Built “Test Your Focus”

Fri, 15 Nov 2024 03:13:17 GMT

import { TestYourFocus } from './_components'

In my previous post, I use a mini-game as a metaphor for how it feels to have ADHD. I thought we could learn how to build that game with React. Let's get started.

Let's start with defining our component and building out some of the UI. I'm going to break out the parts more than I usually would just for the sake of making it clear which piece is which.

import { Button, Heading } from '~/ui'

const METER_HEIGHT = 300 // Adjust to your liking

function Wrap({ children }: { children: React.ReactNode }) {
  return (
    <div
      style={{
        alignItems: 'center',
        display: 'flex',
        flexDirection: 'column',
        gap: 16,
      }}
    >
      {children}
    </div>
  )
}

function Meter({ height, value }: { height: number; value: number }) {
  return (
    <div
      style={{
        border: '2px solid #e5e5e5',
        // We want a defined height so that we can use
        // a percentage height on the child div
        height,
        position: 'relative',
        width: 50,
      }}
    >
      {/**
       * This is the part of the meter that will grow
       * We anchor it to the bottom of the wrapping div
       */}
      <div
        style={{
          backgroundColor: '#33a1cc',
          bottom: 0,
          height: `${value}%`,
          left: 0,
          position: 'absolute',
          transition: 'height 66ms ease',
          width: '100%',
        }}
      />
    </div>
  )
}

function TestYourFocus() {
  return (
    <Wrap>
      <Heading>Test Your Focus</Heading>

      <Meter height={METER_HEIGHT} value={0} />

      <Button onClick={() => {}}>Click</Button>
    </Wrap>
  )
}

Here, we've established the basic units of our mini-game, the power meter that will display the level and the button we'll use to try and move the meter above the threshold.

Now let's try and design the state management of our game. I'm a big fan of using "event-driven" state management in situations like this, so we'll use useReducer. It may seem like overkill, given we won't be adding all the actions and state I used in the previous post, so feel free to replace this with whatever state management you prefer. The concepts will be roughly the same.

The first thing we need for our game is to track a value. This value will translate to the current height of the powered up portion of the meter. To that end, you could just as easily name it power or level or whatever makes sense to you.

type State = {
  /**
   * The current value of the meter
   */
  value: number
}

// I always write my "initialState" as a factory function
// so as to ensure I get a new object any time I call it
// and don't accidentally reference the same object in
// different components
const getInitialState = () => ({
  value: 0,
})

// We'll add these soon
type Action = any

function reducer(state: State, action: Action): State {
  return state
}

We can add that to our component like so:

function TestYourFocus() {
  const [state, dispatch] = React.useReducer(getInitialState())

  return (
    <Wrap>
      <Heading>Test Your Focus</Heading>

      <Meter height={METER_HEIGHT} value={state.value} />

      <Button onClick={() => {}}>Click</Button>
    </Wrap>
  )
}

Now that we have our value wired up, we need to consider how that value changes. We know that when the user clicks the button, the value should increase, but how and how much? We also know that we need that value to decay, but what's the mechanism for triggering that?

We're going to use a concept I covered in my post on simulations and implement a TICK action. With each TICK, we'll calculate the next value, and utilize impulse and decay states to do so.

type State = {
  /**
   * The rate the value will be decreased each tick
   */
  decay: number
  /**
   * How much the value will be increased with each input
   */
  impulse: number
  /**
   * The current value of the meter
   */
  value: number
}

function getInitialState({
  decay,
  impulse,
}: Pick<State, 'decay' | 'impulse'>): State {
  return {
    decay,
    impulse,
    value: 0,
  }
}

type Action = { type: 'TICK' }

function reducer(state: State, action: Action) {
  switch (action.type) {
    case 'TICK': {
      // We want to clamp the bottom range of our values to 0
      const nextValue = Math.max(0, state.value - state.decay)

      return { state, value: nextValue }
    }

    default:
      return state
  }
}

And with this change to getInitialState, we can now add decay and impulse as props to our component, so that we can fiddle with them and make different tests of focus.

type Props = Pick<State, 'decay' | 'impulse'>

function TestYourFocus({ decay, impulse }: Props) {
  const [state, dispatch] = React.useReducer(
    getInitialState({ decay, impulse }),
  )

  //...
}

So far, we've added the decay to our value, but we didn't add anything that dispatches our TICK action, so let's do that next. We want our TICK to occur on an interval, so we'll use setInterval in a useEffect hook to make this happen.

// This will be our interval in ms. You can adjust the
// denominator to increase or decrease the TICK rate
const FPS = 1000 / 15

// In case you're a real stickler about not recreating
// new objects all the time, you can do this
const TICK = { type: 'TICK' }

// ...

function TestYourFocus({ decay, impulse }: Props) {
  //...

  React.useEffect(() => {
    const id = setInterval(() => {
      dispatch(TICK)
    }, FPS)

    return () => clearInterval(id)
  }, [])

  // ...
}

Now, at a rate of roughly 15 times a second, our TICK is dispatched and our state updated. The last piece we need to add is an Action to add the impulse to our value.

type Action = { type: 'TICK' } | { type: 'CLICK' }

function reducer(state: State, action: Action): State {
  switch (action.type) {
    // ...

    case 'CLICK': {
      // Let's clamp the max value at the full height of the meter
      const nextValue = Math.min(100, state.value + state.impulse)

      return { ...state, value: nextValue }
    }

    // ...
  }
}

// ...

function TestYourFocus({ decay, impulse }: Props) {
  // ...

  const handleClick = React.useCallback(() => {
    dispatch({ type: 'CLICK' })
  }, [])

  // ...
  return (
    // ...

    <Button onClick={handleClick}>Click</Button>

    // ...
  )
}

And now we can play the most rudimentary form of our game.

<TestYourFocus decay={1.5} impulse={10} />

Optimizations

There are a few quick optimizations we can make to our game. First, as it stands, our Meter is re-rendering with every TICK, even if we're not playing the game. Let's memoize the component, that way when the value is pegged at 0 because we aren't playing, it won't rerender.

const Meter = React.memo(function Meter({
  height,
  value,
}: {
  height: number
  value: number
}) {
  //... same implementation
})

Second, we're currently sending TICKs to our reducer 15 times a second, regardless if we are playing or not. Let's add a game status to our state and stop TICKing unless it's running.

type Status = 'idle' | 'running'

type State = {
  decay: number
  impulse: number
  status: Status
  value: number
}

function getInitialState({
  decay,
  impulse,
}: Pick<State, 'decay' | 'impulse'>): State {
  return {
    decay,
    impulse,
    status: 'idle',
    value: 0,
  }
}

// ...

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case 'TICK': {
      const nextValue = Math.min(0, state.value - state.decay)

      return {
        ...state,
        status: nextValue ? 'running' : 'idle',
        value: nextValue,
      }
    }

    case 'CLICK': {
      const nextValue = Math.max(100, state.value + state.impulse)

      return {
        ...state,
        status: 'running',
        value: nextValue,
      }
    }

    default:
      return state
  }
}

// ...

function TestYourFocus({ decay, impulse }: Props) {
  const [state, dispatch] = React.useReducer(
    reducer,
    getInitialState({ decay, impulse }),
  )
  const { status } = state

  // ...

  React.useEffect(() => {
    if (status === 'idle') return

    const id = setInterval(() => {
      dispatch(TICK)
    }, FPS)

    return () => clearInterval(id)
  }, [status])

  // ...
}

Now we no longer TICK unless the game is running, which should reduce re-renders as well.

Next steps

Here's a non-exhaustive list of ideas you could implement next:

Add a threshold and determine if the game has been won
Add a timer and countdown
Add multiplayer with something like PartyKit
Add "modifiers" like I did in my ADHD post

I'm sure you can think of even more.

Full code

As with everything in my blog, the code for this is open source and you can find it here.

What ADHD Feels Like to Me

Mon, 11 Nov 2024 16:48:05 GMT

import { TestYourMight } from './_components'

When I was a kid, I used to go to my neighbor's house to play Mortal Kombat on their Sega Genesis. Occasionally between fights, you'd get to play a mini-game called "Test Your Might". I've been thinking about this game a lot.

In the game, your character stood before a block of material, such as wood, stone, or diamond, and attempted to break it in half. Your "might" was a power bar, and your job was to mash the buttons fast enough to charge the power bar before the time limit expired and your character slammed their fist into the material. As the materials got harder, the difficulty of charging the bar got harder.

It dawned on me, that this is a pretty good metaphor for working with ADHD.

A non-exhaustive primer on ADHD

For those of you who don't know much about ADHD, it stands for "Attention Deficit Hyperactivity Disorder". It's not really an accurate name anymore given what we understand about the disorder now. A more apt name might be "Dopamine Dysregulation Disorder". Fundamentally, the ADHD brain has lower levels of dopamine and struggles to regulate what little dopamine it has.

We all need certain amounts of dopamine to function. Most brains produce an adequate amount of this on their own, which enables them to function with relative ease. There's a task to do, they do it. There isn't much need for inputs such as interest or deadlines (more about those later). The brain has what it needs to focus on, begin, and execute the task.

Since the ADHD brain has so little dopamine, it must constantly seek out stimulation in an attempt to trigger itself to produce more so that it can meet the threshold required to function. This is why almost all ADHD medication is a stimulant. It works by activating your brain to produce more dopamine, which allows you to focus because you no longer need to manually produce it yourself.

ADHD has been unfortunately portrayed in media and culture as a disorder that leads to easy distraction. Who hasn't heard someone yell, "Squirrel!" as a joke about those with ADHD? In reality, people with ADHD aren't distracted because they are undisciplined. Our brains are distracted because our base levels of dopamine are not sufficient enough, and so our brains are constantly seeking new stimuli to achieve the levels we need.

Let's imagine the "Test Your Might" game is a human brain, and we have a task to do. If the game was a neurotypical brain, it might look like the following. Give the button a few clicks to watch the meter grow:

The meter quickly has sufficient dopamine to begin the task, plenty above the threshold. Very little effort was required to get started, and the rate of decay is quite slow.

Let's consider the same situation with the ADHD brain.

Notice the brain struggles to get to the threshold and falls quickly below it. We need to keep clicking the button in order to keep stimulating the brain above the focus threshold.

Understimulated

Sometimes the ADHD brain gets in a mode where it's desperately seeking stimulation, but there's no guarantee that whatever is tried will produce the dopamine desired.

The person might have a number of go-to activities that they find stimulating, but their effectiveness varies often. Something that brought them a lot of joy and focus yesterday might not work today, and there's no way to know for how long the activity will do the trick.

The game below represents this understimulation. Imagine each button as an activity a person might do to find stimulation. Eat some food, scroll their phone, play a video game, do a workout, etc. Which button will work, and for how long before it stops working? Try it out.

Stimulation Modifiers

There are four ways we can "encourage" an ADHD brain to get focused, some positive, some negative: novelty, intrinsic interest, challenge, and urgency. <Marker content="I remember this with the mnemonic NICU." /> In the context of our game, we can think of these as "stimulation modifiers". We can tweak and adjust them and watch how it changes our ability to stimulate the brain across the threshold.

Accumulating modifiers has a positive impact on our ability to reach the threshold and reduce the decay of our dopamine loss. However, we have to be really careful how we deploy these. For people with ADHD, the damage of living in a state of constant urgency to get things done can be significant.

Executive Dysfunction

There are times where no amount of modifiers will do anything. Nothing will allow the ADHD brain to focus, even if it desperately wants to focus.

If you encounter someone in executive dysfunction, you need to understand they aren't just being lazy. The brain is in a physical state that is not allowing for executive function. It is very likely this person is in a shame-cycle, and only the urgency of the situation might get so dire they finally can do the task.

Hyperfocus

Many of you have probably heard of "hyperfocus", and perhaps heard it called a super power. In the right scenario, it can certainly lead to prodigous amounts of productivity, but it often comes with some severe negative side effects as well.

It might not be obvious, especially to those obsessed with productivity, but a certain amount of attention decay is a good thing. You need to remember to do things like eat, go to the bathroom, manage your life, etc. A person in hyperfocus forgets to do all of those things. Full disclosure, when I'm in that state, it feels downright violent to be asked to context switch.

Hyperfocus occurs when our system gets stuck. Yes, it's pegged above the threshold, but there is no reset button. The only way for it to decay is for the system to run out of resources and crash.

I might suggest you refresh the page now. That bar will grow forever.

Closing thoughts

As with any metaphor, this one is imperfect, but I hope it provides some context for the people in your life struggling with ADHD. Imagine having to "test your focus" each and every day. It might help you understand why people with ADHD are far more likely to be clinically depressed. We don't just have less dopamine, but unless we're fortunate enough to find work that aligns with our stimulation modifiers, we spend most of our lives fighting with ourselves to get stimulated enough to do what we need to do.

I may update this post in the future, or write something about how I built this little game with React, or how to work with your neurodivergent teammates better, but this is all the focus I have for now. Hope you understand.

Prefer Explicit Maps

Wed, 30 Oct 2024 16:19:36 GMT

This tip is a bit of a weird one. I genuinely don't think others will like it, but I hope you'll hear me out. At the very least, it might make you think a bit.

I'm a big fan of enumerated states. In TypeScript, a great way to represent this is a union of strings. Let's start with a basic one.

type Theme = 'light' | 'dark'

It might be tempting to make this a boolean, given that there are only two states, but bear with me.

Now, let's make a ThemeContext we could use throughout our app.

const ThemeContext = React.createContext<Theme>('light')

function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = React.useState<Theme>('light')

  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
}

So far, so good. Now, let's add a toggleTheme function to the context and export that. We'll need to make some adjustments.

type ThemeContextValue = {
  theme: Theme
  toggleTheme: () => void
}

// ...

function ThemeProvider({ children }: { children: React.ReactNode }) {
  // ...

  const toggleTheme = React.useCallback(() => {
    // Here's the line to pay attention to
    setTheme(currentTheme === 'light' ? 'dark' : 'light')
  })

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

Do you see this line?

setTheme(currentTheme === 'light' ? 'dark' : 'light')

To use the parlance of the kids, I lowkey hate this line.

I'm not opposed to ternaries, but not all ternaries are the same. Some ternaries represent legitimate binary choices: if this, else that. But some ternaries are really "implicit maps".

A "map" is a data structure that pairs keys to values with a one-to-one relationship. This key always gives me this value. For example, we could create a THEME_LABEL_MAP if we needed to associate strings with our themes, like so:

const THEME_LABEL_MAP: Record<Theme, string> = {
  dark: 'Dark',
  light: 'Light',
}

You can see we've established a one-to-one relationship between the key, a Theme, and a string. Our ternary from above does this, too, but not explicitly. If you squint hard enough, you can maybe see the NEXT_THEME map hidden in there. <Marker content="Astute readers might realize that we've created the world's smallest cyclical graph with <code>NEXT_THEME</code>, and I just think that's fun." />

const NEXT_THEME: Record<Theme, Theme> = {
  dark: 'light',
  light: 'dark',
}

And this is actually how I prefer to write this code. Now our toggleTheme function will look a bit different:

const toggleTheme = () => {
  setTheme(currentTheme => NEXT_THEME[currentTheme])
}

Doesn't that read nicely? Our map is practically a function, it's so elegant.

"But why, Kyle? This seems like overkill!"

Maybe it is. But let's say I had to add a third Theme: high-contrast. What does our ternary look like then?

const toggleTheme = () => {
  setTheme(currentTheme =>
    currentTheme === 'light'
      ? 'dark'
      : currentTheme === 'dark'
        ? 'high-contrast'
        : 'light',
  )
}

I mean, to be fair, we could probably ditch the ternary and make it a bit nicer:

const toggleTheme = () => {
  setTheme(currentTheme => {
    if (currentTheme === 'light') return 'dark'
    if (currentTheme === 'dark') return 'high-contrast'
    return 'light'
  })
}

But why go through all of that, when we could just update the map?

const NEXT_THEME: Record<Theme, Theme> = {
  dark: 'high-contrast',
  'high-contrast': 'light',
  light: 'dark',
}

Our toggleTheme function doesn't have to change at all. NEXT_THEME[currentTheme] just keeps working. <Marker content="Although, perhaps it should be called <code>cycleTheme</code> to be more accurate." /> Bonus points: we didn't change the cyclomatic complexity of our code at all either.

If we learn to pay attention, we can start to recognize situations where using an explicit map might be a simpler way for us to write and maintain our code.

Key takeaways

Consider when enumerating states might serve you better than a boolean
Consider using explicit maps to reduce complexity and improve maintainability

"Why didn't you use `new Map()`?"

Just to address anyone who might ask this: Yes, we could use new Map() to create "real" maps. However, I find the most compelling reason to use a Map is if you need to use something other than a string for a keys. Given that we were using strings for keys, I think its more appropriate and simple to just use an object literal.

My `git` Workflow for Refactoring

Sun, 29 Sep 2024 16:34:56 GMT

import Image from '../../../components/Image.astro' import { ExampleButton, ExampleButtonWithVariant } from './_components'

If you've followed me for any significant amount of time, then you might know that Refactoring by Martin Fowler is the most influential book on writing software I have ever read. It fundamentally changed my approach towards writing code.

The book influenced me so greatly that it led to a change in my git workflow. Adopting the strategy I'm about to show you made it easier for me to refactor code, build upon that change, and get it reviewed quicker than ever. If you work in an organization that uses pull requests and code reviews, I believe this workflow will help you do the same.

The gist of my workflow is this:

Make a branch for only the refactoring work, submit the PR
Then, make a branch off of the refactoring branch, not main for your feature work, and set the base to the refactoring branch when you submit the PR

Some groundwork first

Before we get into the finer details of this workflow, I want to provide a little more context as to why I think it's a good idea to make changes this way.

First, I think it's a really bad habit to refactor and make changes in the same pull request. This practice is extremely common, but it comes with some major downsides:

It's not really a refactor, by definition <Marker content="The definition of a refactor requires that the functionality of the program <em>doesn't</em> change. Thus, adding changes to the same PR breaks this definition. You've really just made two changes, which goes to my next point." />
It's harder to differentiate between what was refactored vs. what was added, what was necessary to change and what wasn't
It creates large PRs, which are more likely to be "rubber stamped" and therefore, more error prone <Marker content="I realize for some devs this is a <em>feature</em>. Creating big PRs to might make it easier to get PR approval due to human laxity, but that doesn't make it right." />

Second, I recognize that many organizations' processes are designed to incentivize large PRs. Anything from compliance requiring separate tickets for every change (so you just stuff it all into one ticket), to the overwhelming pressure to pump out features. I understand there are factors working against you sometimes. My hope is that this strategy fits in that system, as it has for me.

So without further ado, let's break this bad habit and explore this workflow now.

Our example

I figured it would be best to work through an example to demonstrate the process. Our codebase has a rudimentary Button component. It currently has two implicit variants, a primary and secondary style. Let's look at how it was implemented.

const SHARED_STYLES = {
  borderRadius: 9999,
  fontFamily: 'sans-serif',
  padding: '0.35em 1em',
}

const PRIMARY_STYLES = { backgroundColor: 'blue', color: 'white' }
const SECONDARY_STYLES = { backgroundColor: 'lightGray', color: 'black' }

type Props = {
  children: React.ReactNode
  onClick: () => void
  isSecondary?: boolean
  type?: 'button' | 'submit' | 'reset'
}

function Button({
  children,
  onClick,
  isSecondary = false,
  type = 'button',
}: Props) {
  const variantStyles = isSecondary ? SECONDARY_STYLES : PRIMARY_STYLES

  return (
    <button
      onClick={onClick}
      style={{ ...SHARED_STYLES, ...variantStyles }}
      type={type}
    >
      {children}
    </button>
  )
}

We can use our Button component like so:

<Button onClick={() => {}}>Primary Button</Button>
<Button onClick={() => {}} isSecondary>Secondary Button</Button>

And it looks like:

<OffsetWrap> <div class="stack sm:row gap-4 sm:justify-center"> <ExampleButton client:load>Primary button</ExampleButton> <ExampleButton client:load isSecondary> Secondary button </ExampleButton> </div> </OffsetWrap>

Now that we know our starting point, let's consider our task. We need to add a third variant, the danger button, without regressions. How should we do this?

Step 0: Write some tests

In the Refactoring book, Fowler makes it clear that a proper refactor changes the organization and structure of the code without changing its functionality. In order to verify that no functionality has changed, we need tests in place that can assert the correct behavior.

In the case of our buttons, we'd have functional tests ensuring the button worked when clicked, or didn't when disabled, etc. We'd also be well served to have visual regression tests, perhaps with something like Storybook. So before we go refactoring, make sure you can verify that everything works exactly as it did before.

If you do need to write some tests, I recommend making this PR first. You can then build your refactor branch off of the testing branch, similar to how we're going to make our feature branch off of our refactoring branch later on.

Step 1: Refactor

Assuming we have tests ready to go in our main branch, we'll start by creating a branch off of main for our refactor:

git checkout -b refactor-button

Now that we're on new branch, we can make our changes. Adding a danger variant will be very cumbersome if we have to deal with booleans. Booleans are a poor choice for representing finite states and could lead to weird situations that leak implementation details.

A better choice than an isSecondary prop, is a variant prop that takes a string. We'll use TypeScript to define this string as a union of our variants, like so:

type Variant = 'primary' | 'secondary'

type Props = {
  children: React.ReactNode
  onClick: () => void
  type?: 'button' | 'submit' | 'reset'
  variant?: Variant
}

Now that we've added Variant to our types, we can make objects that use Variant as a key to create maps for our styles, like so:

const VARIANT_TO_STYLES: Record<Variant, React.CSSProperties> = {
  primary: { backgroundColor: 'blue', color: 'white' },
  secondary: { backgroundColor: 'lightGray', color: 'black' },
}

And we can now use that map in our component:

function Button({
  children,
  onClick,
  type = 'button',
  variant = 'primary',
}: Props) {
  const variantStyles = VARIANT_TO_STYLES[variant]

  return (
    <button
      onClick={onClick}
      style={{ ...SHARED_STYLES, ...variantStyles }}
      type={type}
    >
      {children}
    </button>
  )
}

From this point, we can git add our changes and commit them.

git add .
git commit -m "refactor button with variants"
git push origin refactor-button

After pushing our branch to remote, we can make a PR for our changes.

Step 2: Adding our `danger` variant

Before we make our additional changes, we're going to make a new branch off of our refactoring branch. So ensuring we are currently on the refactor-button branch, we can then make our new on:

git checkout -b update-button-with-danger-variant

Our work is fairly straightforward from here. We'll add 'danger' to our Variant type:

type Variant = 'danger' | 'primary' | 'secondary'

We'll add danger styles to our style map:

const VARIANT_TO_STYLES: Record<Variant, React.CSSProperties> = {
  danger: { backgroundColor: 'red', color: 'white' },
  primary: { backgroundColor: 'blue', color: 'white' },
  secondary: { backgroundColor: 'lightGray', color: 'black' },
}

And we're done! That's literally all we have to do to add our new variant.

<OffsetWrap> <div class="stack md:row gap-4 md:justify-center"> <ExampleButtonWithVariant client:load> Primary button </ExampleButtonWithVariant> <ExampleButtonWithVariant client:load variant="secondary"> Secondary button </ExampleButtonWithVariant> <ExampleButtonWithVariant client:load variant="danger"> Danger button </ExampleButtonWithVariant> </div> </OffsetWrap>

From here, we can add, commit and push our changes:

git add .
git commit -m "add danger variant to button"
git push origin update-button-with-danger-variant

Up to now, all of this work has been the same, but we need to make a key change with our PR. We need to change the base from the main branch to our refactor-button branch.

Take a look at the "Files Changed" tab when we do. Notice, only the changes we've made since the refactor are there.

If we had kept the main branch as base, then we'd see changes from both the refactoring and our danger addition. This makes sense because we made our updates on a branch that was made from the refactor-button branch. But by changing the base, we're able to only see the diff between the refactor-button branch and our current branch. We've shrunk the git diff considerably, and hopefully shrunk the time to review each PR considerably, too.

I should be clear, if there are any tests we need to add for our new feature, we should add them now as well.

Step 3: Review & Merge

At this point, we've submitted two PRs, which may seem like twice the work for code reviewers, but I would say it's actually less than the amount of work of a single PR.

If both of these changes were in a single PR, you'd have to verify that both the refactor was done correctly, and that the addition worked correctly. There's additional work of review buried in this integration.

When we split them into 2 PRs, they become simple verifications. The refactoring PR simply asks us to verify the tests continue to pass. If they do, then we're ok (assuming the quality of the tests).

The second PR simply asks if we've implemented the new feature. It would be easy to spot if we made an unrelated or additional changes at this stage that need to be addressed.

In the review process, you may realize that there are updates you need to make to the refactoring branch. This is not a problem. Checkout your refactoring branch, make your changes, commit and push. Once you've done that, you can switch to your feature branch, and git rebase the refactoring branch on to it. This will move the commits of your feature branch to after the commits of the refactoring branch, maintaining the correct history. You can fix any conflicts that arise here, though they should be relatively small and few.

Once your PRs have been reviewed, merge the refactoring branch first. This will automatically update the base of your feature branch back to main, allowing you to easily merge that branch in as well.

Summary

Refactoring is a part of writing quality code, and while our processes might not make it as easy to do as we like, there are strategies we can take to make them as easy on ourselves and others to review.

If we can build the habit of making our refactoring PR first, and building our feature on top of that branch, we can start to make code changes and reviews easier for everyone we work with.

I hope you find this git workflow useful. Let me know if you or your team starts to adopt something like this.

Additional resources

While I believe they have recently changed their product offering a bit, their is a tool out there that can do a lot of this automatically for you. It's called Graphite and I encourage you to check it out. I'm not the most persuasive person, so I've never tried to convince a team to try it, but I think it could be very useful to a team willing to adopt it.

Never Call `new Date()` Inside Your Components

Tue, 20 Aug 2024 19:12:27 GMT

import { DiceRoll, Form1 } from './_components.tsx'

As I've gotten older, I find myself arguing less often and discussing code more in terms of preferences than absolutes. That should indicate how strongly I feel about this.

I need our community as a whole to stop calling new Date() and other impure functions inside our components, especially when setting initial state. <Marker content="Yes, there are probably times where it is safe to do so, but you should have a really good understanding of pure and impure functions before you do." /> You're making life harder for yourself.

I have a simple React component, a single date input that defaults to today's date.

// A simple way to set a new Date() to 'YYYY-MM-DD' format
// but use whatever method or lib you prefer
function formatDate(date: Date) {
  return date.toISOString().split('T')[0]
}

function MyDateInput() {
  const today = formatDate(new Date())
  const [date, setDate] = React.useState(today)

  return (
    <label>
      <span>Date</span>

      <input
        type="date"
        onChange={e => {
          setDate(e.target.value)
        }}
        value={date}
      />
    </label>
  )
}

You can see it in action here:

Ask yourself a question: How would you visually regression test this?

The answer is you don't. Not in its current state.

Every time this component is first rendered for testing, the date will (potentially) be different. This is the definition of a flaky test. When I first arrived at one of my previous companies, they had a date input similar to this that they simply updated every single time the Chromatic visual regression test ran. It was extremely disappointing to see.

The reason this changes should be obvious, but for the sake of providing all context possible, it happens because new Date() is an impure function. Every time we call it, we get a different response. That's essentially the opposite of what we want to have happen in a test. In a test, we want the same inputs to always produce the same outputs.

Because we're calling an impure function in our component, our component itself has become impure. How do we fix this?

By passing the impure function (or the result of the impure function) in as a prop instead.

function MyDateInput({ today }) {
  const [date, setDate] = React.useState(today)

  return (
    <label>
      <span>Date</span>

      <input
        type="date"
        onChange={e => {
          setDate(e.target.value)
        }}
        value={date}
      />
    </label>
  )
}

function MyForm() {
  return (
    <form>
      <MyDate today={formatDate(new Date())} />
    </form>
  )
}

Now, testing is dead simple, just pass any formatted date into it.

test('MyDateInput', () => {
  const result = render(<MyDateInput today="2024-08-20" />)
  const input = result.getByLabelText('Date')

  expect(input.value).toEqual('2024-08-20')
})

Note that this allows us to pass in a static date into a visual regression test, eliminating the issue of a new date being rendered each time we build the suite.

A step further

I like to take this pattern a step further and use default parameters in this situation. The most common use case of our input will be passing in formatDate(new Date()), so we should just bake it in for a better developer experience.

function MyDateInput({ today = formatDate(new Date()) }) {
  const [date, setDate] = React.useState(today)

  return (
    <label>
      <span>Date</span>

      <input
        type="date"
        onChange={e => {
          setDate(e.target.value)
        }}
        value={date}
      />
    </label>
  )
}

Now, we have the best of both worlds. We have a component we can treat as a pure function by passing the today prop in, or we can make use of the default. I think of this as a form of dependency injection and have covered the topic before.

Let's make another example

Another common impure function you might see in components (or functions in general) is Math.random(). For these instances, I like to use a randomizer argument, with Math.random set to the default. Consider a DiceRoll component.

const rollDice = () => Math.ceil(Math.random() * 6)

function DiceRoll() {
  const [state, setState] = React.useState(rollDice())

  const roll = () => {
    setState(rollDice())
  }

  return (
    <div>
      <button onClick={roll}>Roll dice</button>
      <Dice number={state} />
    </div>
  )
}

Now, I've made this component with a bit of indirection, extracting the rollDice function, but our same principles apply. rollDice is an impure function because of Math.random, therefore DiceRoll is an impure component because of rollDice. Let's make both rollDice and our component pure functions with default parameters.

const rollDice = (randomizer = Math.random) => Math.ceil(randomizer() * 6)

function DiceRoll({ randomizer = Math.random }) {
  const [state, setState] = React.useState(rollDice(randomizer))

  const roll = () => {
    setState(rollDice(randomizer))
  }

  return (
    <div>
      <button onClick={roll}>Roll dice</button>
      <Dice number={state} />
    </div>
  )
}

Now, we could easily write unit and integration tests for our functions.

test('rollDice', () => {
  // We do need to pass in a `randomizer` that returns values
  // in the range of Math.random
  expect(rollDice(() => 0.01)).toEqual(1)
  expect(rollDice(() => 0.99)).toEqual(6)
})

test('DiceRoll', () => {
  const result = render(<DiceRoll randomizer={() => 0.99} />)

  // `getByText` or whatever way we need to check the value of the dice
  expect(result.getByText(6)).toBeInTheDocument()
})

Wrap up

We don't want to set initial state with impure functions in our components. It makes testing difficult. Instead, pass in the impure function (or its result) as an argument/prop. This will will give us the ability to pass in a pure function as a substitute in a test.

Composable Flourishes

Fri, 02 Aug 2024 02:28:47 GMT

If you've read my blog in recent history, then you're probably aware that I'm a big fan of composition. There's almost nothing you can't solve with enough wrapping HTML elements, functions, or components. <Marker content="Depending on what you're working on, of course." />

One way that composition really shines is in adding "flourishes" around your UI, subtle animations that make the site feel less static and flat. Look at the boxes below fade in. Refresh the page if necessary to retrigger the animation.

Let's build this effect as an Astro component to demonstrate how easy it can be. <Marker content="You can easily do the same in React, but I leave that as an exercise for the reader." />

Our component

We're going to build a composable FadeIn component. We'll be able to wrap any UI we want with it, and fade it in to view as it comes into the viewport. Let's start by setting up the markup portion of the Astro component.

<div class="fade-in-element">
  <slot />
</div>

Yep. That's it!

All we want to do is create a wrapping element for our content. Now, we'll add a some styles to it that will be our animation.

<div class="fade-in-element">
  <slot />
</div>

<style>
  .fade-in-element {
    opacity: 0;
    transform: translateY(20px);
    transition:
      opacity 0.5s ease-out,
      transform 0.5s ease-out;
  }

  .fade-in-element.visible {
    opacity: 1;
    transform: translateY(0);
  }
</style>

By default, our component isn't visible. We'll need to add the .visible class to it to change that. Let's do that now.

/* same markup and styles... */

<script>
  const fadeInElements = document.querySelectorAll('.fade-in-element')

  const observer = new IntersectionObserver(
    entries => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          entry.target.classList.add('visible')
          observer.unobserve(entry.target)
        }
      })
    },
    {
      threshold: 0.1,
    },
  )

  fadeInElements.forEach(element => {
    observer.observe(element)
  })
</script>

With this script, we gather all the FadeIn components, observe them for intersecting the viewport, and add the .visible class when they come into view. We can tweak the threshold to adjust how much of the element must be in view to animate, and we can play with the styles to achieve different animations.

One last touch we might like to add is a delay for when several items are next to each other and we want their animations to cascade a bit.

To do this, we can add a delay prop to our component.

---
type Props = {
  delay?: number
}

const { delay = 0 } = Astro.props
---

<div class="fade-in-element" style={`transition-delay: ${delay}ms;`}>
  <slot />
</div>

Now, we can literally wrap anything in our app and get that subtle fade in animation. For example, the code for boxes at the top of this post looks like this:

<div class="grid grid-cols-3 gap-4">
  {
    [0, 1, 2].map(num => (
      <FadeIn delay={num * 200}>
        <div class="aspect-square rounded-xl bg-accent" />
      </FadeIn>
    ))
  }
</div>

It's not hard to imagine how you could replace the inner div with other components in your application.

Additional things to consider

I don't always love being absolutely thorough in my blog posts. I think it can detract from the lesson to go down all the rabbit holes available. That said, I think there are two things to consider with these flourishes that are pretty important:

`prefers-reduced-motion`

We can make the flourishes more accessible to those who don't like screen motion by making a small change to our styles.

<style>
  .fade-in-element {
    opacity: 1;
    transform: translateY(0);
  }

  @media (prefers-reduced-motion: no-preference) {
    .fade-in-element {
      opacity: 0;
      transform: translateY(20px);
      transition:
        opacity 0.5s ease-out,
        transform 0.5s ease-out;
    }

    .fade-in-element.visible {
      opacity: 1;
      transform: translateY(0);
    }
  }
</style>

This makes the element visible by default, but if they have no preference, applies the styles in the media query.

No JavaScript

This ones a bit more tricky, but you want to make sure your content is still visible if the user has JavaScript turned off. Here are the steps I would take to do that:

Add the class no-js to the html element
In the <head> element, add a small <script> that removes the no-js class
Update styles that would be affected by the presence of a no-js class

Wrap up

Composition gives us the opportunity to make some simple reusable flourishes that can add some pleasant movement to our sites. I encourage you to experiment with this technique for other things. Perhaps you can try scaling or rotations. The possibilities are almost endless, so have fun.

Prefer Alphabetized Object Keys

Tue, 30 Jul 2024 15:27:23 GMT

When it's been a while since I've written a post and I need to get back at it, I like to pick something I can write really quickly and publish right away. So here's one of the quickest tips I have for you: whenever order is not important, prefer to alphabetize the keys of your objects.

As a dev, you spend a lot of time reading code. Anything we can do to increase the speed and efficiency of reading and scanning the code can have a big return on investment in the long run. Alphabetizing the keys of your objects is one of the simplest and easiest ways you can do this.

This shouldn't really be controversial, especially for developers with any knowledge of algorithms and data structures. What's the fastest way to search through an array? Have it pre-sorted. That's what alphabetizing does. It's a default sort for every object in your codebase.

But it's more than scanning, it also speeds up writing. If you always alphabetize your keys, you never have to ask yourself, "Where should I add this?" You pick a name, and you slot it in. You keep the keys sorted.

Now, imagine you've done this for an entire codebase. Every prop, every object type, interface, map, and dictionary is alphabetically sorted. Because of this order, you save a second or two every time you have to look for a key. You do this multiple times a day, you do this for a full year. It sounds silly, but you might have saved a few hours over the course of a year.

What about logical groupings?

There's a reason I use the word "prefer" in the title of these posts. There may be a time where the order of keys matters, or putting them in a "logical" grouping might be better. If that is the case, I like to indicate that with a comment and possibly some whitespace.

// WARNING: ORDER HERE MATTERS!
const obj = {
  foo: 1,
  bar: 2,
  baz: 3,
}

// Or

const styles = {
  backgroundColor: 'papayawhip',
  color: 'black',
  fontSize: '1em',

  // Positioning
  position: 'absolute',
  top: 0,
  left: 0,
}

The point is, exceptions can be made, but they should be exceptions.

How do I make this easy to do?

There are ESLint rules you can use to enforce and fix this, but I've never been on a team that used it, and I'm not sure this is a hill I'd care to die on either. Instead, I just alphabetize keys as I do my work with a simple key combination.

Now, if you use VSCode, I think it might have a default sorting key combo, but I have mine bound to cmd + shift + a (a is for "alphabetize"). Like so:

{
  "key": "cmd+shift+a",
  "command": "editor.action.sortLinesAscending"
}

All I have to do is highlight a group of key/value pairs, hit the key combo, and it's done.

Wrap up

I don't think is a life-altering tip. If you never alphabetize an object in your life, you'll be fine. But for me, it saves a good amount of time and energy reading and writing code.

We don't talk a lot about code style guidelines these days. Not since Prettier came on to the scene. In general, that's a good thing, but having some small rules & principles like this one, even if they're only for you with no real impact to others, can make your code more consistent, and consistency leads to speed over time.

Responsive Design and Composition

Sat, 15 Jun 2024 02:34:01 GMT

import { Presenter } from './_components.tsx'

Do me a favor. Change the width of your browser while watching the UI below. Go really narrow, and go really wide.

You see what changed? The spatial relationship between the image, description, and role changed. Some font sizes and weights changed. The amount of border radius on the image changed, too.

I recently came across this exact responsive layout in a client's codebase. The UI changes aren't unreasonable. I can agree that it's a better layout given the size constraints. But if you try and achieve this with a single composition of elements and classes, you're going to have to do some wild CSS shenanigans to make it work.

And that's exactly what they had done.

Here's a pared down version of what I came across in the codebase. I've removed a lot of the stylistic classes, and left you mostly with the classes needed for the UI changes across breakpoints. Hope you're good at reading Tailwind classes (which isn't the problem at all; this would be a CSS mess, too):

function Presenter({ description, image, name, role }) {
  return (
    <figure className="grid grid-cols-[auto,1fr] items-center gap-x-4 gap-y-8 sm:grid-cols-12 sm:grid-rows-[1fr,auto,auto,1fr] sm:gap-x-10">
      <div className="col-span-2 text-xl sm:col-span-7 sm:col-start-6 sm:row-start-2">
        {description}
      </div>

      <div className="col-start-1 row-start-2 overflow-hidden rounded-xl sm:col-span-5 sm:row-span-full sm:rounded-3xl">
        <Image
          src={image}
          className="h-12 w-12 object-cover sm:h-auto sm:w-full"
        />
      </div>

      <figcaption className="text-sm sm:col-span-7 sm:row-start-3 sm:text-base">
        <span className="font-bold">{name}</span>
        <span className="hidden font-bold sm:inline">, </span>
        <br className="sm:hidden" />
        <span className="sm:font-bold">{role}</span>
      </figcaption>
    </figure>
  )
}

So yeah... do you want to maintain this?

Yeah, I didn't think so.

Now look, I understand why this happens. It's really easy to empathize with the challenge the original dev or devs faced in making this work. Let's give them some credit. They were clever enough to come up with a grid layout that could accommodate their needs.

That said, cleverness is not the answer. <Marker content="It rarely is." /> They made this way harder than it has to be. But how could they have known there is an easier way hidden just below the surface? There are two clues here that make it clear what we should do instead.

First, the layout of the elements changes. It would be one thing if all their spatial relationships remained the same. The name stays above the image. The description always has name and role beneath it. But it doesn't. The layout changes. I mean, they went so far as to have a br element that is removed from the page! You know we're up to something weird if that's happening. All of this should be a signal that maybe we want to solve this with multiple compositions instead.

Second, there are lots of "little conditionals" here if you look closely. Just because you don't see the keyword if, doesn't mean they aren't there. Everywhere we see sm:, we can think of that as a conditional. "If we are at a breakpoint larger than sm, do this". I see 17 conditionals in the code example. That's way too many!

What if I told you we only need two?

Multiple compositions to the rescue

When we have the same condition many times lower in our tree of components and elements, we can often lift it up higher and reduce how many times it needs to be checked. <Marker content="That trick applies to a lot more than just components, too. Use it in your functions and watch them get simpler." />

In our case, we can turn Presenter into a facade, that renders either a PresenterNarrow or PresenterWide composition.

First, the facade:

function Presenter(props) {
  return (
    <div>
      <div className="sm:hidden">
        <PresenterNarrow {...props} />
      </div>

      <div className="hidden sm:block">
        <PresenterWide {...props} />
      </div>
    </div>
  )
}

Isn't that simpler?! Now that we can guarantee what context each sub-composition will render in, we can arrange the elements without all the wild grid shenanigans to get the job done, and make a few reusable pieces we can use across compositions as well.

First, our shared pieces. The bigger name and description components:

function Name({ children }) {
  return <h2 className="font-sans text-2xl font-bold">{children}</h2>
}

function Description({ children }) {
  return <div className="font-sans text-lg">{children}</div>
}

Next, our PresenterNarrow composition:

function PresenterNarrow({ description, image, name, role }) {
  return (
    <div className="flex flex-col gap-4">
      <Name>{name}</Name>
      <Description>{description}</Description>

      <div className="flex flex-col gap-2">
        <img className="h-12 w-12 rounded-xl" src={image} alt={name} />

        <div>
          <div className="font-sans text-sm font-bold">{name}</div>
          <div className="font-sans text-sm">{role}</div>
        </div>
      </div>
    </div>
  )
}

And finally our PresenterWide composition:

function PresenterWide({ description, image, name, role }) {
  return (
    <div className="flex items-center gap-12">
      <div className="flex w-[40%] shrink-0 flex-col gap-4">
        <Name>{name}</Name>
        <img className="w-full rounded-3xl" src={image} alt={name} />
      </div>

      <div className="flex grow flex-col gap-4">
        <Description>{description}</Description>
        <div className="font-sans font-bold">
          {name}, {role}
        </div>
      </div>
    </div>
  )
}

How much easier is that code to read, understand, and maintain?! Bonus, if you need to make a change, you can go directly to the component that needs it. You don't have to figure out where in the single composition you have to tweak to get it to work correctly.

So the next time you're struggling with a component that is challenging to make responsive, consider making multiple compositions, one for each layout, and then move the responsive condition up the tree to render the appropriate sub-composition when necessary. I think you'll find your life got a little bit easier doing it that way.

Design System Retrospective

Thu, 23 May 2024 15:51:54 GMT

import { Button } from '../../../components/Button.tsx'

Before starting Agathist, I worked for a couple years at a healthcare startup on the "Frontend Platform" team. My job was to build and design the tooling and internal libraries we would use to develop all of the frontend clients for the company.

All of my work involved one unique constraint: everything has to work on both React web and React Native.

This presents a lot of challenges and I could write a lot of blog posts about them, but today I want to share what I think was my biggest mistake with the design system, why I think so, and what I'd do differently.

What problems were we solving?

Before we get into the design system, I think it's important to discuss what problems we were trying to solve by making one.

Here were the main issues:

Inconsistency

None of their products were visually consistent. You could easily see 4 different eras of styling throughout their products. It was visually unappealing. They wanted a system that could be used across their apps to unify their feel and user experience.

Developer velocity

The developers were very slow to build and release features. One of the reasons <Marker content="Though honestly, not remotely the biggest reason" /> is that new features were written with bespoke CSS, via styled-components, and none of it was type-safe or systematized. When you're manually writing styles for everything, you're going to be slow.

A dumpster fire of an existing "design system"

An attempt at a design system already existed. It started off with the intentions of being a small UI library, but quickly became the place all code was developed. <Marker content="This is because it was too painful to build in the apps themselves. There was a lot of work that needed to be done to modernize the infrastructure of the apps and get to a better, faster developer experience." /> There were several problems with this model, but most notably it became tightly coupled. There were data fetching calls in the library, there was business logic every where. It was no longer a library, but an awkward, vestigial appendage of the existing apps.

There were more problems to be solved by the new design system, but those are the main ones.

My solution

I could solve all three of these problems by making a new design system that eliminated any need for bespoke CSS, was completely type-safe, and never tightly coupled.

The way I chose to do this was to develop a set of components in the same vein as Chakra UI. If you're unfamiliar with Chakra, it is a set of composable components, all built on a base primitive of a Box. Box has a large set of props that are mappable to styles. Props regarding margin, padding, background color, etc.

I, too, built us a Box on top of the React Native Web project, but I made all of the props conform to our design system. For example, we had a palette of colors, and rather than have you pass the color value to the Box, I had you write the color key and did the mapping under the hood for you. Like so:

<Box backgroundColor="gray-300">
  <Text>I am some example text.</Text>
</Box>

We mapped every prop to keys so you could never deviate. Border radiuses, border thicknesses, padding sizes, gap sizes, etc. Everything had to be done thru the props system. It was awesome because you got Intellisense autocomplete and type errors when you did something wrong.

We made many other components on top of Box. Components like Row and Stack and Button, Input, Textarea, etc. The entire system was built around composing Boxes and other primitives like Pressable and Text. It was a rock solid foundation. It was robust. You could not break it or screw it up. It was very fast to use and scaled exceptionally well.

It just had one problem.

Lots of people struggle to build things compositionally.

The company severely lacked frontend talent, as it had historically over indexed on fullstack devs who were really backend devs. So many of these people just couldn't wrap their head around how to properly arrange and compose these components to get the layouts they needed. They were so used to solving everything with some truly tragic CSS that they were quagmired by composition, incapable of seeing alternative ways to achieve the layouts they needed.

Let me give you an overly simple example to explain.

Using composition to design

In a world where you must support React and React Native, you only have one layout mechanism: Flexbox. Flexbox is an inherently compositional system. The styles of the parent affect the styles of the children. Composition is how we change the layout of children.

When I first arrived, the designers had the idea of having a width variant on the Button. They wanted Buttons that were just a little bigger than the text, we could call it an inline-block button, and they wanted Buttons that expanded the full width of their parent. They were adamant that they needed two sizes.

"No, you don't. You only need one size," I said boldly. They were a bit shocked and confused. And then I showed them this.

Here are two Buttons:

<div class="my-8"> <OffsetWrap> <div class="flex flex-col gap-4"> <Button onClick={() => {}}>Click me</Button>

  <div class="flex flex-row">
    <Button onClick={() => {}}>Click me</Button>
  </div>
</div>

</OffsetWrap> </div>

Stylistically, there is nothing different about them. I didn't change their markup at all or give them different classes. All I did was change what Flex context each Button is in.

<Stack>
  <Button onPress={() => {}}>Click me</Button>

  <Row>
    <Button onPress={() => {}}>Click me</Button>
  </Row>
</Stack>

A Stack is a Flex column context, a Row a Flex row context. The default align-items in a Flex context is stretch. This means children of a Flex column parent behave similar to block level elements. They fill the full width of their parent.

On the other hand, children of a Flex row parent behave like inline or inline-block elements. They shrink to the size of their minimum content width.

The designers were a bit stunned that they could have both buttons just by changing the context they were rendered in.

But this was a challenge for devs. They were slow to understand that the way to have an inline-block-like button was to wrap it in a Row. Even after I did multiple demos and wrote examples in our documentation. It never became intuitive for them.

I'd have people ask me, "What if I want multiple buttons of the same width next to each other?"

Easy. More composition:

<Row>
  <Row.Item grow={1} shrink={1}>
    <Button onPress={() => {}}>Click me</Button>
  </Row.Item>

  <Row.Item grow={1} shrink={1}>
    <Button onPress={() => {}}>Click me</Button>
  </Row.Item>

  <Row.Item grow={1} shrink={1}>
    <Button onPress={() => {}}>Click me</Button>
  </Row.Item>
</Row>

<div class="my-8"> <OffsetWrap> <div class="flex flex-row gap-4"> <div class="flex shrink grow flex-col"> <Button>Click me</Button> </div> <div class="flex shrink grow flex-col"> <Button>Click me</Button> </div> <div class="flex shrink grow flex-col"> <Button>Click me</Button> </div> </div> </OffsetWrap> </div>

Every Flex container came with an .Item compound component that we could use to apply values like grow, shrink, basis, or alignSelf to. It enabled us to compose any arrangement we needed.

Taking it a step further, I could wrap the children of a Flex container under the hood with Flex.Items and give them a nice API like this:

<Row childrenGrow={1} childrenShrink={1}>
  <Button onPress={() => {}}>Click me</Button>
  <Button onPress={() => {}}>Click me</Button>
  <Button onPress={() => {}}>Click me</Button>
</Row>

This manner of composing things applied to other ways of styling and manipulating elements, too. For example, box-shadows in React Native are a giant pain in the ass, so I made a Shadow component that you just wrapped other components in that did all the iOS and Android magic under the hood.

<Shadow>
  <Card>{/* other stuff */}</Card>
</Shadow>

The whole system depended on this ability to compose components together to achieve what we desired. It really was a solid system and something I was proud of.

So what was the problem?

The main problem was there are two types of composition, and most people are ok at object composition, and aren't very good at functional composition.

The struggles with this kind of composition made me realize something: many devs don't write styles from a deep, rooted place of knowledge and know exactly what they need to write to make it do what they want; they write code by throwing stuff at the wall until it sticks.

I promise you, that's not an insult. I was the one who failed. Not the other devs.

Even though writing styled-components with bespoke CSS over and over was really slow and led to literally thousands of unnecessary lines of styling, it had one major benefit: people could easily try stuff.

Yes, they wrote a lot of redundant styles. Yes, there were tons of poor choices made. But they could kinda make it work. The user wouldn't really know it was a pile of hot, unmaintainable garbage under the hood, and it would be someone else's mess to deal with later.

The problem with the Chakra UI-like system was there were almost no escape hatches in the entire system. You either had to really understand how to compose your way to a solution, or you were stuck. There wasn't enough surface area for anyone to throw something at the wall. That was entirely on purpose. It solved our original problems, but it meant many devs struggled to adapt.

What I would do differently

After a while, I came to recognize the struggle devs were having. No amount of training or documentation seemed to be helping either. Some of them just weren't getting it and didn't really care to try and learn the system anyways. I felt like I had failed them. <Marker content="Even if, realistically, I hadn't" />

I spent a lot of time thinking about the new problem I had created, and I eventually realized what I would do differently. If I could go back and do it again, I would have built the design system around Tailwind/NativeWind instead.

My main reasoning goes like this: Fewer devs struggle to compose objects or tokens than they do functions. I would be giving up some of the restrictiveness that ensured rightness we had with the Chakra UI-style design system, but I'd make it far simpler for devs to try things out. To throw things at the wall again. Our codebase would receive more sub-optimally written features, but at least they would have features.

I think this path would have been an easier leap from the bespoke CSS of styled-components to composing Tailwind classes.

Now, there are challenges with this approach, too. In the last couple of months, I have built another cross platform design system (and their apps) for a client that's following this approach. Nativewind is imperfect, <Marker content="And at the time we started, we had to use the unofficially released v4 which is not something I would generally recommend or do." /> and we've had to build a lot of components from scratch with the approach, but overall, the other devs are at least able to try things and move forward.

Summary

Some people will always struggle with using functional composition to build what they need to build. They need more escape hatches. Making the right tradeoff regarding how restrictive the system was may have made it easier to adopt for many devs. Going forward, I'll consider this more deeply in my decisions.

Prefer Noun-Adjective Naming

Sat, 18 May 2024 23:21:57 GMT

This one will be super short.

In English grammar, the adjective comes before the noun. The green house. The large dog. The old man. Etc, etc.

Because of this, we tend to also name our functions, components, objects, etc, the same way. PrimaryButton, DefaultHeader, StandardLayout, etc.

I prefer to use noun-adjective naming for one simple reason: alphabetical order.

Let's say I'm creating several components related to the same noun. I've been working on a streaming app for a client recently, so I'll use a Stream as my noun. A Stream can be in three states: created, ended, or live.

If I follow English grammar and make components for each state, I end up with CreatedStream, EndedStream, and LiveStream.

Now, imagine that these are right next to all your other components in the same directory. They could be separated by dozens of components inbetween C and E, or E and L.

- CreatedStream.tsx
- CurrentUser.tsx
- EndedStream.tsx
- FullScreen.tsx
- GoLiveButton.tsx
- LiveStream.tsx
// etc...

Also, try searching for them. What if you forget that it's Ended and not Completed for that stage. You have to get the right adjective to get your search on the right path. <Marker content="Fuzzy search will probably work for you, but it's still easier to search starting with the noun." />

But if you flip them and go noun-adjective, StreamCreated, StreamEnded, and StreamLive, all your components are right next to each other in your directory.

- ButtonGoLive.tsx
- ScreenFull.tsx
- StreamCreated.tsx
- StreamEnded.tsx
- StreamLive.tsx
- UserCurrent.tsx
// etc...

In addition, it's much easier to search this way. Just type the noun Stream and choose which one you need.

It's a small change, but I think it makes for far better organization in your codebase. Try it, see if you like it, too.

Prefer Multiple Compositions

Fri, 17 May 2024 21:12:18 GMT

Consider the following absurdly simple example:

function VideoControls() {
  const { isPlaying, play, pause } = useVideoControls()

  return (
    <Button onPress={isPlaying ? pause : play}>
      <Icon name={isPlaying ? 'pause' : 'play'} />
      <Button.Text>{isPlaying ? 'Pause' : 'Play'}</Button.Text>
    </Button>
  )
}

We have ourselves a Button that presumably controls the state of a video. It's not that complicated and probably very similar to many components you've seen over time.

This is a valid way to write this component. With something this simple, there's not a lot of concern regarding the implementation.

That said, if we think about the pattern more broadly, that is the pattern of handling all conditions in a single composition, I think we can start to see some weaknesses in writing code this way.

The thing that makes me question whether we should use the single composition pattern here is that we have three conditionally rendered pieces that all are based on the same value. In my experience, when many decisions hinge on a single value, it's better to prefer multiple compositions, even when it's more verbose, than to do so much conditional handling inline.

If we prefer composition, our VideoControls will look like this:

function VideoControls() {
  const { isPlaying, play, pause } = useVideoControls()

  if (isPlaying) {
    return (
      <Button onPress={pause}>
        <Icon name="pause" />
        <Button.Text>Pause</Button.Text>
      </Button>
    )
  }

  return (
    <Button onPress={play}>
      <Icon name="play" />
      <Button.Text>Play</Button.Text>
    </Button>
  )
}

You can even take it a step further easily:

function VideoControls() {
  const { isPlaying } = useVideoControls()

  return isPlaying ? <PauseButton /> : <PlayButton />
}

function PauseButton() {
  const { pause } = useVideoControls()

  return (
    <Button onPress={pause}>
      <Icon name="pause" />
      <Button.Text>Pause</Button.Text>
    </Button>
  )
}

function PlayButton() {
  const { play } = useVideoControls()

  return (
    <Button onPress={play}>
      <Icon name="play" />
      <Button.Text>Play</Button.Text>
    </Button>
  )
}

Now, in an example like this, you might argue that this looks worse. "I don't like early returns!", "I don't like small components!" I can hear some people say.

Yes, the example of a single Button might be a bit too rudimentary for us to be overly concerned with how we write it, but it exemplifies common choices we make in far more complicated components.

Because JavaScript and React are so flexible, we can tend not to give much thought to how we organize our code for maintainability. We see a problem there, we put an inline fix there. Job done.

But as the product gets more complicated, we can start to lose velocity when there are lots of "little conditionals" littered about. It's less obvious which branch of logic you are in. Are these conditionals related? Are they not? Often, we need to read almost every line of code to figure it out.

But if we prefer multiple compositions like we did in the second and third example, notice what we accomplished. We went from three conditionals to just a single one. I would argue that the code is much simpler and we have made it a lot harder to introduce bugs. How easy would it be to reverse a ternary accidentally?

If you're not already convinced that composition leads to better components, let's consider some more examples.

What if we're fetching data on the client? Sure, there might be parts of the UI that need to be there regardless of the state of the data fetching, but often times we could write entirely separate compositions that map nicely to each state we could be in.

function DataView() {
  const { data, error, isLoading } = useGetMyData()

  if (isLoading) {
    return <LoadingComposition />
  }

  if (error) {
    return <ErrorComposition error={error} />
  }

  if (isEmpty(data)) {
    return <EmptyComposition />
  }

  return <SuccessComposition data={data} />
}

Preferring composition also works nicely with objects that share a discriminated union. I'm working on a streaming app for a client at the moment. The Stream can be in several phases: 'created' | 'live' | 'ended'. The screens for these different phases can be quite different. The following is an extremely pared down version of some of the different UI rendered per phase. I could write some code like this:

function StreamDisplay({ stream }: { stream: Stream }) {
  const { phase } = stream

  let additionalClasses = ''

  if (phase === 'ended') {
    additionalClasses = 'justify-center items-center'
  }

  if (phase === 'created') {
    additionalClasses = 'justify-end'
  }

  return (
    <View className={`relative flex flex-1 flex-col ${additionalClasses}`}>
      {phase === 'live' && (
        <View className="absolute right-4 top-4">
          <VideoControls />
        </View>
      )}

      {phase === 'ended' && <Text>Stream has ended.</Text>}

      {phase === 'created' && <GoLiveButton />}
    </View>
  )
}

I hope you agree with me, that this is all over the place. We're changing Flex properties based on phase, we're conditionally rendering buttons and text and all sorts of other stuff. It's accurate, but I think it's way more convoluted than necessary. We don't need to write our components this DRY. I'd much rather repeat myself a bit, and make it much easier to read, maintain and update. Like so:

function StreamDisplay({ stream }: { stream: Stream }) {
  const { phase } = stream

  if (phase === 'created') {
    return (
      <View className="flex flex-1 flex-col justify-end">
        <GoLiveButton />
      </View>
    )
  }

  if (phase === 'ended') {
    return (
      <View className="flex flex-1 flex-col items-center justify-center">
        <Text>Stream has ended.</Text>
      </View>
    )
  }

  if (phase === 'live') {
    return (
      <View className="relative flex-1">
        <View className="absolute right-4 top-4">
          <VideoControls />
        </View>
      </View>
    )
  }

  return null
}

And if I'm being honest, I probably actually write it like this:

function StreamDisplay({ stream }: { stream: Stream }) {
  switch (stream.phase) {
    case 'created':
      return <StreamCreated stream={stream} />

    case 'ended':
      return <StreamEnded stream={stream} />

    case 'live':
      return <StreamLive stream={stream} />

    default:
      return null
  }
}

My point is simple. Even if we have to write a few more wrapping elements, by favoring composition, we make the code wildly more understandable and maintainable. You spend absolutely no time trying to figure out if you're in the correct component or not.

If our Stream ever gets another phase, we just make another composition. If the live phase needs an update, we don't need to hunt through StreamDisplay and make sure we don't break anything for the created and ended phases. We can go straight to StreamLive and add it.

I hope this post elucidates some of the challenges you might have felt but not verbalized in working with lots of little conditionals in your code. Preferring multiple compositions can make your work a lot more understandable and maintainable, and now you know how to do it.

There are several related posts below that I think you'll enjoy, check them out if you have time.

`align-items: center` vs. `text-align: center`

Sat, 04 May 2024 16:39:19 GMT

For going on three years now, I've been working daily in an environment where all the code that I write has to support both React and React Native. People unfamiliar with what it takes to support both platforms might not realize a few restrictions you must deal with. One of them is this: Flexbox is your only layout option.

That's right. No tables. No grids. No anything else. Flexbox is all you got.

Because of this, there's a common mistake I've seen developers make over and over I want to demonstrate and fix.

In React Native, every element at a fundamental level is a View or a Text. Thus, when creating components that work across platforms, we have to use these View and Text components on web, too. Generally, this is accomplished through a library like react-native-web, which renders the correct underlying component depending on the platform.

It's important to know that there is one key difference between a View and a div: a View is not a block level element.View is a flex container with flex-direction set to column.

With that in mind, now I'm going to show you two very similar examples, and I want you to spot the difference.

<div class="my-8 flex flex-col gap-4 md:flex-row"> <div class="flex grow flex-col items-center rounded-xl border-2 p-4"> <span class="font-sans">Lorem ipsum</span> </div> <div class="flex grow flex-col rounded-xl border-2 p-4"> <span class="text-center font-sans">Lorem ipsum</span> </div> </div>

Did you spot it? What about now?

<div class="my-8 flex flex-col gap-4 md:flex-row"> <div class="flex grow flex-col items-center rounded-xl border-2 p-4"> <span class="font-sans"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum, arcu id faucibus accumsan, turpis ex interdum est, eget tristique odio odio eget nibh. </span> </div> <div class="flex grow flex-col rounded-xl border-2 p-4"> <span class="text-center font-sans"> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum, arcu id faucibus accumsan, turpis ex interdum est, eget tristique odio odio eget nibh. </span> </div> </div>

You see the difference? Both examples are Flex columns. The first example has set align-items to center, while the second example has kept the default align-items of stretch, but used text-align: center on the text instead. This is a small detail that's easy to overlook, but can have you scratching your head later trying to get things to align the way you'd like.

When the text is short, it can seem like which CSS you use doesn't matter, but if we were to add a background to the text in our first two examples, we'd notice the difference right away.

<div class="my-8 flex flex-col gap-4 md:flex-row"> <div class="flex grow flex-col items-center rounded-xl border-2 p-4"> <span class="bg-pink-500 font-sans text-white">Lorem ipsum</span> </div> <div class="flex grow flex-col rounded-xl border-2 p-4"> <span class="bg-pink-500 text-center font-sans text-white"> Lorem ipsum </span> </div> </div>

When we change align-items to center, we shrink all the children to their minimum content width. For text that is shorter than the width of its container, it will appear the same as text-align: center, but will behave differently once our text starts to wrap.

My main reason for pointing this out is that I so often see unnecessary compensations on the children of a Flex container. Yes, sometimes it might be easier to set a particular align-items on the parent, and then use align-self on a child to make an adjustment. That's why the CSS property exists, but often these compensations are unnecessary entirely.

For example, if we use align-items: center instead of setting the text-align on the title, and we later have an element that we need to take up the full width, we might compensate by setting it's width to 100%.

<div class="my-8 flex flex-col items-center gap-4 rounded-xl border-2 p-4"> <div class="bg-pink-500 font-sans text-white">This is an example title</div> <div class="w-full bg-pink-500 font-sans text-white"> This is an example paragraph with the width set to 100%. </div> </div>

We could avoid that simply by setting text-align: center on the title instead.

If you peek under the hood at the Tailwind for that example, you'll see we've added two classes when one would have done the job. Do this enough times across an app, and the number of unnecessary styles can really grow.

This is a simple thing to get confused about and only notice later when you're making a lot of compensations on the children to get things aligned correctly. Hopefully by seeing this simple example, the gears will start turning and you'll spot when you might need to use one or the other, or even sometimes both.

Creating a React Native “Curved Bottom Bar” with Handwritten SVG

Sat, 20 Apr 2024 15:45:12 GMT

import { CURVED_TAB_BAR_D, Shape } from './_components.tsx'

I'm building my first full React Native app right now for a client and ran into a challenging problem right away. There's a trend in native apps for the bottom tab bar to have a cutout for a larger circular action button right in the middle. I've seen it called the "curved bottom bar" in my research. To make it clear what I'm talking about, let me share the first example I found on my phone, which was from Venmo:

Notice that you can see the text of an item beneath and through the cutout. That's a key feature of this design. In researching how to accomplish this, I found several libraries, but none of them were ready to work with the routing we're using in the applications. I was going to have to do it from scratch.

What I found was most people accomplished this using SVG, which is ironic given that React Native doesn't natively support SVG. What I found interesting about how they were accomplishing it was their use of d3's d3-shape package instead of writing the SVG by hand, which is remarkably easy to do. Let me prove it to you.

Through the course of this post, we're going to build this:

We'll do it step by step, so you can follow along.

Writing SVG by hand is a lot simpler than you might suspect. It reminds me of learning regular expressions. It looks really intimidating, but once you learn a few things, it becomes far less scary. We can combine some basic SVG skills with "parametric design" principles to create a custom shape that will be perfect thanks to math.

Everything I've ever learned about writing SVG by hand comes from this: The SVG Pocket Guide. It's a wonderful resource and I go back to it time and time again. I encourage you bookmark it, as I'm sure you'll do the same.

Drawing the shape

We're going to draw this shape using a path element. Drawing a path is a lot like giving instructions to a someone with a pencil. Start here, go there. Move to here, draw a line to there. Close the loop. You just have to learn how to read the way we give the path those instructions.

We're going to partner this with parametric design by using variables. These variables will describe certain values we want in our path. That way, if we want to tweak something, we just tweak a variable and our path updates.

We're going to build a basic rectangle first as the foundation of our shape. We're going to start in the bottom-left corner of the rectangle and work our way around the shape clockwise. Let's see the code, and then I'll break it down.

const WIDTH = 320
const HEIGHT = 48

/**
 * Line by line explanation
 * - Start in the bottom-left
 * - Draw a line to top-left
 * - Draw a line to top-right
 * - Draw a line to bottom-right
 * - Close the path
 */
const d = `
M0,${HEIGHT}
L0,0
L${WIDTH},0
L${WIDTH},${HEIGHT}
Z
`

function Shape() {
  return (
    <svg width={WIDTH} height={HEIGHT}>
      <path d={d} />
    </svg>
  )
}

We've stored some values for the width and height of our shape and we can change those to suit our needs. Next, we've created a d variable, which is the value we hand to our path element. Let's break down this string further.

M stands for moveTo. We're giving our path the instruction of moving to the bottom-left of our shape. Coordinates work as if 0,0 is the top-left of our space, moving positively to the right and down. This makes ${WIDTH},${HEIGHT} the bottom-right of our shape. If you're wondering why we started in the bottom-left, those reasons will reveal themselves soon.

So we've moved to the point of 0,${HEIGHT}. Next, L stands for line. More specifically, draw a line from our current point to the next point. So when we say L0,0, we're drawing a line from the bottom-left to the top-left of our shape.

From there, we make two more lines to the top-right and bottom-right of our shape. However, we don't draw a third line back to the place we started. Instead, we use the Z command. This tells the path to "close", which returns to where we started. Thus, we get this shape:

Next, let's add the rounded top corners. That update looks like this:

const WIDTH = 320
const HEIGHT = 48
const CORNER_RADIUS = 12

/**
 * Line by line explanation
 * - Start in the bottom-left
 * - Draw a line towards the top-left to the start of our corner radius,
 *    use the top-left as the curve control point,
 *    and curve to the other end of our corner radius
 * - Draw a line towards the top-right to the start of our corner radius,
 *    use the top-right as the curve control point,
 *    and curve to the other end of our corner radius
 * - Draw a line to bottom-right
 * - Close the path
 */
const d = `
M0,${HEIGHT}
L0,${CORNER_RADIUS} Q0,0 ${CORNER_RADIUS},0
L${WIDTH - CORNER_RADIUS},0 Q${WIDTH},0 ${WIDTH},${CORNER_RADIUS}
L${WIDTH},${HEIGHT}
Z
`

function Shape() {
  return (
    <svg width={WIDTH} height={HEIGHT}>
      <path d={d} />
    </svg>
  )
}

We added a variable and a few instructions! Let's break them down.

CORNER_RADIUS describes how far we want to start the curve from the corners. We can add or subtract that value from other values to properly place the start and end points of our curves, and the Q command is how we make those curves.

Q stands for "quadratic bézier curve" and it takes two coordinates for its command: the control point and the end point. Think of it this way, a segment of path is drawn from the start point to the end point. Then, the control point is moved to change how the line curves between the start point and end point.

So when we see:

L0,${CORNER_RADIUS} Q0,0 ${CORNER_RADIUS},0

We're telling the path to draw a line to 0,12, use 0,0 as the control point, and curve to 12,0. If we change the value of CORNER_RADIUS, then it would change which points it uses.

When we render our new shape, we get:

Next, let's work on the cutout semi-circle in the middle. We can use math to get this centered and curved correctly. We'll be adding quite a few variables, so don't get overwhelmed. They'll make sense soon enough.

const WIDTH = 320
const HEIGHT = 48
const CORNER_RADIUS = 12
const CUTOUT_RADIUS = 30
const CUTOUT_LEFT_X = WIDTH / 2 - CUTOUT_RADIUS
const CUTOUT_RIGHT_X = WIDTH / 2 + CUTOUT_RADIUS

/**
 * Line by line explanation
 * - Start in the bottom-left
 * - Draw a line towards the top-left to the start of our corner radius,
 *    use the top-left as the curve control point,
 *    and curve to the other end of our corner radius
 * - Draw a line to the left edge of our cutout
 * - Draw an elliptical arc with an equal x and y radius to create a circle,
 *     have 0 rotation on the x-axis,
 *     use the smaller arc (we could use either as they are equal),
 *     sweep the arc in a counter-clockwise direction,
 *     complete the arc on the right cutout point
 * - Draw a line towards the top-right to the start of our corner radius,
 *    use the top-right as the curve control point,
 *    and curve to the other end of our corner radius
 * - Draw a line to bottom-right
 * - Close the path
 */
const d = `
M0,${HEIGHT}
L0,${CORNER_RADIUS} Q0,0 ${CORNER_RADIUS},0
L${CUTOUT_LEFT_X},0
A${CUTOUT_RADIUS},${CUTOUT_RADIUS} 0 0 0 ${CUTOUT_RIGHT_X},0
L${WIDTH - CORNER_RADIUS},0 Q${WIDTH},0 ${WIDTH},${CORNER_RADIUS}
L${WIDTH},${HEIGHT}
Z
`

function Shape() {
  return (
    <svg width={WIDTH} height={HEIGHT}>
      <path d={d} />
    </svg>
  )
}

We start by defining a CUTOUT_RADIUS, we can increase or decrease this value to make the cutout larger or smaller. Next, we derive a few useful values, namely the x position for the left and right side of the cutout. Then we draw an "arc".

That's what the A is for, an "elliptical arc". This command takes a lot of values, but because we're making a semi-circle, we're able to simplify a few of them. The first value is the x-radius and y-radius of our ellipse. One way to think of a circle is as an ellipse whose focii are both in the center, meaning both radii are equal. That's what A${CUTOUT_RADIUS},${CUTOUT_RADIUS} represents.

The next value determines the rotation of the shape on the x axis. Since there is no rotation, the value is 0.

Next, we have the "large-arc-flag", essentially a boolean to determine if we want the larger or shorter of the two arcs produced by an ellipse. In our case they are equal, so we could use either 1 or 0.

The next value is the "sweep-flag", meaning should we draw our arc in a clockwise (1) or counter-clockwise (0) direction. Since we're going from the CUTOUT_LEFT_X down and to the right, we use 0 for our value.

Lastly, we identify the point the arc should complete at, ${CUTOUT_RIGHT_X},0 and we've completed our arc. It looks like this:

From here, all we need to do is absolutely position this in the correct spot in our UI and build our buttons and tabs on top of it. If we need to make tweaks later, all we need to do is update some of the variables.

Summary

We don't always need a library to draw SVG in an understandable way. It just takes a little bit of effort to understand the available commands.

Using variables to control aspects of our SVG allow us to tweak and modify our shape in a way that we know will always work. We could even hook these values into inputs and sliders to adjust them as we see fit.

I hope you feel less intimidated about SVG now that you've seen how to draw some of it by hand and inspired to try and use this technique in some of your own work.

Tailwind “Minimum Full Height” Layout

Sat, 30 Mar 2024 18:23:51 GMT

import { Example } from './_components.tsx'

I've been using Tailwind CSS on a lot of projects lately. Almost all my layouts for these projects are some version of the "minimum full height" layout, and I wanted to quickly show you how I do that with Tailwind.

The keys are:

html must be height: 100%
body must be min-height: 100%
body must be a Flex column container
main (or whatever element you choose) is flex-grow: 1

Here are the important pieces of the markup you're looking for:

<html class="h-full">
  <body class="flex min-h-full flex-col">
    <header></header>
    <main class="grow"></main>
    <footer></footer>
  </body>
</html>

Percentage based heights only work if their parent element is a fixed height. In this case, since the topmost parent is set to the full height of the browser window, we can then also use a percentage based height on its direct child, the body element.

Because we want our body element to be able to extend beyond the full height of the browser when it has that much content, we only use min-h-full on it.

Next, by setting body as a Flex column layout, we can use the flex-grow property on one of its children to tell the layout engine, "expand this element to any remaining available space". In this case, that's the main element.

Thus, with this markup, our header and footer will take up the amount of space they require, and the main element will take up the rest to the full height of the browser if there is too little content to fill the space, and beyond if there is more than enough content.

Here's a small example: <Marker content="A fixed height is used on the outermost <code>div</code> to make it seem like a browser window. A <code>gap</code> is used on the <code>div</code> representing the <code>body</code> element just for visibility." />

And that's it. From there I encourage you to figure out the "holy grail" layout to further develop your skills and understanding.

Update - 2024-04-03

Multiple people on Twitter pointed out that it might be better to use h-dvh instead of h-full on the html element, and they're correct. In some cases, most likely ones involving mobile browsers, it might be better to use h-dvh.

For those unfamiliar like I was, dvh stands for "dynamic viewport height". I found this solid dev.to article breaking down the various units, so I don't have to.

On mobile screens, h-dvh will track the full height and adjust if any other UI obstructs the viewport, such as the native navigation and such. So anything pinned to the bottom like our footer is, will track along with the viewport resizing as those bits of UI change.

So give h-dvh a try if you find h-full doesn't do the trick.

Make Checkpoint

Fri, 29 Mar 2024 16:01:20 GMT

When I'm working on production code, I tend to be really good about making atomic commits in git. I'm a big fan of using patch commits, git commit -p, to be really precise about what I am adding in that commit.

But when I'm prototyping or working on a new side project, throw that all out the window!

I'm really bad about it on a side project. I can't tell you how many times I've written entire projects without making a single commit. It's truly laughable. I have to do better, and luckily, it's easy to do so.

I originally learned this tip from Brandon Dail on Twitter. The tip is to use a Makefile to create a script that generates a "checkpoint", a git commit with a timestamp.

We'll add a new file to our project named Makefile, and then add the following to it:

checkpoint:
	@git add -A
	@git commit -m "checkpoint at $$(date '+%Y-%m-%dT%H:%M:%S%z')"
	@git push
	@echo Checkpoint created and pushed to remote

Now, in the terminal, I can run the command make checkpoint <Marker content="If you know you will never add another script, you can remove the name <code>checkpoint:</code> from the <code>Makefile</code> and then simplify the command to <code>make</code> in the terminal. It will treat the instructions as the default command and run them." /> and it does the following:

Stages all the files to be committed
Commits them with a message of "checkpoint at <timestamp>"
Pushes the branch
Logs out that the work is done

It's that simple.

Now when I'm jamming on a new idea, I don't have to worry about my poor committing habits, I can just make checkpoints, which is way better than nothing.

So if you're like me and really lazy about git while hacking on something, consider adding this to your next project. Might help you out a little bit.

Agathist VSCode Themes

Sat, 16 Mar 2024 16:55:07 GMT

import Image from '../../../components/Image.astro'

About a week ago I started messing around with creating a VSCode theme inspired by Agathist's brand colors using using themer.dev. I kept tweaking and tweaking until I had something that, as the kids say, kind of slaps.

Because I genuinely enjoyed how the theme was working for me, I thought it would be a neat idea to turn it into a VSCode extension and use it to get the word out about Agathist.

"Agathist Themes" is available for VSCode today. You can find it by searching for "Agathist Themes" either in the Extensions tab or the VSCode Marketplace.

Currently, only "Agathist Dark" is available, but I have plans to make other themes soon, starting with a light theme.

I love it! 😍 What can I do with my feelings?

You can give it a review and a bunch of stars on the VSCode Marketplace. Or you can give the Github repo a star. You can also tell other people about the theme, or send me a kind word on social media.

I hate <bothersome thing>! 😤 What can I do with my feelings?

Themes will continue to get tweaks and updates as issues naturally arise, but you're also welcome to submit an official issue to the repo, which can be found at https://github.com/agathist/vscode-themes. I'd love it if you shared an image and all the data I need to reproduce the issues when you do.

What's next?

As mentioned before, a light theme will be whipped up eventually. I like using light themes when I'm coding outside in the sun and the good weather is coming quickly.

Two Types of Composition

Tue, 12 Mar 2024 15:23:44 GMT

import { Button } from '../../../components/Button.tsx' import Hr from '../../../components/Hr.astro' import ClassClash from './_ClassClash.astro'

Author's note: I am writing this post so that I can reference it in the near future (famous last words, I know). If it seems odd and from out of nowhere, it's because it lives in a greater context in my head. One that I haven't put into words writing yet. Thank you for your patience in advance.

-Kyle

<Hr />

I've been thinking about composition for a long time. I use the word a lot, but I'm often met with confused faces when I do. I could be wrong, but I feel like "composition" in programming is one of those words that many people sort of understand but would really struggle to clearly define. That's ok. I'm not calling anyone out.

You hear over and over, "Prefer composition over inheritance!", but no one really breaks down what composition is. Let's fix that.

First, "composition" is the act of combining and recombining existing "elements" <Marker content={"Elements" here is used in the abstract, not in the sense of HTML elements.} /> to create new ones. It's like combining atoms to make molecules, except without needing a laboratory or a chemistry degree.

Second, in my opinion, there are two different "types" of composition: function composition and object composition, but I think it might be more useful to think of these as nesting composition and merging composition. I think learning to recognize these two types of composition is beneficial.

Function (nesting) composition

I've written about function composition before, so I won't go into great detail. Suffice it to say, this is when we nest functions together, such that the result from one becomes the input to another. We make new functions by combining and recombining other functions in different orders to achieve new results. For example:

const repeat = str => str + ' ' + str
const exclaim = str => str + '!'
const shout = str => str.toUpperCase()

const result = shout(repeat(exclaim('composition over inheritance')))

However, if we use our imaginations a bit, we can see that this very same thing happens in other contexts that we would not normally think of as functions. Such as with CSS and HTML.

For the last few years, I've worked on applications where the only layout mechanism available was Flexbox. <Marker content="Yup. This is what you have to do to make components that work on web and React Native since RN only supports Flexbox." /> Therefore, I had to use nesting compositions to create various layouts I wanted to achieve.

For example, if I have a Flexbox column, all of it's child elements are set to align-items: stretch by default. The stretch value means that each child is stretched on the cross-axis, and thus takes up the full width of the parent container.

<div class="flex flex-col gap-4">
  <p class="border">
    Here is a paragraph with a border to show that it stretches the full width.
  </p>
  <p class="border">
    Notice that the button below stretches the full width of the parent
    container as well.
  </p>
  <button>Click me</button>
</div>

<div class="bg-gray-100 p-4 font-sans dark:bg-gray-800"> <div class="flex flex-col gap-4"> <div class="border border-gray-500"> Here is a paragraph with a border to show that it stretches the full width. </div> <div class="border border-gray-500"> Notice that the button below stretches the full width of the parent container as well. </div> <Button>Click me</Button> </div> </div>

But let's say I want the button only to take up the space of its text (and only the button should do this, the paragraph should remain the same), as if it was display: inline-block?

Rather than try and add ad hoc CSS to this particular button (the go-to move for so many developers in my experience), or modifying the parent in some way, what if we just alter the composition?

Let's wrap our button in a flex row container instead:

<div class="flex flex-col gap-4">
  <p class="border">
    Here is a paragraph with a border to show that it stretches the full width.
  </p>
  <p class="border">
    Notice that the button below now only takes up the space of its minimum
    content width.
  </p>
  <div class="flex">
    <button>Click me</button>
  </div>
</div>

<div class="bg-gray-100 p-4 font-sans dark:bg-gray-800"> <div class="flex flex-col gap-4"> <div class="border border-gray-500"> Here is a paragraph with a border to show that it stretches the full width. </div> <div class="border border-gray-500"> Notice that the button below now only takes up the space of its minimum content width. </div> <div class="flex"> <Button>Click me</Button> </div> </div> </div>

Through nested composition, we've changed the appearance of our UI. In this case, a flex row container shrinks its children to their minimum content width by default, and thus we achieve the button look we're going for.

Our HTML elements (with the proper CSS) behave sort of like functions in that they take their children as inputs and modify their output. If we were working within a system like React, where components are functions, we really would be doing function composition:

function MyComponent({ children }) {
  return (
    <Stack gap={4}>
      <Text>{children}</Text>
      <Row>
        <Button>Click me</Button>
      </Row>
    </Stack>
  )
}

Object (merging) composition

Objects can be merged together to form new objects, primarily with the ... spread operator. Some common places this technique is used are extending configuration objects, or updating state objects.

import baseConfig from 'something'

export const myConfig = {
  ...baseConfig,
  someProperty: {
    foo: 'bar',
  },
}

function reducer(state, action) {
  switch (action.type) {
    case 'TOGGLE_OPEN': {
      return {
        ...state,
        isOpen: !state.isOpen,
      }
    }

    default:
      return state
  }
}

Object composition differs from function composition in a couple ways:

For the most part, the objects are merged at a single level. Yes, we can merge at a deeper level in the object, but it has no impact on any of the higher levels of the object.
Merging is a destructive act. When one object is merged into another, any key in the second object that matches a key in the first object replaces the first property's value with the second object's value.

Another way that you may have used this form of composition is with style objects:

const primaryButtonStyles = {
  backgroundColor: 'blue',
  color: 'white',
  padding: '1em',
}

const dangerButtonStyles = {
  ...primaryButtonStyles,
  backgroundColor: 'red',
}

console.log(dangerButtonStyles)
// { backgroundColor: 'red', color: 'white', padding: '1em'}

Taking this a step further, we might be able to think of CSS class composition as object (merging) composition. Consider these classes:

.primary {
  background-color:;
}

.danger {
  background-color: red;
}

If we were to (accidentally) apply both of these styles to an element, the order of our classes would have an impact on the element's appearance, but maybe not in the way you expect.

<div class="primary danger">I will be red</div>
<div class="danger primary">I will also be red, lol</div>

This occurs because of where our object composition is really occurring. Because our .danger class comes after our .primary class in our stylesheet, the latter class' values replace the values of the former class when there are matching keys.

We always have to be aware of how merging composition may have unintended consequences!

Why does any of this matter?

The main reason I find this important has to do with how easy it is for someone to understand one form of composition versus the other.

I have found that people find object/merging composition far easier to understand, even though it often has more pitfalls. It often provides developers with more "escape hatches" and ways to "throw stuff at the wall until it sticks". In other words, there's often more than one way to achieve the desired result, at the tradeoff of potentially making a destructive mess in the process.

On the other hand, function/nesting composition is often superior in terms of strictness of inputs and outputs, but is more difficult for developers to intuit. There's less room for trying things to see if it works by design.

Be honest with yourself. How well do you know CSS? Do you know precisely what you're doing, or do you need to be able to throw stuff at the wall? There's no shame in the answer, I promised, but you might be able to guess what my future post will be about based on how you respond.

Consider our simple example above with the Button. It's so much easier for devs to throw more classes at the CSS, or use the style prop, rather than recognize, "If I wrap this Button in a Row, it will achieve the result I'm looking for!" I know devs can get there. I've trained them to do it and seen it happen, but it's not intuitive for many of them.

Summary

You might not find it useful to think of composition in these two ways, but I do, and I hope it helps you in some small way.

Here's a quick break down of what I've discussed:

Composition is combining existing elements to create new ones
Nesting composition uses wrapping elements to modify functionality
- Parents change the functionality of child elements
Merging composition smashes elements together destructively to achieve new ones
- The order of the smashing is important

Agathist Q&A

Tue, 05 Mar 2024 16:35:56 GMT

You might have noticed a few new "ads" around here recently for something called Agathist. Let me tell you what that's all about in a (hopefully) fun self-directed Q&A.

What is Agathist?

Agathist is the software development firm I started this year. I want to take my talents and use them more broadly, working with multiple clients on a variety of projects, to build good software with good people.

Why the name Agathist?

The word "agathist" is derived from the Greek word agathos, which means "the good". Therefore, an agathist is one who believes in goodness, but unlike an optimist who tries to see the upside of bad situations, an agathist acknowledges reality and does the work to make it better.

When did you come up with the idea to start Agathist?

I first conceived of Agathist in 2017. I bought the domain agath.ist because I thought the name was perfect for a company. It rolls off the tongue. It doesn't hurt that the top level domain for Istanbul is .ist. That was the icing on the cake.

I even made a placeholder page for it back then, as if I was starting an agency. Up to that point in my career, I had only worked at agencies, so it was what I knew. But I never did anything with the site other than renew the domain each year.

I didn't start seriously considering starting a software development firm as a career option until last fall. In November, I had a revelation regarding work and realized that it was extremely unlikely for me to find a Goldilocks job where I could thrive, working with my neurodivergence and not against it. The only way I could do that would be to take a chance on myself and start my own company.

Perhaps someday I will write about all the things I realized about being neurodivergent in the workplace, but for now I'll make it very simple. When I consider all of my possible employment options going forward, working for myself and building a team of my own is the only one that gives me the opportunity to be happy.

What are your goals for Agathist?

It's impossible to know all the goals I should have right now, but here are a few: <Marker content="I hope it will be fun to revisit these someday." />

Land our first client
Stay afloat for the year
Succeed enough to hire our first employee
Grow enough to have a small team

I also want to mention, while not strictly a goal, one of the reasons I want to start Agathist is to be in a position to help my friends out. With all the layoffs, there's a lot of talent in our industry just going to waste right now. There's no shortage of projects that need to be done. I think there's an opportunity to find those projects and put together a team to do them.

Basically, if you've trusted me all these years for my writing and what I share around the Internet, I want you to trust me to take on a project that's important to you, to be able to use my network to gather up some talented folks and knock it out of the park.

What do you hope to get out of Agathist?

A living that doesn't kill me.

That might sound hyperbolic, but it's so difficult to work under the power structures of companies when you're neurodivergent. The masking, the lack of autonomy, and the workplace politics are all extra challenges wasting useful energy. <Marker content="Yes, these things can be difficult for anyone, but they are especially challenging for neurodivergent people." /> There's a reason why people with neurodivergence experience far higher rates of burnout.

By taking ownership, I can at least flip some of those structures in my favor and put more of my energy where I want it to go. While it might not be the most financially sensible move, <Marker content="It might be a great move, too. Time will tell." /> it does give me the best opportunity to create structures that work for me rather than against me.

I also hope to get back to learning and growing. My last job was a poor fit in this regard. It was a quagmire. I spent all of my energy pouring into others, trying to build up their skills so we could move forward. No one was pouring into me and there were no opportunities for growth. I became stuck as well. Starting Agathist is part of my journey to getting out of that muck.

For right now, I'm specifically excited to ramp up on some of the new trends in web development, like React Server Components. I'm also excited about the opportunity to spend more time doing fullstack work for clients, becoming more skilled with Postgres, SQL and other backend skills.

In addition, I suspect that as Agathist grows, my role within it will change, too. I will have opportunities to learn and grow more into the leader I want to be. I can't say it enough, I'm excited about the future.

What kind of projects are you looking for?

I'm open to a lot of ideas! My career has allowed me to work on so many different things, such that I genuinely believe I could help out on any web (or React Native) project in so many ways. Here are a few ways I'm focusing on right now:

Fullstack applications

I'd love to land some bigger applications with some bigger companies. <Marker content="Who wouldn't, right?!" /> Projects with some real meat to them. I actually love working on product in the early stages, where there's lots of work to get done and you can really just put your head down and go. Let us take your idea and build version 1.0. Get you rolling.

Codebase improvement

I'm thinking of this as "Refactor as a Service". Every place I've ever worked has needed lots of love. I'm skilled at revitalizing legacy code and making it pleasurable to work in. I'd be happy to bring that to a project.

In addition, I've been approached a couple times now to do "Revamp as a Service", too. If you have an older website that just needs to be ported to something more modern, let us do that. We can set you up on a modern stack you're happy with, with a better developer experience, and get you back on the happy path.

Design systems

I've spent the last 10 years working in React and the last 2 years building a design system that supports both React and React Native. In other words, I know a thing or two about building really great component systems.

If you're team has been looking to build one of these but doesn't know how, or just needs help getting started, I'd love to help.

Is anyone else on the team with you?

Yes! Right now one of my best friends is working with me. <Marker content="I am so excited!" /> This way we'll have enough hands and minds to take on some bigger projects. I'll add subcontractors as necessary this year and hopefully be in a position to hire some as full-time employees when the time comes.

What are Agathist's rates?

Good question! The truth is you can't have one rate for all clients. You need to optimize your rate for value. Bigger companies, bigger projects that bring in bigger revenues, they're worth more value to the client, and thus the rate should be higher to match that value.

That said, I'm a very transparent person, <Marker content="A trait that is <em>also</em> related to my neurodivergence. Yay, oversharing!" /> I'm starting my bids at $125/hour and shooting for no more than 40 hours per week split between my colleague and me. I want to keep our workload very reasonable and give myself ample time to pursue new clients and grow the business. I can't do that if I'm full-time coding.

I suspect our rates will go up a bit as we obtain clients, so if you're reading this in the future, don't be surprised if they're higher. Please keep in mind, rates aren't only for making money, they are a tool for managing workload and that's really important to me.

Lastly, I have no interest in gouging people. I'm not really wired to treat money as king. I'm wired to do things well and to do things right. I want to take on projects that interest me (and my team) and make business sense for both the client and us. That won't always mean going with the company that can pay the most!

How can I get in touch with Agathist about a project?

I'm not shy, I'll talk to you about it however you want!

That said, you can fill out the form on the contact page. That's probably the best way to do it!

If forms aren't your style, you can also send me an email at kyle@agath.ist. I'd be happy to discuss it there.

Lastly, if you're really adventurous, you can click the Agathist ads you see around here, too. That will lead you in the right direction.

How can I help Agathist be successful?

I think the simplest thing you can do is think of us when an opportunity presents itself. You meet someone looking for a team to help them with a project? Let them know about Agathist.

Have a project at work you really want to see happen but don't have the headcount for? Consider Agathist.

Our main hurdle right now is landing those first clients. Once the ball is rolling, we'll have new, exciting challenges to deal with.

Other ways you can help us out include:

Sharing this post
Sharing the Agathist website
Writing a testimonial if we've worked together

There are probably even more ways I'm not thinking of right now. Be creative!

How are you going to conclude this Q&A?

By saying thank you. Thank you to the people who believe that I can do this. Thank you to the mentors helping me learn some lessons the easy way, rather than the hard way. And thank you to the network of wonderful people I have that makes this a possibility. I appreciate each and every one of you.

No Outer `margin`

Mon, 26 Feb 2024 16:13:32 GMT

Building reusable components can be challenging to do well, and there are some anti-patterns that are easy to fall into that can make it even more difficult.

One of the most common antipatterns I see is having margin (and in some cases padding) on the outermost element of a component. This is an easy mistake to make, but luckily, it's easily avoided once we know what we're looking for.

What are "outer" `margin`s and `padding`s?

I define "outer" here as margins that extend beyond the border-box of the UI. Generally speaking, this would be applying margin to the outermost element of a component.

function Card({ children }) {
  return (
    // WARNING: Don't do this! It is an outer `margin`!
    <div style={{ marginBottom: '1rem' }}>{children}</div>
  )
}

function EmployeeCard({ name, occupation }) {
  return (
    <Card>
      {/**
       * This is fine! We can use internal margins for layout,
       * but there are better ways we'll learn later!
       */}
      <div style={{ marginBottom: '1rem' }}>{name}</div>
      <div>{occupation}</div>
    </Card>
  )
}

In addition to never using outer margin, we should never use padding for the same purpose. The outermost element of a component should not have padding unless that element has a border or a background-color.

function Card({ children }) {
  return (
    // WARNING! Don't do this! It is an outer `padding`!
    // Without a border or background color, it has
    // the same appearance/effect as a `margin`
    <div style={{ paddingBottom: '1rem' }}>{children}</div>
  )
}

function BorderCard({ children }) {
  return (
    <div
      style={{
        border: '1px solid tomato',
        backgroundColor: 'gray',
        // This padding is ok because we have styles that extend to the
        // border-box of our component, thus defining a boundary for
        // this UI!
        padding: '1rem',
      }}
    >
      {children}
    </div>
  )
}

What's the big deal? Why is this a problem/anti-pattern?

The problem with outer margins and paddings like the examples above is that it breaks encapsulation. I've written about encapsulation before, but never in terms of UI. Essentially, styles like these have an impact on the other components around it. Components with outer margins get their elbows out, NBA Jam style, knocking around adjacent components.

The impact of these styles often lead to what I call "compensations", essentially workarounds to undo what we've already done. We'll see some examples of this soon.

Not only do outer margins require compensations, they give the underlying component too many responsibilities. External spacing should never be the responsibility of a component. Components should only ever be concerned with internal spacing.

An abstract example

Let's say I have a reusable component called Item that looks like this:

function Item() {
  return <div className="rounded bg-accent p-8" />
}

Imagine Item is any reusable UI. Perhaps it's an InfoCard or a ListRow in a list. It doesn't really matter what the specifics of Item are, we only need to know that it's a single unit of UI for our purposes.

Let's say I have many Items next to each other. Let's give them different background colors so it's clear which one is which:

Now that I have many Items, it's necessary to space them away from each other. It might be very tempting to add a margin-bottom to each one, like so:

function Item() {
  // Notice the `mb-4` class
  return <div className="mb-4 rounded bg-accent p-8" />
}

That looks fine, but we need to look at it with more scrutiny. What if we add a border around the wrapping element? What are we going to see?

Oof! We have an extra margin at the bottom.

It's at this point less experienced devs start making all sorts of "compensations" to handle this situation. If it's a dynamically rendered list of Items, we might be tempted to use an index in our loop and somehow remove the margin-bottom on the last one. <Marker content="Or even apply a wrapping element with a negative <code>margin</code>. Gross." /> We might even go so far as to add the dreaded marginBottom={false} prop, a bad case of Yet Another Prop syndrome if I've ever seen one. <Marker content="Seriously, these kinds of props make me want to 🤮" />

// Don't do this. You'll make me cry.
function Item({ marginBottom = true }) {
  const mb = marginBottom ? 'mb-4' : ''
  return <div className={`rounded bg-accent p-8 ${mb}`} />
}

But what about other scenarios? What are you going to do if you have to put your Items into a Row:

Or a Grid?

Are you going to make boolean props for all the margins? I sure hope not!

A concrete example

One of the most common ways I see this is with headings. Let's say I have a component for H2s in my codebase:

function H2({ children }) {
  return <h2 className="mb-4 text-xl font-bold">{children}</h2>
}

That looks like this:

<div class="my-4 bg-gray-100 px-4 py-2 dark:bg-gray-800"> <h2 className="mb-4 text-xl font-bold"> Using the <code>h2</code>. Notice the space below. </h2> </div>

This might seem like a good idea. Headings tend to be found in large blocks of text and doesn't the user agent stylesheet give h1 through h6 a margin-bottom by default anyways?

Sure, but the web isn't simply long-form text anymore. It's componentized and we need to be able to use our elements in more scenarios than just long-form text.

What if we want to add additional data around it? Perhaps we need to put a subtitle right below it, or a date, or timestamp?

<div class="my-4 bg-gray-100 px-4 py-2 dark:bg-gray-800"> <h2 className="mb-4 text-xl font-bold"> Using the <code>h2</code> </h2> <div class="font-sans text-lg">Uh oh. I'm spaced really far away!</div> </div>

Now you're back-pedaling to either undo the mb-4 class or compensate for it some other way. Better to leave it off entirely and do the proper solution, which we'll discuss next.

The solution

The solution to this problem is simple, use parent elements or components for layout and spacing.

As I said before, it is never the responsibility of a component to manage its external spacing, only its internal spacing. We can always use a parent element or component to manage the layout of adjacent components.

Regardless of what layout solution you use, whether it's with components with something like Chakra UI or classes like Tailwind, I find the best solutions heavily use Flex or Grid containers with gap to apply spacing. Let's do that here with our Items:

After removing the mb-4 class from our Item, we can now wrap our items in another element to do the spacing. For example, our Stack looks like this:

Our Row looks like this:

And our Grid looks like this:

No matter where we need to put our Item, we know we can control how it's laid out in our UI. We've fixed its encapsulation problem and made it more reusable.

Summary

No margin on the outermost element
No padding on the outermost element unless it has a border or background-color to visually define the border-box boundary of the UI
Use parent elements or components to do layout instead

Type `TODO`

Tue, 23 Jan 2024 03:47:59 GMT

import SocialPost from '../../../components/SocialPost.astro'

With tongue firmly in cheek, I tweeted the following:

The response the post received was a lot larger than I was expecting, so I thought I'd take a moment to explain why this is both a tip and a joke at the same time.

Tip: Sometimes `any` is ok

If you've written TypeScript for long enough, then I am willing to bet any has come to your rescue a time or two.

Any app of reasonable complexity, especially a codebase that has some age, perhaps still has some JavaScript, will likely have nasty parts that are difficult to type correctly.

Add to this any time pressure or consideration between value created versus the time it's taking to do so, and you'll find yourself in a situation where it is just not worth it to solve that hairy type problem right now. That's where the TODO type comes in handy.

type TODO = any

The scenario that prompted me to write the tweet was converting a JavaScript file to TypeScript. I had a value I couldn't get the types right for in the first few minutes. It was a file that was already JavaScript, and thus inherently not type-safe, and it was a file that hadn't been modified in years. Given these factors, using an any was appropriate. Making it a TODO provides some signal that perhaps a time may come where it can be updated and improved.

Don't forget, you don't have to name it TODO either. You can name it something more specific. Perhaps you prefix a typename with UNSAFE_ or something similar to signal that you've opted out of type safety.

Joke: You shouldn't use `TODO` excessively

While there are appropriate times to use the TODO type, it definitely should not be abused. If many parts, or particularly important parts, are littered with TODO or any types, then you may want to consider if it's possible to devote more time to getting the types correct.

We want to use any or TODO purposefully, as the very rare escape hatch and a signal that the following code is unsafe. Don't just use them to hide something under the proverbial rug, use them to make it clear that something requires further attention when possible.

Bonus tip

I use a VSCode extension, TODO Highlight, that highlights keywords in your editor. With a few tweaks to the settings, the extension will highlight every use of TODO in your app. That way, you never visually miss where you have them.

Summary

Recognize any or TODO can be useful in a pinch, especially when considering the time/value tradeoff. Do treat them like a real TODO and try and fix them when you have time. Use either type sparingly.

Lastly, keep improving your TypeScript skills and you'll find you reach for these types less often.

Wrangling Tuple Types

Sun, 21 Jan 2024 00:00:00 GMT

This is going to be a short and simple TypeScript tip for you about tuples.

At the time of this writing, JavaScript and TypeScript do not officially have a tuple type. That TC39 proposal is still in the works. The best you can do is a fixed-length array.

So let's say we have a function that returns a tuple, like a custom hook:

function useBool(initialValue = false) {
  const [state, setState] = React.useState(initialValue)

  const handlers = React.useMemo(
    () => ({
      on: () => setState(true),
      off: () => setState(false),
      toggle: () => setState(s => !s),
      reset: () => setState(initialValue),
    }),
    [initialValue],
  )

  return [state, handlers]
}

const result = useBool()

Returning a tuple is a nice API because it allows the consumer of the result to array destructure the values into custom names whenever it's used. It's a bit nicer doing:

const [isOpen, setIsOpen] = useBool()

Than it is to do the object equivalent:

const { state: isOpen, handlers: setIsOpen } = useBool()

That said, what do you think the return type is for our useBool function? The answer might surprise you. result's type is:

const result: (
  | boolean
  | {
      on: () => void
      off: () => void
      toggle: () => void
      reset: () => void
    }
)[]

The return type is a non-fixed-length heterogenous array of the union of boolean and the shape of our handlers object. Basically, TypeScript doesn't know the index of our values in the array. We will run into a lot of annoying type issues if we try and use this in a component.

function Secret({ message }: { message: string }) {
  const [isOpen, setIsOpen] = useBool()

  return (
    <div>
      {/**
       * TS will error here, saying you can't call
       * a method on a boolean
       */}
      <button type="button" onClick={setIsOpen.toggle}>
        {/**
         * TS won't yell at you because anything can be truthy
         * or falsy, but it won't know that `isOpen` is strictly
         * a boolean
         */}
        {isOpen ? 'Hide' : 'Reveal'}
      </button>

      {isOpen && <div>{message}</div>}
    </div>
  )
}

The first error that pops out is setIsOpen.toggle might not be a function because it might be a boolean. If you continue to examine isOpen closer, you'll also find it's not typed as a boolean, but rather as the union. You can take a look for yourself in this TypeScript Playground.

You and I know that useBool returns a tuple, how do we convince TypeScript of that fact?

The way I used to do it

I advise others to avoid defining function return types whenever possible to allow TypeScript inference to do its thing. There's really no need to be overly prescriptive. Type the inputs, let TS handle the outputs.

Except in the case of tuples.

As we've seen, TypeScript thinks the return type is an array and this is understandable because we don't have real tuples. So taking our useBool function, we could add a return type to it.

function useBool(initialValue = false): [
  boolean,
  {
    on: () => void
    off: () => void
    toggle: () => void
    reset: () => void
  },
] {
  const [state, setState] = React.useState(initialValue)

  const handlers = React.useMemo(
    () => ({
      on: () => setState(true),
      off: () => setState(false),
      toggle: () => setState(s => !s),
      reset: () => setState(initialValue),
    }),
    [initialValue],
  )

  return [state, handlers]
}

Now, TypeScript knows that we intend to return a fixed length array and forces us to conform to it. The type checker correctly types state and handlers throughout our code.

But our solution is a bit verbose and brittle. If we ever make a change to our hook's API, we'll have to manually update the types. Is there a more elegant way? Yes.

Why didn't I think of this sooner?

A simpler answer to our problem is to add as const after our returned tuple, like so:

function useBool(initialValue = false) {
  const [state, setState] = React.useState(initialValue)

  const handlers = React.useMemo(
    () => ({
      on: () => setState(true),
      off: () => setState(false),
      toggle: () => setState(s => !s),
      reset: () => setState(initialValue),
    }),
    [initialValue],
  )

  return [state, handlers] as const
}

This tells TypeScript that the return value of useBool is a readonly array. It will never be modified. Because it's readonly, TypeScript correctly types state and handlers anywhere they are used.

It's a dead simple change, and only recently did it occur to me to do it this way. I should have been doing it this way for years. But hopefully I saved you a little trouble learning it the hard way.

Summary

Unless you tell TypeScript otherwise, it will assume that you're returning an array, not a tuple, from a function. You can either explicitly define a return type, or use as const on the return value to inform TypeScript of the correct types.

UI Composition

Tue, 03 Oct 2023 00:00:00 GMT

import { Card } from './_components'

I frequently come across components with either egregious conditionals, bizarre CSS, or both, to solve problems that can be easily solved with composition. It just takes some practice to recognize what responsibilities a particular part of a component should have, and how to properly separate and apply those responsibilities. Let's make an example.

Let's say you have a Card component. A Card should have a border and the content inside should be padded from this border. Let's also give it a box-shadow for some fun. It'll look like this:

<div class="my-8"> <div class="flex justify-center"> <Card> <div class="flex flex-col gap-4"> <h3 class="font-sans text-xl">This is a Card</h3> <p>This is the Card's content. Notice it is padded from the border.</p> </div> </Card> </div> </div>

Cool, looks great! But soon you learn that the design team wants to be able to have "sections" in the Card, divided by what is essentially an hr tag. What happens if we do that without making any changes?

<div class="my-8"> <div class="flex justify-center"> <Card> <div class="flex flex-col gap-4"> <h3 class="font-sans text-xl">This is Section 1</h3> <p>This is the content of Section 1. Isn't it great?!</p> </div> <hr class="h-[2px] bg-gray-300" /> <div> <h3 class="font-sans text-xl">This is Section 2</h3> <p class="mt-4"> This is the content of Section 2. Isn't it <em>also</em> great?! </p> </div> </Card> </div> </div>

That's probably not what we want. We want the divider to be able to go the full width of the card, and we want each section to be padded the same. We could try and do some hacky CSS. If I were working in a codebase with this component, I would not be shocked to see something like:

.card hr {
  /* This matches the vertical padding of the wrap */
  margin-top: 1rem;
  margin-bottom: 1rem;
  /* negative margin moves the `hr` to the left side of the box */
  margin-left: -1rem;
  /* 2rem accounts for left and right padding */
  width: calc(100% + 2rem);
}

This might work, but it's not the most robust solution we can come up with. Rather than write some hacky CSS, we need to take a step back in order to make forward progress again. Composition is going to help us do that.

You see, it might not be obvious, but Card has too many responsibilities. Just like classes, objects and functions can do too much, so can elements with their styling.

When we look closely, we can see Card is doing two separate jobs. First, it's wrapping all of the children in a border and box shadow. Second, it's applying a padding between that wrapping border and the children. In order to solve our problem, we need to separate these responsibilities into multiple components.

Let's break Card into a compound component, with Wrap, Section, and Divider components.

Card.Wrap = function Wrap({ children }) {
  return (
    <div className="rounded border-2 border-gray-300 shadow-[8px_8px] shadow-accent">
      {children}
    </div>
  )
}

Card.Section = function Section({ children }) {
  return <div class="p-4">{children}</div>
}

Card.Divider = function Divider() {
  return <hr class="border-t-2 border-t-gray-300" />
}

Now we can compose our pieces together correctly.

<Card.Wrap>
  <Card.Section>
    <Stack gap={1}>
      <h3>This is Section 1</h3>
      <p>This is the content for Section 1</p>
    </Stack>
  </Card.Section>

  <Card.Divider />

  <Card.Section>
    <p>
      This is an entirely different section. Notice the padding works correctly!
    </p>
  </Card.Section>
</Card.Wrap>

<div class="my-8"> <div class="flex justify-center"> <Card.Wrap> <Card.Section> <div class="flex flex-col gap-4"> <h3 class="font-sans text-xl">This is Section 1</h3> <p>This is the content for Section 1</p> </div> </Card.Section> <Card.Divider /> <Card.Section> <p> This is an entirely different section. Notice the padding and divider work correctly! </p> </Card.Section> </Card.Wrap> </div> </div>

This right here, the act of recognizing Card was overloaded with responsibilities and breaking them apart, is the work of building component-based design systems. This is how we make these components robust and flexible.

We can take two steps to make this a bit better. Let's make the original Card component a sane default composition of the compound components:

function Card({ children }) {
  return (
    <Card.Wrap>
      <Card.Section>{children}</Card.Section>
    </Card.Wrap>
  )
}

This way, when someone needs the simplest Card, they can just use it.

The second way we can improve this is to make it an error to use Card.Section or Card.Divider outside of Card.Wrap using a Context.

// Setting the default to false will let us trigger our Error if necessary
const CardContext = React.useContext(false)

const useCardContext = () => {
  const context = React.useContext(CardContext)

  // We'll set context to true in our Provider, which will avoid this condition
  // We don't even need to return anything from this hook because we're not
  // using the context value anyways.
  if (!context) {
    throw new Error(
      'You may only use Card compound components inside of a `Card.Wrap` component',
    )
  }
}

Card.Wrap = function Wrap({ children }) {
  return (
    // By setting the value to true, we enable our
    // compound components to work safely
    <CardContext.Provider value={true}>
      <div
        style={{
          border: '2px solid var(--colors-offsetMore)',
          borderRadius: 4,
          boxShadow: '8px 8px var(--colors-accent)',
        }}
      >
        {children}
      </div>
    </CardContext.Provider>
  )
}

Card.Section = function Section({ children }) {
  useCardContext()

  return <div style={{ padding: '1rem' }}>{children}</div>
}

Card.Divider = function Divider() {
  useCardContext()

  return <hr />
}

We can take this a step even further and prevent nesting Sections or passing a Divider into a Section, by adding another layer of our context provider in there.

Card.Section = function Section({ children }) {
  useCardContext()

  return (
    <CardContext.Provider value={false}>
      <div style={{ padding: '1rem' }}>{children}</div>
    </CardContext.Provider>
  )
}

I hope your imagination helps you see that this problem affects more than our simple Card component; that there are other offenses of having too many styling responsibilities. One of the most common ones is exporting margins, but I'll save writing about that for another day.

When you're struggling to get some UI to work the way you want, try to take a step back to make a step forward. Examine if some part of your component is overloaded, and if separating those responsibilities might not solve the problem.

Typescript Prevents Bad Things... and Good Things

Fri, 08 Sep 2023 00:00:00 GMT

import { RandomNumber } from './_components'

A few days ago, TypeScript was the main topic of discussion on tech Twitter. <Marker content="I will never call it that other name." /> The reasons why aren't worth giving any more time or energy. But I do wish to discuss some thoughts I have regarding working with TypeScript.

Let me state up front, my experience with TypeScript has been largely a net positive. But being a net positive is not the same thing as being entirely positive. I have had negative experiences with TypeScript and I have some criticisms I will address in this post.

TL;DR;

TypeScript prevents many bad things: bugs, errors, bad assumptions and more. The type system can give you a lot of confidence in your programs. This is overwhelmingly positive.

I also think TypeScript prevents good things, too. It is often far easier to express functionality than it is to express the types required for that functionality. This can stifle creativity and innovation. It's very easy to build something undeniably useful in the realm of JavaScript, that turns out to be extremely difficult to express type-wise in TypeScript.

I think it's ok to admit this. I posit it is more difficult to learn the type system deeply and intuitively than the rest of programming language. Thus, most of us working in TypeScript who are not experts in the type system are making a tradeoff where we limit our programmatic expressiveness for the sake of type safety. I think it's ok to have nostalgia for how easy it was to express ourselves when it was just JavaScript.

In plain terms

I feel very confident in my JavaScript abilities. In my ability to express the functionality I desire with the language. Because TypeScript is a superset of JavaScript, I maintain this ability to express the functionality I desire.

That said, my ability to express the type correctness of my functionality is far more limited. I don't think I'm alone in this limitation. In fact, it makes me wonder if it's a limitation of the type system itself! I say "wonder" purposefully. Someone far better at using the type system could likely prove me wrong.

In fact, I would love it if they would. Guide me, teach me to be better, because I think it is far harder to gain fluency in TypeScript's type system than it is to write programs. It's esoteric, algebraic, <Marker content={I am pretty darn good at math, as I'll describe soon, so please don't come at me with "Get gud!"} /> and there are far fewer resources on deciphering and unlocking its nuances than there are of the rest of the language.

I think because because of this gap between the ease of expressing the functionality and the difficulty of expressing the type correctness for that functionality, we often have to forego otherwise "good things" because we cannot guarantee thorough type safety in order to so. On occasion, we get worse APIs because they are easier to express type-wise, even when doing so hampers and limits functionality and expressiveness.

Shortly, I will demonstrate this challenge with a bit of code I wrote for fun, that in a world of just JavaScript, it would be fine to use. But despite my best efforts--asking a TS expert on Twitter, consulting Chat-GPT for hours, reading docs, and even trying to decipher the types in another library--I have been unsuccessful in getting the types right and have to abandon this "good thing". Without the type safety, it's not usable by others in the community.

My background with types

I do not have an extensive background with typed programming languages. My experience is primarily with forms of typed JavaScript. Starting in 2019, I spent just over 2 years working with Flow. <Marker content="I still prefer Flow's error messages if I'm being honest." /> I have essentially written TypeScript every day since that time.

I have dabbled in some strongly typed languages, with ReasonML and ReScript being the ones I have used most seriously. I have finished a few small projects with these languages and have also contributed to an open source project that used these languages.

I am by no means an expert in types or TypeScript, but I'm not uncomfortable with them either.

In university, I double majored in Philosophy and Mathematics. These areas of study are useful for understanding a type system. Just look at some of my blog posts. I enjoy a little set theory and symbolic logic here and there.

What I am trying to say is I believe I am capable of learning a type system well. I have the tools and skills. But I will admit up front, there are parts of TypeScript for which I have struggled to develop any intuition, which we will discuss in more detail later.

That time I couldn't use state machines at work because they weren't type safe yet

I couldn't find a better place to add this anecdote, but I need to share it with this post because it's a "good thing" that was prevented by the lack of complete type safety.

I tried to introduce state machines to a work place to manage a very complicated bit of UI. Most people saw the value of the state machine for this particular situation and appreciated the run time guarantee of never getting into impossible states.

The problem was I couldn't get the correct types for the state of the machine. It was a combo of Flow and the existing types for the library. It just couldn't be done.

I was required by a staff engineer to abandon the use of state machines and told if I wanted that kind of run-time safety, I would have to also make it compile-time safe, aka type safe. I ended up writing a reducer that acted like a state machine. There are some posts about it around here. It was ~3x the code to express the same functionality. But hey, types!

A recent struggle as an example

I really enjoy learning about how things work on a fundamental level. I also enjoy solving puzzles. <Marker content="Probably why I enjoy Advent of Code as much as I do." /> In order to experience these two joys at once, I will occasionally attempt to rebuild a small library (or a stripped down version of one) from scratch, so I can both test myself and see what I learn in the process.

Recently, I decided to try and write a small pattern matching library, similar to ts-pattern. I enjoy pattern matching, but it's not built into JavaScript, so if we want to experience the expressiveness of using it, we have to implement it ourselves.

Here's what I wanted to accomplish with my lib:

Our function must receive an input that can be matched against an arbitrary number of cases
It would be nice if those cases could be values or a predicate function that received the input
It must be able to return a default value

I wrote my first pass in plain JavaScript in ~5 minutes. It looked something like this: <Marker content="It should go without saying, the following code could be written as a class or use the <code>this</code> keyword. I don't want to hear it. I <em>know</em> how to do that. I just <em>happen</em> to enjoy writing functions and closures instead. If I do see you complain about it on Twitter, I'll know you never read these footnotes when you really should." />

/**
 * Because ts-pattern uses match/with, I wanted to do something
 * slightly different. I decided to use Ruby's case/when, but since
 * "case" is already a keyword in JavaScript, I'm spelling it "kase"
 */
function kase(input) {
  // Over time, I've developed a fondness for writing simple closures
  // and so a closure is how we manage the state of our pattern matcher
  let isMatched = false
  let result = undefined

  // I also prefer to avoid using `this` if I can
  // We can do this easily by instantiating the object
  // and referring to it
  const api = {}

  // Our primary way of testing patterns against the input
  // If we get a match, the result is set to the return of the callback
  function when(pattern, callback) {
    if (isMatched) return api

    // This allows us to pass values or a predicate function
    const predicate =
      typeof pattern === 'function'
        ? () => pattern(input)
        : () => pattern === input

    if (predicate()) {
      isMatched = true
      result = callback(input)
    }

    return api
  }

  // Default case handling
  function otherwise(callback) {
    if (isMatched) return result

    return callback(input)
  }

  // If no default case is provided, we need a way to get the result
  function end() {
    return result
  }

  api.when = when
  api.otherwise = otherwise
  api.end = end

  return api
}

This simple function works great. We can use it like so:

const result = kase(Math.round(Math.random() * 100))
  .when(
    x => x <= 33,
    () => 'Low',
  )
  .when(
    x => x <= 67,
    () => 'Mid',
  )
  .when(69, () => 'Nice!')
  .otherwise(() => 'High')

And check it out in action: <Marker content={Sorry if it takes you forever to get a "Nice!" response.} />

Now, let the trouble begin.

We're going to try and add types to this. Here's what we need to accomplish (and I have thus far been unable):

kase needs to be typed such that it returns an object with when, otherwise, and end typed correctly
The functions passed to when and otherwise need to infer the correct type of the input
result needs to be a union of the types returned by the callbacks provided to whens and otherwise and returned from otherwise and end

If you want to follow along and try to work it out on your own, you can use this TypeScript Playground to interact with the code and try and fix the type errors.

The very first error we see is:

Parameter 'input' implicitly has an 'any' type

We can knock this one out easily. We don't want to specify a type of input, we simply want whatever the user passes in to be the type throughout the function. This is exactly what a generic is for, so let's add one:

function kase<Input>(input: Input) {
  // ... the rest
}

That was easy. The next error we have is:

Variable 'result' implicitly has type 'any' in some locations where its type cannot be determined.

We get this error because we set result as the return of our callbacks but we don't know that type yet. Let's add an unknown and come back to it. There are other errors we can solve before that one:

let result: unknown = undefined

Now, the next error we have is:

Parameter 'pattern' implicitly has an 'any' type.

So let's give it a type. A pattern is either an unknown value <Marker content="We will revisit this later, too." /> or it's a function that receives the input and returns a boolean. That looks like this:

function when(pattern: ((input: Input) => boolean) | unknown, callback) {
  //...
}

Our next two errors are actually of the same variety:

Parameter 'callback' implicitly has an 'any' type.

Let's make ourselves a little helper type to handle this.

type Callback<Input> = (input: Input) => unknown

function kase<Input>(input: Input) {
  // ...
  function when(
    pattern: ((input: Input) => boolean) | unknown,
    callback: Callback<Input>,
  ) {
    // ...
  }

  function otherwise(callback: Callback<Input>) {
    //...
  }
}

So far, this has been pretty easy. Our remaining errors are all related. I'll combine them into one: Properties 'when', 'otherwise' and 'end' do not exist on type '{}'. We instantiated api as an empty object and thus, TypeScript doesn't know what properties should eventually exist on api. We need to either change our code or cast the type of api. Let's try casting it. I'm going to create another helper type to do so:

// ...
type API<Input> = {
  when: (
    pattern: ((input: Input) => boolean) | unknown,
    callback: Callback<Input>,
  ) => API<Input>

  otherwise: (callback: Callback<Input>) => unknown

  end: () => unknown
}

function kase<Input>(input: Input) {
  // ...
  const api = {} as API<Input>
  //...
}

Great! Now all our errors are gone. Or are they?

While we have no errors in our function, we don't have type safety. We actually have to try and call this function and see what happens. So let's use it below where we define it, like so:

const result = kase(Math.random())
  .when(
    x => x < 0.33,
    () => 'low',
  )
  .when(
    x => x < 0.67,
    () => 'mid',
  )
  .otherwise(() => 'high')

What do you know? We have errors. Parameter 'x' implicitly has an 'any' type. Why is this the case? We indicated that pattern should return the type of the input, so TypeScript should already know the type of x. What gives?

Well, it turns out there are two problems with our types so far.

First, if we examine the resulting type of when, it turns out pattern is actually unknown. Our union isn't working the way we expected.

Second, when we check if pattern is a function, it doesn't narrow it to our predicate type, it narrows it only to Function. There is no way for TypeScript to determine that when pattern is a function, it's specifically our predicate function, at this moment. To fix this, takes a bit of work.

We're going to make a few more helper types, change one of our original type decisions, and use a type predicate function for our pattern predicate function. So much predication! Here we go:

// ...
type Predicate<Input> = (input: Input) => boolean

// Here we make an "API" change, instead of `unknown`
// we narrow it to only types that match the Input generic
type Pattern<Input> = Predicate<Input> | Input

type API<Input> = {
  when: (pattern: Pattern<Input>, callback: Callback<Input>) => API<Input>
  // ...
}

// This is a type predicate, a function that returns a boolean
// where we indicate to TypeScript the type `pattern` is
// when this function returns true
function isPredicate<Input>(
  pattern: Pattern<Input>,
): pattern is Predicate<Input> {
  return typeof pattern === 'function'
}

function kase<Input>(input: Input) {
  //...
  function when(pattern: Pattern<Input>, callback: Callback<Input>) {
    //...
    const predicate = isPredicate<Input>(pattern)
      ? () => pattern(input)
      : () => pattern === input
    // ...
  }
  //...
}

Awesome! There are no errors. If you're following along, your playground should look like this.

But!!! Do we have full type safety? No, we don't. Hover over the type of result. It's still unknown, which makes sense, we said we'd come back to that later, and now is later.

A brief aside

Getting to this point, where we have everything typed correctly except for result, didn't take me long, but it took me a lot longer than writing the functionality. The first few steps were pretty easy, maybe taking 20 minutes or so. But once I got to the point where pattern wasn't typed correctly, where x was implicitly any, I started to lose time quickly.

I explained it to you simply here, but that's only because I tried and failed a few ways before figuring it all out. I went down the road of function overloads, casting, all sorts of other attempts. I tried rewriting it as a class to see if it was easier to type. I tried a lot of things until I got to this point. Probably took anywhere from 1-4 hours. Not really sure because it's mixed in with other experiments and attempts.

But that's exactly what I'm getting at. Functionality was exponentially easier to express than the type correctness of that functionality. ~5 minutes compared to hours.

The next step we're about to do, at the moment I write this, I still haven't solved. I have probably put 8-12 hours into this. I've tried rewriting the entire API to make it better, but I haven't cracked it yet. This is where productivity is lost. It's at this point where if this wasn't solely for my own edification, I'd just go back to a switch (true) pattern and move on. It's not worth me making this helpful function anymore.

Damn it!!!

So... I stepped away after writing that previous paragraph. It was entirely true at that point in time. But after I ate some lunch and did some chores, I came back and gave it one more try (probably about my 10th try) and wouldn't you know, I finally got it.

I still stand by what I've posited so far in this post. Getting the types correct can be onerous and burdensome. It certainly has been for me in this specific example, and situations like this very one have happened to me dozens of times before. TS can stand for TimeSuck sometimes. <Marker content="I call dibs if no one has ever said that before." />

That said, let's get this nut cracked. Let's figure out how to get result typed correctly.

To figure this out, let's consider what result should be. It begins as undefined, and then it should be the return type of any callback passed to when or otherwise. So if all those callbacks return string, I would expect result to be the type string | undefined.

So far, we have the return of a Callback as unknown. It's true that we don't know what that value is, but we can pass a second generic to Callback to at least give it a name, like so:

type Callback<Input, Return> = (input: Input) => Return

This should break a lot of things. Everywhere we've used Callback now expects a second type passed to it. So how do we do this?

Let's start by adding a Return generic to when and otherwise.

type API<Input> = {
  when: <Return>(
    pattern: Pattern<Input>,
    callback: Callback<Input, Return>,
  ) => API<Input>

  otherwise: <Return>(callback: Callback<Input, Return>) => unknown
  //...
}

function kase<Input>(input: Input) {
  //...
  function when<Return>(
    pattern: Pattern<Input>,
    callback: Callback<Input, Return>,
  ) {
    //...
  }

  function otherwise<Return>(callback: Callback<Input, Return>) {
    //...
  }
  //...
}

Ok, but result is still unknown. Why? Because the return types for when, otherwise and end don't track the result. How can we do this? We need to change those unknowns into a Result somehow.

I'm not going to lie, this next part is not very intuitive, especially if you don't have any functional programming experience.

Right now, our api mutates and returns the result because it's held in a closure. In JavaScript, this is fine and used to be a far more common pattern than it is now. But what if instead of mutating result, we make our api stateless, and return a new api with the correct state baked in instead? What if we make our api immutable? Then we'd be able to identify what type of Result we have when we return the new api. How do we do this?

First, we're going to start with a "factory function". We're going to take everything inside of kase and move it inside a kaseFactory:

function kase<Input>(input: Input) {
  return kaseFactory<Input>(input)
}

function kaseFactory<Input>(input: Input) {
  // literally everything we had to this point
}

Next, we're going to make our factory stateless. Instead of holding isMatched and result in closure, we're going to pass them in as arguments to the factory. The "state" of the api is static, and to change the state, we'll just return a new api with the next state. Thus, our initial state has isMatched set to false and result set to undefined, like so:

function kase<Input>(input: Input) {
  return kaseFactory<Input, undefined>(input, false, undefined)
}

function kaseFactory<Input, Result>(
  input: Input,
  isMatched: boolean,
  result: Result,
) {
  // And we delete the following commented out lines
  // let isMatched = false
  // let result: unknown = undefined.
  // The rest is the same
}

Notice two things: First, that we added a Result generic to kaseFactory and pass in undefined as our initial type when we call it in kase. Second, that we're currently in a broken state. We need to fix a few things, but I wanted to explain what we're about to do first.

Up til now, when we got a match, that is when predicate() returned true, we mutated the isMatched and result values. This mutation prevented us from being able to type result properly.

Going forward, when we have a match, we're going to create and return a new api by calling kaseFactory with new arguments. We'll pass in the same input, true for the isMatched parameter, and then the result of calling the callback. We'll also be able to pass the Input generic along, as well as the typeof result from the callback, like so:

function when<Return>(
  pattern: Pattern<Input>,
  callback: Callback<Input, Return>,
) {
  if (isMatched) return api

  const predicate = isPredicate<Input>(pattern)
    ? () => pattern(input)
    : () => pattern === input

  if (predicate()) {
    // Here's the change
    const result = callback(input)

    return kaseFactory<Input, typeof result>(input, true, result)
  }

  return api
}

Now we're returning a whole new api with the correct types baked in! This means we now know the type of Result no matter where we are in the chain.

We're almost finished. We just need to add a Result generic to our API type so that we correctly describe the return types of our methods.

type API<Input, Result> = {
  when: <Return>(
    pattern: Pattern<Input>,
    callback: Callback<Input, Return>,
    // Notice the union passed in the `Result` generic slot
  ) => API<Input, Result | Return>

  // Same union is now returned here as well
  otherwise: <Return>(callback: Callback<Input, Return>) => Result | Return

  // End is guaranteed to be the `Result`
  end: () => Result
}

Now... now, we've truly done it. Our result will be typed correctly when we use kase(). If you've been following along, this is what your code should look like at this time:

type Callback<Input, Return> = (input: Input) => Return

type Predicate<Input> = (input: Input) => boolean

type Pattern<Input> = Predicate<Input> | Input

type API<Input, Result> = {
  when: <Return>(
    pattern: Pattern<Input>,
    callback: Callback<Input, Return>,
  ) => API<Input, Result | Return>

  otherwise: <Return>(callback: Callback<Input, Return>) => Result | Return

  end: () => Result
}

function isPredicate<Input>(
  pattern: Pattern<Input>,
): pattern is Predicate<Input> {
  return typeof pattern === 'function'
}

function kase<Input>(input: Input) {
  return kaseFactory<Input, undefined>(input, false, undefined)
}

function kaseFactory<Input, Result>(
  input: Input,
  isMatched: boolean,
  result: Result,
) {
  const api = {} as API<Input, Result>

  function when<Return>(
    pattern: Pattern<Input>,
    callback: Callback<Input, Return>,
  ) {
    if (isMatched) return api

    const predicate = isPredicate<Input>(pattern)
      ? () => pattern(input)
      : () => pattern === input

    if (predicate()) {
      const result = callback(input)

      return kaseFactory<Input, typeof result>(input, true, result)
    }

    return api
  }

  function otherwise<Return>(callback: Callback<Input, Return>) {
    if (isMatched) return result

    return callback(input)
  }

  function end() {
    return result
  }

  api.when = when
  api.otherwise = otherwise
  api.end = end

  return api
}

Let's take a moment

Can we just take a moment to appreciate just how challenging this was?

It required wiring three different generics through our types, which frankly, I could have made a whole lot harder to read. <Marker content="Like so many types I read that only use <code>T</code> and <code>U</code>, etc." />

It required a type predicate in order to properly narrow our pattern. Admittedly, a type predicate is not difficult to use, but does require knowing about this uncommon feature.

Finally, it required adding an entire layer of indirection in order to be able to type our end result correctly! How many people are going to think about adding "yet another function" to solve this problem? <Marker content={I'm not going to lie, I frequently say, "You can solve any problem with enough wrapping functions." I've also been known to say the CSS equivalent, "You can solve any layout problem with enough wrapping <code>div</code>s."} /> Maybe a bunch of you, but I'd bet just as many give up entirely. I almost did. <Marker content="And there ain't no shame in it!" />

Wrap up

Programming is communication. The inherent difficulty of all communication, programming, linguistic, or otherwise, is that we can only communicate what we are capable of expressing. <Marker content="There's also the whole issue of the receiver of the communication, but I'm going to ignore that at the moment." />

When it comes to programming in TypeScript, at least for me, the effort to express functionality and the effort to express the types for that functionality can be wildly different. This example I shared took ~5 minutes to write the functionality and several days and attempts for me to get the types right. That's... not awesome.

I hope it's clear, I'm not arguing we should stop using TypeScript. But I am arguing that we should be mature enough to acknowledge how challenging it can be to write type safe code sometimes. That sometimes we give up having some "good things" for the sake of avoiding many "bad things".

Also, we should probably just add pattern matching on types like OCaml to TypeScript already. <Marker content="🙃" />

Quit Your YAP-ing

Mon, 14 Aug 2023 00:00:00 GMT

import { Button } from '../../../components/Button' import { Card1, Card2, CardWithChildren, CardWithSlotsExample } from './_Cards'

A couple years back, I came up with what I hope is a clever name to a common problem I see in React components, but I never took the time to write about it. I call it YAP (Yet Another Prop) Syndrome, and once you recognize it, you'll see it every where.

YAP occurs when we add props to a component that would be better handled by composition. Simple definition, but I'll be the first to admit that it's challenging to develop the intuition to recognize this, but I'll do my best to give you a few examples.

Most components require some props in order to work, this is simply how functions work. Most accept inputs to be used in the output. YAP occurs when we add excessive props that could be handled better by making a new composition. This is often the result of requirements changing as time goes by without giving alternative solutions much thought.

Let's consider a simple Card component with a button in the Card's footer.

Now, it's completely possible that the first time you're given this design, you bake the button in because there's only going to be one. A simplistic approach might look like this:

type CardProps = {
  action?: {
    onClick: () => void
    text: string
  }
  body?: string
  title?: string
}

/**
 * All the code samples in this post are rudimentary and omit styles. I trust
 * you can figure out what markup you would need to get the result you want.
 */
function Card({ action, body, title }: CardProps) {
  return (
    <div>
      <div>
        {title && <h4>{title}</h4>}
        {body && <div>{body}</div>}
      </div>

      {action && (
        <div>
          <button onClick={action.onClick} type="button">
            {action.text}
          </button>
        </div>
      )}
    </div>
  )
}

This is probably fine.

That is until a few months go by, and someone decides that maybe a card can have two buttons, a left and a right one. Something like this:

Now, a really bad approach would be left and right props, like so:

type Action = {
  onClick: () => void
  text: string
}

/**
 * Bonus tip: I prefer to write keys with adjectives
 * in noun-adjective order. That way, all the like keys
 * are grouped together when I sort them alphabetically
 */
type CardProps = {
  actionLeft?: Action
  actionRight?: Action
  body?: string
  title?: string
}

function Card({ actionLeft, actionRight, body, title }: CardProps) {
  const hasAction = actionLeft || actionRight

  return (
    <div>
      <div>
        {title && <h4>{title}</h4>}
        {body && <div>{body}</div>}
      </div>

      {hasAction && (
        <div style={{ display: 'flex', gap: '1rem' }}>
          {actionLeft && <CardAction action={actionLeft} />}
          {actionRight && <CardAction action={actionRight} />}
        </div>
      )}
    </div>
  )
}

function CardAction({ action }: { action: Action }) {
  return (
    <button
      onClick={action.onClick}
      type="button"
      style={{
        flex: '1 1 auto',
      }}
    >
      {action.text}
    </button>
  )
}

"But Kyle, why is this bad? It works, doesn't it?"

Sort of. It sort of works.

You see, we've started YAP-ing. We're adding "yet another prop" to adjust our component, but once we start down this path, there's no good way to stop going further.

Which prop should we map a single action to? actionLeft? actionRight? I don't know, and neither will the other people using Card.

What happens if the designer requests a third button? Do we add an actionMiddle prop? What happens if the user provides actionMiddle and actionRight but no actionLeft? Does actionMiddle become an actionLeft, or should there be an empty space to the left?

What happens if they ask for only a single button, but it should only span half the width of the Card's footer? Which prop is that now? If we have three different action slots, how do we do half of the width of the card?

As I've already said, the better solution is composition. Give the consumer (the one using the component in their code) the ability to create any composition they need. 1 button, 2 buttons, 3 buttons, no buttons. It doesn't matter.

We can take a few approaches to this. Let's explore them.

Using `children`

First, we could use children and let the consumer make whatever they need there.

function Card({ body, children, title }) {
  return (
    <div>
      <div>
        {title && <h4>{title}</h4>}
        {body && <div>{body}</div>}
      </div>

      {children && <div>{children}</div>}
    </div>
  )
}

function ExampleWithChildren() {
  return (
    <Card body="Here is an example body text." title="Example Title">
      <Flex justify="space-between">
        <button onClick={() => {}} type="button">
          Click me
        </button>

        <button onClick={() => {}} type="button">
          Click me, too
        </button>
      </Flex>
    </Card>
  )
}

<div class="my-8 flex justify-center"> <CardWithChildren client:load body="Here is an example body text." title="Example Title"

<div style={{ minWidth: '30ch' }}>
  <div class="flex justify-between">
    <Button onClick={() => {}}>Click Me</Button>
    <Button onClick={() => {}}>Click Me, too</Button>
  </div>
</div>

</CardWithChildren> </div>

This approach works well. We're able to control the layout of the buttons however we would like. We can layout any number of buttons or no buttons at all. We can even add other elements we might need: text, images, etc.

The downside of this approach is children feels a touch odd when there are other elements rendered from props. It's unclear where this will render without looking at the implementation of the component. We can maybe make this a little bit clearer with "slots".

Using slots

Slots is not a common term in React, but they've been there since the beginning. You'll more commonly hear the word "slots" in regards to other frameworks such as Vue and Astro, but in React, it's simply a prop that accepts a JSX element and renders it in a location in the component.

Let's say we're asked to make it possible for Card to have some content above and below the main body of content. We can't use children without giving the consumer a way of rendering the body. We could do this with compound components, but let's focus on a different approach. We're going to name two props: header and footer, and if the consumer passes in something to that prop, it'll get rendered in the appropriate slot. Like so:

function Card({ body, footer, header, title }) {
  return (
    <div>
      {header && <div>{header}</div>}

      <div>
        {title && <h4>{title}</h4>}
        {body && <div>{body}</div>}
      </div>

      {footer && <div>{footer}</div>}
    </div>
  )
}

function ExampleWithSlots() {
  const header = <Flex justify="center">EXAMPLE</Flex>

  const footer = (
    <Flex justify="space-between">
      <button onClick={() => {}} type="button">
        Click me
      </button>

      <button onClick={() => {}} type="button">
        Click me, too
      </button>
    </Flex>
  )

  return (
    <Card
      body="Here is an example body text."
      header={header}
      footer={footer}
      title="Example Title"
    />
  )
}

Summary

It's tempting to handle conditional React code with yet another prop, but it's often a bad solution and makes our code more complex than necessary. Make sure you're not adding excessive props in a situation that could be better handled with composition.

If you determine composition is a better answer, you have several options at your disposal. You might even be able to combine compound components and composition to help you quit your YAP-ing.

Good luck and let me know if you need any help with this.

Compound Components

Sat, 27 May 2023 00:00:00 GMT

import { Custom1 } from './_Custom1' import { Custom2 } from './_Custom2' import { Custom3 } from './_Custom3' import { Tabs } from './_Tabs' import { ITEMS } from './_shared'

Compound components are nothing new in React, but it's an advanced pattern that not everyone takes the time to learn. I want to break down how I build compound components, and make it easy for you to do the same.

For a working example, we're going to build a Tabs component.

The code for that might look something like this: <Marker content="Styling details omitted." />

function Tabs({ items = [] }) {
  const [selectedValue, setSelectedValue] = React.useState(items.at(0)?.value)

  // There are plenty of better ways to do this
  // I'm keeping it simple for the example
  const [selectedItem] = items.filter(item => item.value === selectedValue)

  return (
    <div>
      <div>
        {items.map(item => (
          <button
            key={item.value}
            onClick={() => {
              setSelectedValue(item.value)
            }}
          >
            {item.value}
          </button>
        ))}
      </div>

      {selectedItem && <div>{selectedItem.content}</div>}
    </div>
  )
}

Now, to transform this into a compound component, we're going to start by creating a TabsContext, like so:

const TabsContext = React.createContext()

const useTabsContext = () => React.useContext(TabsContext)

Our useTabsContext hook will only make sense if we add a TabsContext.Provider somewhere. For compound components, I like to create a Root component that renders this Provider.

Tabs.Root = function TabsRoot({ children }) {
  return (
    <TabsContext.Provider value={undefined}>{children}</TabsContext.Provider>
  )
}

The job of the Root component is to receive all of the props that Tabs would accept and utilize the context's value to distribute them to the compound components we will create. For now, we're passing undefined because we haven't determined all that we need to store in the context just yet.

I would also like to point out that we attach Root as a property of the Tabs component. I do this primarily as a convenience. We could export a TabsRoot component, but I find it easier to import the main component, and then use the properties (the other sub-components) to create whatever composition I need.

We can add our Tabs.Root component to what will be our default Tabs composition without disrupting any functionality, like so:

return (
  <Tabs.Root>
    <div>
      <div>
        {items.map(item => (
          <button
            key={item.value}
            onClick={() => {
              setSelectedValue(item.value)
            }}
          >
            {item.value}
          </button>
        ))}
      </div>

      {selectedItem && <div>{selectedItem.content}</div>}
    </div>
  </Tabs.Root>
)

Now that we have our Tabs.Root in place and can make use of the TabsContext, what state do we need to manage with the it?

We need to be able to get the selectedValue and set it from anywhere within Tabs.Root using the useTabsContext hook. Let's start by duplicating the state in Tabs.Root to pass to the Provider.

// Notice we've added an `initialValue` prop
Tabs.Root = function TabsRoot({ children, initialValue }) {
  const [selectedValue, setSelectedValue] = React.useState(initialValue)

  return (
    <TabsContext.Provider value={{ selectedValue, setSelectedValue }}>
      {children}
    </TabsContext.Provider>
  )
}

And then in Tabs:

// we'll need an initialValue, we can default it to the first item if it exists
const initialValue = items[0]?.value

return (
  <Tabs.Root initialValue={initialValue}>
    <div>{/* the rest... */}</div>
  </Tabs.Root>
)

Now, we're at a place where we can start to migrate some of the sub-components of Tabs into compound components. Let's start with the Tabs.Trigger, the button we use to select a tab:

Tabs.Trigger = function TabsTrigger({ children, value }) {
  const { setSelectedValue } = useTabsContext()

  return <button onClick={() => setSelectedValue(value)}>{children}</button>
}

Notice we pass a value to the Tabs.Trigger. This is what we use to update the selectedValue state in our Context. Clicking the Tabs.Trigger updates the state of the TabsContext.

We can do something similar with the Tabs.Content component:

Tabs.Content = function TabsContent({ children, value }) {
  const { selectedValue } = useTabsContext()

  if (value !== selectedValue) return null

  return <div>{children}</div>
}

Notice with Tabs.Content that we control whether it renders or not thru the context. This is fundamentally different than before where we essentially filtered our list of items. Now, we will map over all the items and let Tabs.Content determine whether it should return some UI or null.

With our sub-components built, we can update Tabs to use them. Pay attention to how we have to map over items twice, once for the Trigger components and another time for the Content components.

function Tabs({ items = [] }) {
  const initialValue = items[0]?.value

  return (
    <Tabs.Root initialValue={initialValue}>
      <div>
        <div>
          {items.map(({ value }) => (
            <Tabs.Trigger key={value} value={value}>
              {value}
            </Tabs.Trigger>
          ))}
        </div>

        {items.map(({ content, value }) => (
          <Tabs.Content key={value} value={value}>
            {content}
          </Tabs.Content>
        ))}
      </div>
    </Tabs.Root>
  )
}

Now, we did all that work and component hasn't changed. Still looks and works great. But don't be fooled. Just because the functionality hasn't changed at all, doesn't mean making it slightly more complicated wasn't worth it. What we've actually done is separate the functionality of the Tabs from whatever user interface we decide to create with it. We can move the Triggers anywhere we want in relation to the Content and as long as we pass in the correct value, it will continue to work flawlessly.

For example, perhaps the Tab.Triggers should go on the bottom:

function TabsBottom({ items = [] }) {
  return (
    <Tabs.Root initialValue={items[0]?.value}>
      <div>
        {items.map(({ content, value }) => (
          <Tabs.Content key={value} value={value}>
            {content}
          </Tabs.Content>
        ))}
      </div>

      <Flex>
        {items.map(({ value }) => (
          <Tabs.Trigger key={value} value={value}>
            {value}
          </Tabs.Trigger>
        ))}
      </Flex>
    </Tabs.Root>
  )
}

Or perhaps on the side:

function TabsSide({ items = [] }) {
  return (
    <Tabs.Root initialValue={items[0]?.value}>
      <Flex>
        <Flex direction="column">
          {items.map(({ value }) => (
            <Tabs.Trigger key={value} value={value}>
              {value}
            </Tabs.Trigger>
          ))}
        </Flex>

        <FlexItem grow={1}>
          {items.map(({ content, value }) => (
            <Tabs.Content key={value} value={value}>
              {content}
            </Tabs.Content>
          ))}
        </FlexItem>
      </Flex>
    </Tabs.Root>
  )
}

Or perhaps we should have all the Tab.Triggers you can think of:

Now, we're able to create any composition for Tabs that we might need, while still having a great default composition for normal usage. Need icons in the Triggers? No problem. Need different colors for each Content? No problem. There is almost no limit to what you can do with this pattern.

Hope this helps you understand compound components a little better, and that you gain some benefit from adopting it in your projects. Let me know if it does!

Context, Composition, and Flexibility

Tue, 02 May 2023 00:00:00 GMT

import { Example1, Example2, Example3 } from './_Examples'

Recently, I had the following situation at work. It has been adapted to be less professional and more humorous:

Designer: Hey, you know our Input component?

Me: Yeah, this one?

Designer: Yeah, that's the one! Look, I want you to make it so that when the Input is optional, it shows a little bit of helper text to the right of label that says "(optional)". Like this:

Me: Oh, you wouldn't prefer to show an asterisk when it's required like almost every other website in existence? Like this:

Designer: Well, most of our Inputs should be required so we felt that this would be less noisy. Don't want to see *s everywhere.

Me: But every Input in all our apps, and all the web actually, is optional by default. You have to set the required attribute explicitly. Meaning the more likely scenario is seeing "(optional)" everywhere.

Designer: Yeah... I don't care. Just do it.

Now, if you've done software engineering for any significant amount of time, you've probably run into a scenario just like this one. It sucks to be told to do something that you know isn't the right solution.

That said, in this particular scenario, there's a pretty easy way for both of us to win and I'm hoping it will give you some more strategies when you're in a similar situation again in the future. Let me show you how.

First instincts vs. second thoughts

Given the nature of the change, it would be really tempting to solve it as simply as possible, perhaps like this:

function Input({ id, label, required = false }) {
  return (
    <div>
      <label htmlFor={id}>
        {label}
        {!required && ' (optional)'}
      </label>
      <input id={id} required={required} />
    </div>
  )
}

This definitely solves the problem, but we know that this isn't a great solution. It's likely to get push back from other teams who want something they're more accustomed to, like an * on required fields.

We might be tempted to change it so that Input receives a variant that determines how to handle this, perhaps like this:

function Input({ id, label, required = false, variant = 'showOptionals' }) {
  const getHelperText = () => {
    if (variant === 'showOptionals' && !required) return ' (optional)'
    if (variant === 'showRequireds' && required) return '*'

    return null
  }

  return (
    <div>
      <label htmlFor={id}>
        {label}
        {getHelperText()}
      </label>
      <input id={id} required={required} />
    </div>
  )
}

Now, if a team wants to show a more traditional * on their required inputs, they can add the variant="showRequired" prop. However, this would mean needing to add that to every single Input that needs that treatment. That's laborious, exhausting and tedious.

What if there was a way to apply a variant to every input, but only have to write it once?

Context and composition to the rescue

Let's create an InputStyleContext that will pass the variant to all consumers automatically.

const InputStyleContext = React.createContext()

function InputStyleProvider({ children, variant = 'none' }) {
  return (
    <InputStyleContext.Provider value={variant}>
      {children}
    </InputStyleContext.Provider>
  )
}

const useInputStyleContext = () => React.useContext(InputStyleContext)

Now that we have that, let's use the custom hook we made to get the variant off of context, rather than passed in as a prop to Input.

function Input({ id, label, required = false }) {
  const variant = useInputStyleContext()

  const getHelperText = () => {
    if (variant === 'showOptionals' && !required) return ' (optional)'
    if (variant === 'showRequireds' && required) return '*'

    return null
  }

  return (
    <div>
      <label htmlFor={id}>
        {label}
        {getHelperText()}
      </label>
      <input id={id} required={required} />
    </div>
  )
}

Now we have the option to change the appearance of our Inputs with a single wrapping component. You want the "(optional)" text, do this:

<InputStyleProvider variant="showOptionals">
  <Input id="name" label="Name" />
</InputStyleProvider>

Or if you want to show * on required fields, change the variant to showRequireds. It's that simple.

<InputStyleProvider variant="showRequireds">
  <Input id="name" label="Name" required />
</InputStyleProvider>

Now we have a solution that has satiated our designer, but gives us some flexibility still. I think that's a win-win.

Try to remember that context and composition might be a good solution for your problem, too.

And for the record...

The very first form I worked on after this change was, in fact, 5 Inputs, all optional, all with the "(optional)" text next to them. So much for being less noisy! Oh well.

Algorithms: Insertion Sort

Sun, 22 Jan 2023 00:00:00 GMT

import { InsertionSortVisual } from './_InsertionSortVisual'

Let me start this post with a question. Is an array of a single item a sorted array?

Not a trick question! It is, and we use this fact with insertion sort.

In the previous post on bubble sort, our algorithm spent a lot of time comparing items that were already sorted, especially near the end of the sort. That's really inefficient. How might we be able to avoid making these unnecessary comparisons?

If we were able to track an array that we knew to be sorted, we could stop looping past this array and instead insert items, one by one, into their correct position. Doing so, would save us a few unnecessary comparisons.

To accomplish this, we treat the first item in the array as a sorted list of a single item. Then, we compare the rest of the items to the items in this sorted list. When we find a spot for our item, we insert it into the sorted portion. By the time we finish looping through each item, our list will be sorted. No need for a final loop to verify nothing changed.

The details

The insertion sort algorithm goes like this:

Treat the first item as a sorted
Thus, starting from the 2nd item in the array, loop through each item
For each item:
- Loop through the sorted portion of our array
- Compare each item in the sorted portion to the item in the outer loop
- If the outer item is less than the inner item
  - Remove the outer item from its current position
  - Splice it into the inner position

function insertionSort(items) {
  let i
  let j

  /**
   * Loop from the start of the unsorted portion of our array
   * aka the second item
   */
  for (i = 1; i < items.length; i++) {
    /**
     * Loop thru the sorted portion of our array
     * aka from the first item to our outer item
     */
    for (j = 0; j < i; j++) {
      /**
       * Compare the item at `i` with `j`
       */
      if (items[i] < items[j]) {
        /**
         * We can remove the item at `i` out and destructure it
         */
        const [item] = items.splice(i, 1)

        /**
         * And splice the item back in at `j`
         */
        items.splice(j, 0, item)
      }
    }
  }

  return items
}

We can see it in action here:

Take notice that while we still do a lot of comparisons, we do quite a bit fewer than we did with bubble sort. In running the component above a few times in testing, I noticed it was about 1/2 as many as the bubble sort on average. That's a pretty good improvement. But we can still do better, and we'll learn how soon.

For egghead subscribers

If you enjoy learning from video content and have an egghead account, you can watch this lesson in the embed below or at https://egghead.io/lessons/javascript-sort-an-array-with-a-nested-for-loop-using-insertion-sort-in-javascript.

Algorithms: Bubble Sort

Wed, 18 Jan 2023 00:00:00 GMT

import { BubbleSortVisual } from './_BubbleSortVisual'

Preface

I've had the itch recently to write articles for all the algorithms and data structures I covered in my original Data Structures & Algorithms course and maybe a few others. <Marker content="Who knows? Maybe start working on another course." /> There's just something that tickles the pleasure centers of my brain to learn a new algorithm or review an old one. They might not always be useful in a practical sense, <Marker content="You will literally never use bubble sort at work, except as a joke." /> but I think practicing data structures & algorithms can help your brain improve its abilities to model problems well, and well-modeled problems are easier to solve.

I also wanted to play around with visualizing the algorithms with some React components, so double the fun for me, and hopefully for you, too.

A few words on algorithms, in general

Algorithms get an undeservedly bad rap these days because the word has been appropriated to describe the manipulations of social media companies to show us more ads. Let's not allow that negative connotation to stop us from learning them.

An algorithm is simply a set of instructions to perform a task, to get a desired outcome. A recipe is an algorithm. How you tie your shoes is an algorithm. The way you brush your teeth, an algorithm. Algorithms are everywhere and unavoidable.

When we examine algorithms and enjoy the intricacies that make one slightly better than another, they might teach us a thing or two. Perhaps about the world around us, perhaps about ourselves.

So don't let "algorithm" be a scary word for you just because of the media or the fact that it ends in a strange combination of consonants. Embrace them.

The bubble sort algorithm

We're going to start by learning the "bubble sort" algorithm. Its typically the first sorting algorithm people learn because it's a naive approach that's remarkably similar to how one might actually sort a collection of items in real life. The algorithm, goes like this:

Given a list of items, begin looping through the them one at a time
For each item, compare it to the next item in the array
- If they are out of order, swap them in place and track that a swap occurred
When the loop is complete:
- If any swaps occurred, repeat the previous steps
- else, the array is sorted

Simple, right? But simple, can be extremely inefficient! The bubble sort algorithm has a Big O of O(n^2), otherwise known as quadratic time. It's not the absolute worst score you can get for an algorithm, but it's pretty darn bad!

For those unfamiliar with Big O notation, let me break it down for this particular case quickly. <Marker content="I know better than to promise a separate blog post on a topic, but this is by no means an exhaustive explanation of Big O." /> Big O is how computer scientists describe the worst case performance of an algorithm. In the case of bubble sort, n represents the number of items we are sorting. Our algorithm requires that we loop through every item in the list. If we only had to do that, our Big O would be O(n), indicating that as n increases, the time it takes to sort them grows at the same rate.

However, in bubble sort, inside of our first loop we have an inner loop that compares each item with every other item. This results in doing n * n operations, or n^2. Think about this for a moment. This means that as n increases, the time to sort them quadratically increases. For example, if we have to sort 5x more items than a previous n, it will perform 25x worse!

Coding it up

Let's write the code for this algorithm piece by piece. Now, it might seem odd, but I think it might be a bit easier to write if consider what we would have to do if we were given a perfectly sorted list. How would we know that the list is sorted?

In the case of bubble sort, we know a list is sorted when a loop through its items is completed without swapping any of them. Thus, even for a perfectly sorted array, we still have to make at least one loop all the items. If we have to do something at least once, but conditionally after that first loop, does that conjure up a particularly rare looping mechanism for you?

I hope you came up with the do..while loop.

So rarely do we get to use this looping mechanism but it's quite useful for the right situation. We want to do at least one loop through the array, and continue looping through it while there were swaps in the previous loop. Let's write that code.

function bubbleSort(items) {
  let swapped = false

  do {
    // Gotta reset `swapped` with every outer loop
    swapped = false

    // TODO: Our inner loop will go here
  } while (swapped)

  return items
}

Now, let's add our inner loop. We need to take each item and check if it should swap with the nextItem. We'll need the index of our item to get the next item and to do swaps, and I like to do that with a combo of for..of and Array.prototype.entries(), like so: <Marker content="For this algorithm, because there is no need to <code>break</code> or <code>continue</code>, you could also use <code>Array.prototype.forEach</code> with a callback that made use of both the <code>item</code> and the <code>index</code> instead." />

function bubbleSort(items) {
  let swapped = false

  do {
    swapped = false

    for (const [idx, item] of items.entries()) {
      const nextItem = items[idx + 1]

      if (item > nextItem) {
        items[idx] = nextItem
        items[idx + 1] = item
        swapped = true
      }
    }
  } while (swapped)

  return items
}

We can see how the algorithm works with a visual. This visual sorts 50 lines from shortest to tallest. It has two additional features not found in the code block above: it highlights the item currently being sorted, and it tracks the number of comparisons made by the algorithm. You can run the visual several times to see how close it gets to that n^2 performance number. <Marker content="If you have the time. Each run will take a little over a minute because this algorithm is so inefficient." />

You can see that sorting items with bubble sort is agonizingly slow. We will discuss much faster and more efficient sorting algorithms, but it's useful to learn bubble sort all the same. Knowing poor performing algorithms can help us identify inefficient ones in our programs and guide us towards better solutions.

For egghead subscribers

JSX was a Mistake

Mon, 07 Nov 2022 00:00:00 GMT

import { Box, ChildrenExample, NoChildrenExample } from './_Examples'

It wasn't. I just wanted your attention. Thanks.

And now while I have it, I do want to discuss a bit of common confusion caused by JSX.

One of the most common misunderstandings I run into with people regarding React is this: If a component has a state change and rerenders, it does not cause children to rerender. I think this is very obvious when we remove JSX, and use React.createElement instead. Let's have a look.

Here we have one of my favorite components to demonstrate rerenders, a Box that changes background color whenever it's rendered. This Box allows us to pass children through it. Thus, we'll make an Example where we force an update, which will cause Box to rerender.

import { useForceUpdate } from './hooks'
import { randomRGB } from './utils'

function Box({ children }) {
  return (
    <div style={{ backgroundColor: randomRGB(), padding: '1rem' }}>
      {children}
    </div>
  )
}

function Example() {
  const forceUpdate = useForceUpdate()

  return (
    <Box>
      <button type="button" onClick={forceUpdate}>
        Update
      </button>
    </Box>
  )
}

As you can see, clicking "Update" causes the Box to change colors. <Marker content="If you are visually impaired, I added a <code>data-background-color</code> attribute to the <code>div</code> that changes with it. I wasn't sure what else I could do, so I hope that helps. Please let me know if there's more I can do and I'll make an update." /> This is because Box is a function that gets called when Example is called. This is obvious when instead of JSX, we use React.createElement instead.

function Box({ children }) {
  return React.createElement('div', {
    style: { backgroundColor: randomRGB(), padding: '1rem' },
    children,
  })
}

function Example() {
  const forceUpdate = useForceUpdate()

  return React.createElement(
    Box,
    null,
    React.createElement('button', { type: 'button', onClick: forceUpdate }),
  )
}

Notice that this time, we replaced <div /> with React.createElement('div'). Then when we needed to render the Box in Example, we pass it to another call of React.createElement. Thus, each time Example rerenders, we call a function to render a Box and a function to render a button. Makes it pretty clear where functions are getting called.

How does this relate to `children`?

Well, simply put, children is typically not a function call, it's just a value. <Marker content={Yes, you can pass a function as <code>children</code> like the "render prop" pattern and that would be treated differently} />

What if I add a "slot" for children in our Example component like this:

function Example({ children }) {
  const forceUpdate = useForceUpdate()

  return React.createElement(
    Box,
    null,
    // createElement's third parameter is a rest parameter,
    // so we can add more items by adding more arguments
    React.createElement('button', { type: 'button', onClick: forceUpdate }),
    // here's the slot, it'll come after our button
    children,
  )
}

Now, what happens if we pass Box as children of our Example?

<Example>
  <Box>I am a child</Box>
<Example>

<div className="my-8"> <OffsetWrap> <ChildrenExample client:load> <Box client:load>I am a child</Box> </ChildrenExample> </OffsetWrap> </div>

Notice that our child Box doesn't rerender, while the parent Box still does. It remains the same background color it was when it initially rendered, because it's not getting called again when Example rerenders.

Heck, let's have some fun and put Example into Example.

Kind of fun, isn't it?

When does this matter?

In most cases, I wouldn't fret about rerendering a Box or whatever component you might be working with, but it's just good knowledge to have. You'll be better off having this concept etched into your brain than not.

The place I'm most concerned about getting this right is the use of Context Providers. I wrote a very similar blog post all about that. Check it out if you're interested.

In general, if you have a component with frequent state changes and it uses children, consider letting as much of the inner contents be composed via children as possible to avoid unnecessary rendering.

You never know, you might just find your component is now a bit more reusable, too.

Capture Phase Event Handling in React

Sat, 18 Jun 2022 00:00:00 GMT

import Breakfast from './_Breakfast' import EventButton from './_EventButton'

So... as of the time I'm writing this, I've used React for 7 years and today (February 22, 2022) I learned something completely unbeknownst to me. <Marker content="Yes, it took me 4 months to get back to this and write the last few paragraphs, lol." /> You can append Capture to an event name to have it handled in the "capture" phase of event delegation, instead of the "bubbling" phase. Who knew?! It's right here in the docs.

So what is this and why is it useful? Let's explore.

What is event capturing and bubbling?

In short, because there are a million other articles on the topic, event capturing and bubbling describe how events traverse the DOM. Look at the following markup:

<html>
  <head>
    Event capturing and bubbling
  </head>
  <body>
    <div>
      <button>Click me</button>
    </div>
  </body>
</html>

When you click the button, the "capture" phase begins. It starts at the top of the DOM, and traverses down the tree through each element. When it reaches the target, the button, it begins the "bubbling" phase and traverses back up to the top of the DOM tree. We can imagine that loop like this:

<TableSimple headings={['Element', 'Event', 'Phase']} items={[ ['<code>html</code>', '<code>click</code>', 'capture'], ['<code>body</code>', '<code>click</code>', 'capture'], ['<code>div</code>', '<code>click</code>', 'capture'], ['<code>button</code>', '<code>click</code>', 'capture'], ['<code>button</code>', '<code>click</code>', 'bubble'], ['<code>div</code>', '<code>click</code>', 'bubble'], ['<code>body</code>', '<code>click</code>', 'bubble'], ['<code>html</code>', '<code>click</code>', 'bubble'], ]} />

We can see this by writing just a few lines of code:

// Wildcard selector
const allElements = document.querySelectorAll('*')

function logNodeName() {
  // I know, I hate using `this` too
  console.log(this.nodeName)
}

for (const el of allElements) {
  // This one will be used in the capture phase
  el.addEventListener('click', logNodeName, true)
  // This one will be used in the bubbling phase
  el.addEventListener('click', logNodeName)
}

Now I've attached the logNodeName function as a click event handler to every element on the document. That means, clicking anywhere, should log out all the elements touched in the "bubbling" phase. Note: this does not remove any listeners, so it's possible to have memory leaks if you add or remove elements from the page between clicks. Try it out here:

You can see that it starts at the html element and works its way down to the button and then works its way back up. Honestly, because I used the wildcard selector, *, you can click anywhere and see the output. Have fun.

Using the capture phase with React events

In most cases, React abstracts the process of attaching event handlers to elements. Rather than getting the element and writing addEventListener and removeEventListener, we use the associated element attribute for the given event we want to respond to, such as onClick.

const button = document.getElementById('#btn')
button.addEventListener('click', () => { console.log('clicked') })

// Vs.
<button onClick={() => { console.log('clicked') }}>Click me</button>

addEventListener and removeEventListener receive an optional third argument of the type boolean | Options. I will ignore the Options object as you can look that up here and instead focus on the boolean that represents the useCapture value.

By passing true into this third argument, we indicate that this event handler should be used in the capture phase. But, if we're using React's abstractions, we have no place to pass in a useCapture argument. Do we?

We do.

This is where appending Capture to the event handler name comes in. If we want a click handler to be used in the capture phase, rather than the bubbling phase, we use onClickCapture instead. Let's make an example.

Let's say we have a group of buttons and every button should use the exact same event handler. Rather than attach the same handler to each button, we can attach it to the parent element in the capture phase. I'm eating breakfast as I write this, so let's imagine a rudimentary menu for selecting a breakfast item.

const ITEMS = ['Eggs', 'Bacon', 'Pancakes', 'Toast']

function Breakfast() {
  const [selected, setSelected] = React.useState(null)

  const selectItem = e => {
    setSelected(e.target.value)
  }

  return (
    <div>
      <div>Selected: {String(selected)}</div>
      <div onClickCapture={selectItem}>
        {ITEMS.map(item => (
          <button key={item} value={item}>
            {item}
          </button>
        ))}
      </div>
    </div>
  )
}

See it in action here:

Now, before you judge the example too harshly for being rudimentary, let me be abundantly clear: This isn't the only way, or even the recommended way, to accomplish this. It's just to teach the concept. That said, I think it's kind of neat that we can do this without onClick handlers on each button.

Additional thoughts

This technique is a bit of a throwback. Back to a time where maybe you were using <input type="button"> or inlining an onclick attribute on a parent. It's unlikely in React and other modern frontend frameworks that you'll ever have to use *Capture events.

However, that doesn't mean it's not worth throwing this into your repertoire! You never know when you might run into a situation where this little tid bit is the simplest and most elegant way to solve the problem.

Why Use `useReducer`?

Mon, 06 Jun 2022 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro' import JumpingBall from './_JumpingBall' import ReducerJumpingBall from './_ReducerJumpingBall'

A while back now, my buddy Mike Hartington asked this:

<SocialPost authorName="Mike Hartington" authorHandle="@mhartington.io" authorProfile="https://bsky.app/profile/mhartington.io" avatarUrl="https://cdn.bsky.app/img/avatar/plain/did:plc:7kwylbxx56yro6aqz3oh5d2s/bafkreih5czye4acyme3j5ckt4bmwkypwqyqcq4mgecjq55g2lavdy573n4@jpeg" date="2022-02-12" content={`Random question for my react friends...

Is useReducer something folks use/like?`} />

I gave a brief answer in the replies, but thought I'd write a bit more about it here. If you've come across my blog before, much of what I'm going to write in this post will relate to other posts of mine, such as useEncapsulation and Enumerate, Don't Booleanate and more. There's a lot of overlap, so please check them out if you haven't. Forgive me if this all sounds familiar.

Two state primitives

React provides two state primitives, useState and useReducer for managing state for a component or custom hook. useState is a hook that gives us a straightforward [read, write] tuple. Like so:

const [count, setCount] = React.useState(0)

console.log(count) // "read" the value
setCount(count + 1) // "write" the next value

The other primitive, useReducer is a bit more complex. It gives us a [read, emitEvent] tuple. Like so:

const reducer = (state, event) => {
  switch (event) {
    case 'INCREMENT':
      return state + 1
    default:
      return state
  }
}

const [count, emitEvent] = React.useReducer(reducer, 0)

console.log(count) // "read" the value
emitEvent('INCREMENT') // emit the event

Now, more often you'll see emitEvent and event named dispatch and action respectively. I, too, often do this. However, I wanted to make it clear that what we're doing when we use useReducer is emitting and responding to events.

Choosing one over the other

In general, I treat useState as the default tool for the state management job. In many situations, I have a single state to manage and writing a few declarative state updaters for that state does the trick. That said, there are certain conditions that make useReducer a better choice. Here are the things I consider when making the choice:

Does the next state frequently depend upon the current state?
Is there more than one state to manage?
More importantly, are there situations where we change multiple states as a result of the same event?
Are there times where the same user event is handled differently depending on the current state?
Far less common, is there a use case where a consumer of the component may need to hook into and respond to events, aka the state reducer pattern?

If you answered "Yes" to any of these questions, then you might have a good use case for using useReducer. Let's work through an example to learn more.

Our example

Here I have a little jumping ball. Go ahead. Make it jump by clicking the button labeled "Jump".

Every time we click the button, the ball jumps. If we click it while the ball is already in the "air", it has no effect on the ball, which continues to fall due to "gravity". Try it. Click it as many times as you can while it's in the "air".

Nothing, right?

Let's focus in on some key parts of the code that represent what happens when we click the "Jump" button". First, we need to establish some states. We're going to use a combination of useState and useRef. We're going to use useState for states that we want the component to rerender when it changes, and refs for states that don't need to cause a rerender. I explain this more in depth in Comparing useRef and useState.

function JumpingBall() {
  // Y-position of the ball
  const [position, setPosition] = React.useState(0)
  // The amount of change the ball is experiencing for a given `tick`
  const delta = React.useRef(0)
  // The state of the ball, either 'idle' or 'jumping'
  const ballState = React.useRef('idle')
}

Next, we're going to implement a tick function, which will attempt to update the ball's position with every "frame" of our component. This is a rudimentary example of a game loop, if you're familiar with video game development.

const tick = React.useCallback(() => {
  // If the ball is 'idle', then there is nothing to update
  if (ballState.current === 'idle') return

  // Otherwise, set the next position based on the current position
  setPosition(currentPosition => {
    // Every tick subtracts a constant of GRAVITY from the delta change
    delta.current -= GRAVITY
    // The nextPosition is the current position + this change. Rounding is just
    // for making the ground check easier.
    const nextPosition = Math.floor(currentPosition + delta.current)

    // If the ball is on the ground (or below it), set the ball on the ground
    // and update its state
    if (nextPosition <= 0) {
      delta.current = 0
      ballState.current = 'idle'
      return 0
    }

    // Otherwise, return the calculated next position
    return nextPosition
  })
}, [])

Next, we need to handle our "Jump" button's click event.

const handleClick = React.useCallback(() => {
  // This is why clicking multiple times does nothing, if its 'jumping'
  // do nothing
  if (ballState.current === 'jumping') return

  // Otherwise, add the force of the jump to the delta
  delta.current += JUMP_IMPULSE
  // and change the ball state
  ballState.current = 'jumping'
}, [])

Lastly, we need to set up an effect to run our loop at ~60fps.

React.useEffect(() => {
  // Call `tick` roughly 60 times a second
  const id = setInterval(tick, 1000 / 60)

  // Clean it up if `tick` changes or we unmount the component
  return () => clearInterval(id)
}, [tick])

Here is the component in its entirety now:

function JumpingBall() {
  const [position, setPosition] = React.useState(0)
  const delta = React.useRef(0)
  const ballState = React.useRef('idle')

  const tick = React.useCallback(() => {
    if (ballState.current === 'idle') return

    setPosition(currentPosition => {
      delta.current -= GRAVITY
      const nextPosition = Math.floor(currentPosition + delta.current)

      if (nextPosition <= 0) {
        delta.current = 0
        ballState.current = 'idle'
        return 0
      }

      return nextPosition
    })
  }, [])

  const handleClick = React.useCallback(() => {
    if (ballState.current === 'jumping') return

    delta.current += JUMP_IMPULSE
    ballState.current = 'jumping'
  }, [])

  React.useEffect(() => {
    const id = setInterval(tick, 1000 / 60)

    return () => clearInterval(id)
  }, [tick])

  // ... and our UI is returned down here
}

Sub-optimal elements of our code

Looking at this code, I see a few things that I think are sub-optimal, but very common in codebases, that we can improve.

The primary issue I see is that we have code that manages the state in two different places, inside of tick and handleClick. In order to understand this code, we'd have to read through both of these functions and understand how they relate to one another. Most worrisome to me is having state modifying functionality directly in the event handler. As silly as it sounds, I'd prefer to see it separated into a state updater function called inside the event handler. Like so:

const tryJump = () => {
  if (ballState.current === 'jumping') return

  delta.current += JUMP_IMPULSE
  ballState.current = 'jumping'
}

const handleClick = () => {
  tryJump()
}

That way if anything else needs to be called with the event handler, such as logging, we don't need to make any changes to the state updating code as well.

If we look deeper and consider the questions I prompted before, we recognize that we answer in the affirmative for several of them. Our state updates depend on the current state and we're updating multiple states at the same time. Let's refactor our code with a useReducer pattern instead.

The refactor

First, let's gather our states into an initialState object.

const initialState = {
  ballState: 'idle'
  delta: 0,
  position: 0,
}

Next, let's write our reducer. I'll start with it essentially empty, and add our events one by one:

const reducer = (state, event) => {
  switch (event) {
    default:
      return state
  }
}

Let's add the CLICK event:

const reducer = (state, event) => {
  switch (event) {
    case 'CLICK': {
      if (state.ballState === 'jumping') return state

      return {
        ...state,
        ballState: 'jumping'
        delta: state.delta + JUMP_IMPULSE,
      }
    }

    default:
      return state;
  }
}

Now let's add our TICK event:

const reducer = (state, event) => {
  switch (event) {
    case 'CLICK': {
      if (state.ballState === 'jumping') return state

      return {
        ...state,
        ballState: 'jumping'
        delta: state.delta + JUMP_IMPULSE,
      }
    }

    case 'TICK': {
      if (state.ballState === 'idle') return state

      const nextDelta = state.delta - GRAVITY
      const nextPosition = state.position + nextDelta

      if (nextPosition <= 0) {
        return initialState
      }

      return {
        ballState: 'jumping'
        delta: nextDelta,
        position: nextPosition
      }
    }

    default:
      return state;
  }
}

Now, let's use them in our component.

function JumpingBall() {
  const [state, dispatch] = React.useReducer(reducer, initialState)

  const tick = React.useCallback(() => {
    dispatch('TICK')
  }, [])

  const handleClick = React.useCallback(() => {
    dispatch('CLICK')
  }, [])

  React.useEffect(() => {
    const id = setInterval(tick, 1000 / 60)

    return () => clearInterval(id)
  }, [tick])
}

Notice how much simpler our event handlers are. Heck, we even discovered we had an event that probably wasn't obvious to us before, TICK. Additionally, there's no logic in multiple functions we have to wrangle. It's all encapsulated within the reducer.

Adding a "double jump" to our ball

A popular video game mechanic is to enable a "double jump", that is, a second upward impulse while the player is jumping. For our case, we want the user to be able to click "Jump" a second time, while the ball is in the "air" and have it jump again. But only one additional time.

If we were still using useState, we'd have to find a way to add this logic inside of the event handler. You can maybe see where this is going. We'd have to add another state to track, and an additional conditional inside of handleClick. It wouldn't be a very organized way to add functionality.

By using useReducer, literally nothing changes about JumpingBall. The event handlers still dispatch the same events. The only thing that changes is our reducer, so let's update it to handle a double jump.

We're going to start by adding another state to track, jumpsRemaining. This way it will be trivial to add a "triple jump" or more if we ever want to in the future. <Marker content="Can you tell I used to be a Hunter main in Destiny?" /> Like so:

const initialState = {
  ballState: 'idle',
  delta: 0,
  jumpsRemaining: 2,
  position: 0,
}

Next, we'll add a check for jumpsRemaining to our CLICK event:

const reducer = (state, event) => {
  switch (event) {
    case 'CLICK': {
      if (state.jumpsRemaining === 0) {
        return state
      }

      return {
        ...state,
        ballState: 'jumping',
        delta: state.delta + JUMP_IMPULSE,
        jumpsRemaining: state.jumpsRemaining - 1,
      }
    }

    // ...
  }
}

Lastly, we need to update our TICK event to update jumpsRemaining when we hit the "ground".

// Not a mistake, purposely empty

Wait! There's nothing to update. It's already handled by setting state to initialState when the ball hits the ground. Yet another benefit of using a reducer is that occasionally we can update multiple states in one fell swoop by resetting it to initialState (or some other permutation of the state object).

Now let's see how our ball double jumps!

If you time it right, you can send the ball flying off the canvas. Pretty cool how easy that change was to make.

Summary

useReducer may seem like overkill, but is an absolutely great tool in the right situation. It can drastically reduce the complexity of our event handlers, while also organizing our state managing code into a single place. Hope this post helps you in choosing which state primitive to use in the future.

As always, you can find the full code for the JumpingBall (with both state management patterns) by viewing the source code on Github. Look for the why-use-use-reducer directory under published posts.

Patterns for Functions with Conditionals

Tue, 24 May 2022 00:00:00 GMT

Recently, a tweet about wrapping for loops into functions <Marker content="And my consequent reply to it." /> inspired me to write a (hopefully) brief blog post on two common function patterns I use to handle conditional logic. Knowing how to write each pattern and knowing when to one or the other will help you wrangle complexity in your programs.

In the past, I've written about complexity and managing it, and one of the ways I believe we can do this effectively is through patterns. Now, I don't think these patterns are revolutionary. They've been around for a ages and I'm not trying to take credit for them. That said, no one taught me these patterns in clear and succinct terms when I was learning to program either. My hope is to do that for you.

The “Single Mutable `result`” pattern

The first pattern we're going to cover I call the "single mutable result" pattern. This function establishes a result variable, conditionally mutates it, and returns it. The skeleton of it looks like this:

function singleMutatedResult() {
  let result // = some default value

  if (condition1) {
    // result = some transformation or replacement
  }

  if (condition2) {
    // result = some other transformation or replacement
  }

  return result
}

This pattern is most useful when writing algorithmic code with conditions that transform the result. I think of them as additive requirements, as in, "If this condition exists, we make this additional change". An example of this might be a function that calculates the total cost of an online purchase, like so:

function getTotalCost(price, quantity, tax, shipping) {
  let result = price * quantity

  if (tax) {
    result = result + result * tax
  }

  if (shipping) {
    result = result + shipping
  }

  return result
}

Notice that as we read the code, each condition leads to a transformation of the code, but we maintain the same result variable the whole time. At any place in the algorithm, we can log out result and get an idea of what we need to change to achieve the result we're looking for.

The “Early Exit” pattern

This is essentially the opposite of the "single mutable result" pattern, but is very useful for code that has "short circuits". The "early exit" pattern uses guard clauses in order to return as soon as possible from the function. Here is the skeleton of this pattern:

function earlyExit(...args) {
  if (condition1) return result1
  if (condition2) return result2

  // Do the work to calculate our final result and return it
  return result3
}

The "early exit" pattern is great for conditional code that may involve missing information or restricted access, situations where we can bail out of the function before doing other calculations. A practical example might be deriving a user's name from a user object.

function getUserName(user) {
  if (!user) return null
  if (user.nickname) return user.nickname

  const [firstName] = user.fullName.split(' ')

  return firstName
}

In this example, if the user doesn't exist, we can "short circuit" the function and exit early with a null value. The next condition we can use to exit early is if the user.nickname is set. Otherwise, we do the work of deriving the firstName from the user. The "early exit" pattern is great for code where we never want to do more work than absolutely necessary to get the desired result.

I think there are some characteristics of this pattern that are worth taking notice of. First, the guard clauses tend to be so succinct that I like to write them on a single line. Second, I have learned that some people struggle with code with early returns. Some languages don't allow/recommend it, so be gentle with people who struggle with this pattern. Teach them the benefits of avoiding unnecessary calculations and they'll come around.

What If...

Now, I want to be clear, both examples could be written with the other pattern, but they'd be awkward. I'm going to write them out, just to demonstrate. Let's get our total cost again, but with the "early exit" pattern.

function getTotalCost(price, quantity, tax, shipping) {
  const initialCost = price * quantity

  if (!tax && !shipping) return initialCost
  if (tax && !shipping) return initialCost + initialCost * tax
  if (!tax && shipping) return initialCost + shipping

  // Logically this is tax && shipping
  return initialCost + initialCost * tax + shipping
}

Using the "early exit" pattern with this code had us repeating ourselves over and over. We even had to add another conditional since we couldn't just skip the algorithmic step if it didn't apply.

Now, let's use "single mutable result" with our user's name.

function getUserName(user) {
  let result = null

  if (user) {
    result = user.fullName.split(' ')[0]
  }

  if (user?.nickname) {
    result = user.nickname
  }

  return result
}

Using the "single mutable result" pattern to get our user's name results in some very awkward transformations. Assuming we have a user, we always have to calculate the firstName even if ultimately we don't use it. Why? Because the nickname supersedes the firstName and thus must overwrite the result value last. We also have to use the "optional chaining" operator, ?., because we still can't be sure if we even have a user by the time we hit that condition. Lastly, it can be difficult to reason that between the setting of result to null and all those transformations that if result is still null, it means we have no user. It's much clearer in the "early exit" example.

Summary

Writing conditional code can be challenging. Using the right pattern for the right reasons can make that challenge a lot easier. Get comfortable writing code with both patterns and you'll see an improvement in the quality of your code.

Remember, the "single mutable result" is great for algorithmic code with transformational requirements. "If this condition is true, transform result to this new value". The "early exit" pattern is great for code with short circuits. "If this condition is true, bail out with this value".

Both are useful, and both have their place.

Updating State with a Component

Thu, 05 May 2022 00:00:00 GMT

import Example from './_Example.astro'

Have you ever wanted to create a component like Head from next/head or Helmet from react-helmet that would update some state by using the children of a component? It's simpler than you might think.

A while back, I was working with a design that had an h1 heading in the middle of the header. Like this:

It's a bit of an odd design, but it's what they wanted. The challenge of the design is that the heading element has to live within the <header> of the app, but the component code we'll be writing is for the area labeled Page Content. There's a literal border (pun intended) between the content we're creating and the place we need to update the heading.

Now, one way to solve this is to use a Header component with a prop for the heading, or potentially with children so you could compose Header with the correct page title. Perhaps like this:

function Header({ children }) {
  return (
    <header
      style={{
        display: 'flex',
        justifyContent: 'space-between',
        // In order to center the heading regardless of other items in the
        // header, we'll need to absolutely position it
        position: 'relative',
      }}
    >
      <Logo />
      <h1
        style={{
          position: 'absolute',
          left: '50%',
          transform: 'translateX(-50%)',
        }}
      >
        {children}
      </h1>
      <Nav />
    </header>
  )
}

// Then used like so:
function SomePage({ children }) {
  return (
    <div>
      <Header>This page's title</Header>
      <main>{children}</main>
    </div>
  )
}

The downside of this approach is that we would have to use Header in every single page in the application. That's not ideal. It would be preferable to have Header in a layout component higher up in the component hierarchy, used only a few times. It would be pretty easy to forget some important piece of the app layout on a page this way.

While this might be the most common approach to solving the problem, there are alternatives. The next approach to try would be to use React Context and a custom hook. I cover this in my article How to Use React Context Effectively, so check it out when you have a chance.

In this approach, we'd setup a context and export a hook we can use to update that context. Let's do that briefly, since it will be useful for the next part of this post as well:

// Create the context
const HeadingContext = React.createContext()

// Create our provider
function HeadingProvider({ children }) {
  const [heading, setHeading] = React.useState('')

  return (
    <HeadingContext.Provider value={{ heading, setHeading }}>
      {children}
    </HeadingContext.Provider>
  )
}

// Custom hook for consuming the context
const useHeadingContext = () => React.useContext(HeadingContext)

// Hook specifically for updating the heading
// Name provides a little more context where it gets used
const useUpdateHeading = value => {
  const { setHeading } = useHeadingContext()
  setHeading(value)
}

// Now our header consumes the `heading` value (let's assume that
// the `HeadingProvider` is higher in the tree)
function Header() {
  const { heading } = useHeadingContext()

  return (
    <header>
      <Logo />
      <h1>{heading}</h1>
      <Nav />
    </header>
  )
}

// And then we would update that heading like so
function SomePage({ children }) {
  useUpdateHeading("This page's title")

  return (
    <div>
      <main>{children}</main>
    </div>
  )
}

This is reasonable. I certainly wouldn't stop anyone from doing this approach, but it feels off to me personally. I experience a bit of a disconnect here. This hook feels like an unrelated function, used arbitrarily and doesn't connect to the rest of the code in the component in a cohesive way. Admittedly, how I instinctively respond to some code is not a strong argument for anything, so as I said before, I wouldn't stop my team from doing this approach, but is there an alternative?

There is. We can use that same context and a component to create a composable state updater. All we need to do is make use of children. Here's one way of doing that. <Marker content="There are quite a few ways you could manipulate <code>children</code> to suit your needs." />

const ACCEPTABLE_TYPES = ['string', 'number']

function Heading({ children }) {
  const { setHeading } = useHeadingContext()

  React.useEffect(() => {
    if (ACCEPTABLE_TYPES.includes(typeof children)) {
      setHeading(children)
    }
  }, [children, setHeading])

  return null
}

// Now we can use that component _anywhere_ to update the heading
function SomePage({ children }) {
  return (
    <main>
      <Heading>This page's title</Heading>
      {children}
    </main>
  )
}

Now, we use a renderless component and an effect to keep the page title synced up. We've also created a component that conveys some semantics to someone reading the code. In the case of the design, Heading really is the heading for the page, it's just at a distance to us in the DOM. Using this semantic component let's our code feel cohesive without negatively impacting the actual layout of the app.

You can experiment with other ways to utilize children to achieve this effect. Just be sure to sanitize children in some way. You may want to look into the React.Children API if you do. Otherwise, enjoy adding this little trick to your coding repertoire.

Conway's Game of Life

Thu, 03 Feb 2022 00:00:00 GMT

import GameOfLife from './_GameOfLife'

In a previous post, The Simulation Pattern, I mentioned Conway's Game of Life. In this post, we're going to implement it using the simulation pattern.

The Game of Life is about cellular automata, that is, how do individuals governed by a set of rules interact in a system. In this case, the individuals are the cells that make up a 2-dimensional grid.

The game is a simulation because it advances in discrete increments. During each tick, our cells may or may not change their state. Let's go over those states and the rules that govern the cellular behavior.

Each cell can be in one of two states: alive or dead. Cells die or reanimate based on a set of conditions. Those are:

An alive cell with fewer than 2 neighbors dies
An alive cell with 2 or 3 neighbors lives
An alive cell with 4 or more neighbors dies
A dead cell with exactly 3 neighbors reanimates

Given those rules, we can start to write the code that meets that criteria. I'm going to use JavaScript & React, but I encourage you to try and write this in all sorts of languages and frameworks. It can be a lot of fun to explore a familiar problem in different ways.

Let's create the shell of our simulation's factory function. Our initial state will be a 2-dimensional array of 10 rows and 10 columns, and every value will be false.

// Creates a 10 x 10 2d array of falses
const initialState = Array(10)
  .fill()
  .map(() => Array(10).fill(false))

function createGameOfLifeSim() {
  let state = initialState

  return {
    tick() {},
    getState() {
      return state
    },
  }
}

Next, we need to encode the Game of Life rule's inside our tick method. Because we frequently need to get a cell's neighbors, let's write a function that manages that functionality. Since this function needs access to the current state, we can write it in the closure of our factory function:

function createGameOfLifeSim() {
  let state = initialState

  function getNumberOfNeighbors(rowIdx, colIdx) {
    const neighborIndices = [
      [rowIdx - 1, colIdx - 1],
      [rowIdx - 1, colIdx],
      [rowIdx - 1, colIdx + 1],
      [rowIdx, colIdx - 1],
      [rowIdx, colIdx + 1],
      [rowIdx + 1, colIdx - 1],
      [rowIdx + 1, colIdx],
      [rowIdx + 1, colIdx + 1],
    ]

    const neighbors = neighborIndices
      .map(([row, col]) => state?.[row]?.[col])
      .filter(Boolean).length

    return neighbors.length
  }

  return {
    tick() {},
    getState() {
      return state
    },
  }
}

I think it's worth examining this function briefly. To start, we create an array of neighborIndices. These are the row and column indexes we will use to retrieve the neighbor values from the state grid.

Next, we want to determine how many neighbors have the value true. To do this, we map over the neighborIndices. Cells that are on the edge of our grid will create neighborIndices outside the bounds of our grid, and so we use optional chaining, the ?. you see there, to avoid errors that come from trying to access non-existent values.

After that, it's your basic filter(Boolean), making use of pointfree programming, to only get trues and then the length.

Now that we can efficiently get the number of alive neighbors a cell has, we can write the conditional logic to determine the next state.

return {
  tick() {
    const nextState = state.map((row, rowIdx) => {
      return row.map((cell, colIdx) => {
        const neighbors = getNumberOfNeighbors(rowIdx, colIdx)

        // A dead cell only reanimates with exactly 3 neighbors
        if (!cell) return neighbors === 3

        // An alive cell only stays alive with 2 or 3 neighbors
        switch (neighbors) {
          case 2:
          case 3:
            return true
          default:
            return false
        }
      })
    })

    state = nextState

    // Will allow us to chain .getState() after a call to .tick()
    return this
  },
}

I've divided the logic into two sections: a guard and early return when the cell is dead, and a small switch when the cell is alive. I often prefer to use switches because they are similar to pattern matching, and in this case, the fallthrough works to our benefit.

This is the crux of our simulation. The full code should look like this so far:

// Creates a 10 x 10 2d array of falses
const initialState = Array(10)
  .fill()
  .map(() => Array(10).fill(false))

function createGameOfLifeSim() {
  let state = initialState

  function getNumberOfNeighbors(rowIdx, colIdx) {
    const neighborIndices = [
      [rowIdx - 1, colIdx - 1],
      [rowIdx - 1, colIdx],
      [rowIdx - 1, colIdx + 1],
      [rowIdx, colIdx - 1],
      [rowIdx, colIdx + 1],
      [rowIdx + 1, colIdx - 1],
      [rowIdx + 1, colIdx],
      [rowIdx + 1, colIdx + 1],
    ]

    const neighbors = neighborIndices
      .map(([row, col]) => state?.[row]?.[col])
      .filter(Boolean).length

    return neighbors.length
  }

  return {
    tick() {
      const nextState = state.map((row, rowIdx) => {
        return row.map((cell, colIdx) => {
          const neighbors = getNumberOfNeighbors(rowIdx, colIdx)

          // A dead cell only reanimates with exactly 3 neighbors
          if (!cell) return neighbors === 3

          // An alive cell only stays alive with 2 or 3 neighbors
          switch (neighbors) {
            case 2:
            case 3:
              return true
            default:
              return false
          }
        })
      })

      state = nextState

      return this
    },
    getState() {
      return state
    },
  }
}

I want to add two more methods that will be useful for us when we build our UI: a randomize method and a toggleCell method. First, randomize:

const randomBool = () => Boolean(Math.round(Math.random()))

//... inside our factory function
return {
  //... the return of our sim
  randomize() {
    state = state.map(row => row.map(randomBool))
    return this
  },
}

With randomize, we generate a completely random grid of trues and falses. Next, let's write toggleCell. This will allow a user to click on a cell and toggle its state.

return {
  //... the return of our sim
  toggleCell(rowIdx, colIdx) {
    state[rowIdx][colIdx] = !state[rowIdx][colIdx]
    /**
     * Because React requires immutable changes to know that
     * state has updated, we're going to clone the current state
     * in order to create an immutable update
     *
     * It's a pain in the butt, but it's what we gotta do
     *
     * Alternatives would be creating/using a clone util or
     * a package like Immer
     */
    state = state.map(row => row.map(x => x))
    return this
  },
}

Now with those extra methods in place, we can build our UI. Because we've built our sim as a plain object with state held in closure, we can use it with whatever framework (or lack thereof) that we want. We just have to adapt it to the framework. That said, adapting it can result in some strange patterns. We'll see that as we make this work with React.

Let's start with our basic markup and build up the functionality of our UI. I'm going to use inline styles for the sake of simplicity, but use whatever styling method you prefer:

function GameOfLife() {
  const grid = [] // just a placeholder, will eventually be stateful

  return (
    <div style={{ display: 'flex', justifyContent: 'center' }}>
      {/* Our grid */}
      <div>
        {grid.map((row, rowIdx) => {
          return (
            <div key={rowIdx} style={{ display: 'flex' }}>
              {row.map((cell, colIdx) => {
                return <button key={colIdx} onClick={() => {}} type="button" />
              })}
            </div>
          )
        })}
      </div>
      {/* Our actions */}
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <button onClick={() => {}} type="button">
          Start
        </button>
        <button onClick={() => {}} type="button">
          Randomize
        </button>
      </div>
    </div>
  )
}

Now that we have our basic UI, let's add our simulation to the component. We want to have a single simulation for the lifetime of our component. The simplest way to do this is with useRef. However, as I've written about before in Comparing useRef and useState, changes to a ref will not cause our component to update, so we'll need a useState as well. Here's how we're going to make that happen:

function GameOfLife() {
  const simRef = React.useRef(createGameOfLifeSim())
  const [grid, setGrid] = React.useState(simRef.current.getState())

  //... the rest of the component
}

Now, whenever we make an update to our sim, we'll have to use setGrid on the new state to update our UI. Bit of a pain, but manageable.

Let's build out some of the UI functionality next. The primary function we need to add next is the button that starts and stops our simulation. What good is the Game of Life if it never ticks?

To do this, we're going to use an effect that will call tick on an interval while the game is running, and stop when the game is paused. We can set that up like this:

const INTERVAL = 150

function GameOfLife() {
  const simRef = React.useRef(createGameOfLifeSim())
  const [grid, setGrid] = React.useState(simRef.current.getState())
  const [gameState, setGameState] = React.useState('paused')

  React.useEffect(() => {
    // If the game is paused, the effect should do nothing
    if (gameState === 'paused') return

    // Otherwise, setup the interval...
    const intervalId = setInterval(() => {
      // Because refs and state setters are stable across renders,
      // none of these need to be included as dependencies of the effect
      setGrid(simRef.current.tick().getState())
    }, INTERVAL)

    // ...and clean it up
    return () => {
      clearInterval(intervalId)
    }
  }, [gameState])

  // Our handling function for toggling the state of the game
  const handleGameStateToggle = React.useCallback(() => {
    setGameState(s => (s === 'paused' ? 'running' : 'paused'))
  }, [])

  return (
    //... most of the UI
    <button onClick={handleGameStateToggle} type="button">
      {gameState === 'paused' ? 'Start' : 'Stop'}
    </button>
    //... the rest of the UI
  )
}

Our game is ready to run, but all the cells are dead so nothing will happen. Let's make use of our randomize and toggleCell methods from before so we can change the state of our cells.

function GameOfLife() {
  //...
  const handleRandomize = React.useCallback(() => {
    setGrid(simRef.current.randomize().getState())
  }, [])

  // Pay attention here, we're going to use a higher order function so that
  // we can partially apply the rowIdx and colIdx values
  const handleToggleCell = React.useCallback(
    (rowIdx, colIdx) => () => {
      setGrid(simRef.current.toggleCell(rowIdx, colIdx).getState())
    },
    [],
  )

  return (
    <div>
      //...then in the cell button UI
      <button
        key={colIdx}
        onClick={handleToggleCell(rowIdx, colIdx)}
        type="button"
      />
      //...then in our actions UI
      <button onClick={handleRandomize} type="button">
        Randomize
      </button>
    </div>
  )
}

Now we have all the pieces for our Game of Life. Your component code should look something like this:

const INTERVAL = 150

function GameOfLife() {
  const simRef = React.useRef(createGameOfLifeSim())
  const [grid, setGrid] = React.useState(simRef.current.getState())
  const [gameState, setGameState] = React.useState('paused')

  React.useEffect(() => {
    if (gameState === 'paused') return

    const intervalId = setInterval(() => {
      setGrid(simRef.current.tick().getState())
    }, INTERVAL)

    return () => {
      clearInterval(intervalId)
    }
  }, [gameState])

  const handleGameStateToggle = React.useCallback(() => {
    setGameState(s => (s === 'paused' ? 'running' : 'paused'))
  }, [])

  const handleRandomize = React.useCallback(() => {
    setGrid(simRef.current.randomize().getState())
  }, [])

  const handleToggleCell = React.useCallback(
    (rowIdx, colIdx) => () => {
      setGrid(simRef.current.toggleCell(rowIdx, colIdx).getState())
    },
    [],
  )

  return (
    <div style={{ display: 'flex', justifyContent: 'center' }}>
      <div>
        {grid.map((row, rowIdx) => {
          return (
            <div key={rowIdx} style={{ display: 'flex' }}>
              {row.map((cell, colIdx) => {
                return (
                  <button
                    key={colIdx}
                    onClick={handleToggleCell(rowIdx, colIdx)}
                    type="button"
                  />
                )
              })}
            </div>
          )
        })}
      </div>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <button onClick={handleGameStateToggle} type="button">
          {gameState === 'paused' ? 'Start' : 'Stop'}
        </button>
        <button onClick={handleRandomize} type="button">
          Randomize
        </button>
      </div>
    </div>
  )
}

The only thing left for you to do is tweak some styles. Specifically, you should play around with the buttons for each cell. Style them based on their current state. Have fun with it and see what you come up with.

Here's a version of our game right here. Click randomize and get the simulation started:

Recap

The Game of Life is an interesting exercise that can use the simulation pattern. It's a great starting point for learning cellular automata. Change the rules, build it in other languages and frameworks, explore to your heart's content.

The Simulation Pattern

Fri, 28 Jan 2022 00:00:00 GMT

Disclaimer: If this pattern has an established name, let me know. I'll update the article to reflect that.

In December, <Marker content="And some of January..." /> I participated in Advent of Code. It was mostly fun, but I did have some extremely difficult days. If you follow me on Twitter, you know of my travails with day 19. Oof.

That said, there was a common pattern I used to solve several of the puzzles that I want to share with you. I call it the "simulation pattern" and if I hadn't tried to learn the tiniest amount of game dev a few years back, I may have never learned it. Thus, I want to pass it on to you in the hopes you find it useful.

What is a “simulation”?

A "simulation", in my own words, is where we create some conditions and store some state, and then add a tick method to advance that state to the next discrete increment. Conway's Game of Life is an excellent example of a simulation and I encourage you to take this pattern and try to build Conway's Game of Life with it when you're done reading this post.

The pieces of the pattern

In its most basic form, a simulation is a closure which exposes a tick method to advance to the next state. Using a factory function, it looks like this:

function createSimulation(initialState) {
  let state = initialState

  return {
    tick() {
      // Add functionality to update state
    },
    getState() {
      return state
    },
  }
}

const sim = createSimulation()
sim.tick()
sim.getState()

We create a function that holds our state in closure. We add functionality in our exposed tick method to advance the state, and we create a way to access the current state with getState. All simulations are some variation of this pattern.

Let's create a simple example to demonstrate this. All of us have to deal with money in some capacity, so a loan payoff calculator can be a useful tool to have. We can create a simulation that takes in a principal, an interestRate, and expose a tick method that receives a payment to determine how many payments are necessary to pay off a loan.

First, let's create our factory function:

function createLoanPayoffSimulation(principal, interestRate) {
  let total = principal

  return {
    tick(payment) {
      const interest = total * interestRate

      if (payment <= interest) {
        throw new Error('Impossible to pay off loan. Increase payment amount.')
      }

      const diff = interest - payment
      total += diff

      return this
    },
    getTotal() {
      return total
    },
  }
}

// Dividing by 12 gives us a monthly interest rate
const sim = createLoanPayoffSimulation(10000, 0.05 / 12)

Now that we have our simulation, we can create a function that uses a simulation to determine how many payments are needed to payoff the loan.

function getTotalPayments(payoffSimulation, payment) {
  let payments = 0
  let paid = false

  while (!paid) {
    payoffSimulation.tick(payment)
    payments++

    const total = payoffSimulation.getTotal()
    paid = total <= 0
  }

  return payments
}

console.log(getTotalPayments(sim, 500)) // 21

We can pass different simulations with different conditions into getTotalPayments to solve other loan payoff scenarios.

Now that you've seen the basics, give it a try on some other problems. Or try it on an Advent of Code problem, like this one.

You can also use generator functions to create a similar effect, just with next as the method instead of tick. The difference being that you yield the next state with each run of the function. I make a loan payment calculator in that post as well, so you can hopefully compare the two.

The Wrapped State Setter Pattern

Wed, 19 Jan 2022 00:00:00 GMT

Today, in the process of working on what might potentially become a course on React, I used a pattern that I've found useful from time to time that I want to share with you.

Have you ever wanted to have something happen every time you use setState in React? Perhaps you wanted a way to finagle the nextState or wanted to run a side effect where you store the value in localStorage. We can accomplish this and more with a "wrapped state setter" pattern.

Since my example app for the potential course uses localStorage in lieu of a database, I'll use that for my example code. That said, the pattern is the same regardless of what you use it for, so let's dive in.

Let's say my app stores a collection of notes:

function App() {
  const [notes, setNotes] = React.useState([])
  //...
}

Now, let's add some declarative state updaters that will update our notes. Keep in mind, there are multiple ways to write these updaters. Don't get too focused on the implementation details, just recognize we've written a few. Like so:

function App() {
  const [notes, setNotes] = React.useState([])

  const createNote = note => {
    setNotes(currentNotes => [...currentNotes, note])
  }

  const updateNote = update => {
    setNotes(currentNotes => {
      const index = currentNotes.findIndex(note => note.id === update.id)

      if (index < 0) return currentNotes

      return [
        ...currentNotes.slice(0, index),
        { ...currentNotes[index], ...update },
        ...currentNotes.slice(index + 1),
      ]
    })
  }

  const deleteNote = id => {
    setNotes(currentNotes => {
      const index = currentNotes.findIndex(note => note.id === id)

      if (index < 0) return currentNotes

      return [...currentNotes.slice(0, index), ...currentNotes.slice(index + 1)]
    })
  }

  //...
}

Now, let's say that we want to store these changes to notes in localStorage every time we make an update. What is the simplest way to do this?

If we look at all our declarative updaters, they all make a call to setNotes. If we had a way to change setNotes, we could make this happen. This is where the "wrapped" part of the title comes in.

We're going to create a function that will call the current setNotes and use it to provide ourselves with a seam in which to extend the current behavior. Let's wrap it up, like so:

const wrappedSetNotes = React.useCallback(update => {
  // Call the original state setter, use the function updater to get the current state
  setNotes(currentNotes => {
    // Determine the nextState
    const nextState =
      typeof update === 'function' ? update(currentNotes) : update

    // This is where we extend the functionality
    localStorage.setItem(YOUR_LOCAL_STORAGE_KEY, JSON.stringify(nextState))

    // We preserve the existing functionality
    return nextState
  })
}, [])

And then every where we previously called setNotes, we update to wrappedSetNotes:

const createNote = note => {
  wrappedSetNotes(currentNotes => [...currentNotes, note])
}

const updateNote = update => {
  wrappedSetNotes(currentNotes => {
    const index = currentNotes.findIndex(note => note.id === update.id)

    if (index < 0) return currentNotes

    return [
      ...currentNotes.slice(0, index),
      { ...currentNotes[index], ...update },
      ...currentNotes.slice(index + 1),
    ]
  })
}

const deleteNote = id => {
  wrappedSetNotes(currentNotes => {
    const index = currentNotes.findIndex(note => note.id === id)

    if (index < 0) return currentNotes

    return [...currentNotes.slice(0, index), ...currentNotes.slice(index + 1)]
  })
}

Now, any updates that we make to notes will have the side effect of updating the value in localStorage.

There are other ways to use this pattern. If you've ever heard of the "state reducer pattern", that's an example of wrapping the state setter.

This pattern also doesn't have to be just for state setters. If ever you find yourself with a function that you want to add some functionality to, you might be able to simply wrap it in a function, and add your functionality in the function body. Try it out, see if it works.

Parametric Design

Tue, 18 Jan 2022 00:00:00 GMT

import ColorPicker from './_ColorPicker' import ResizableBox from './_ResizableBox' import FullSpiro from './_Spirograph'

This will be short and to the point. Yesterday, I tweaked the button styles on my blog. At the time I'm writing this, the buttons have multiple box shadows to create what I hope is an interesting effect. In the process of getting the shadows "correct", I employed "parametric design". I believe parametric design is a valuable concept for developers to know and apply, <Marker content="<em>Especially</em> if you're like me and not a very gifted designer." /> and I want to make sure it's a part of your vocabulary.

Parametric design is the process of using adjustable parameters to modify and influence a design. In other words, we turn the values and relationships between values into functions. Then, we wire up inputs to pass new arguments to them to get immediate feedback on the outcome.

It can be very simple, like choosing a color:

Or perhaps the width and height of an item:

To something more complex, like generative art:

Parametric design is the foundation of so many dev and design tools that it's incredibly likely you've encountered it without even knowing it. Wiring up inputs to provide immediate feedback can be a very satisfying way to experiment and solve problems.

It's also a wonderful tool for non-coders. Good inputs can be a way of empowering them to solve their own problems.

Parametric design is fundamentally about exploring. Next time you're building something and you're not quite sure what it should be, consider wiring up some inputs and see what happens.

The “Folded Code” Test

Mon, 03 Jan 2022 00:00:00 GMT

One underrated feature of code editors is "code folding", the ability to fold a block of code, like this:

I use this feature all the time, and recently, it dawned on me that folding your code might help you write better code.

Why I fold code

When I'm reading code, especially large files, I can find it overwhelming to see lots of code. Even more so when I'm unfamiliar with the code. It's a lot of visual noise and information to take in all at once. In order to reduce this overwhelming sensation, I literally reduce how much code is visible.

If you use VSCode, you can collapse code blocks from the keyboard using "chords". A "chord" is a command that requires multiple key combinations to perform. You can fold up to 9 levels of indentation by pressing cmd + k, followed by cmd + <number between 1-9>. <Marker content="I work on a Mac, please convert <code>cmd</code> to <code>ctrl</code> if you are a Windows user." /> The number you press is the level depth of the collapse. You can un-collapse all levels by performing cmd + k, then cmd + 0.

Often, when I open up a large file, I'll start by hitting cmd + k, then cmd + 1 or cmd + 2 to reduce how much code I can see. This allows me to view the file at a higher level. It's seeing the code "forest" and ignoring the details of the code "trees" for a moment.

Looking at code from this vantage point, where much of the implementation details are hidden, begs us to ask a key question: does the code still describe its purpose at this level?

I believe <Marker content="Yes, this is my <em>opinion</em>" /> code that is easy to read, understand, and maintain will also be easy to follow at each level you fold. When you fold it to a level where it's unclear what happens inside the block, you may have an opportunity to refactor and improve the code.

I can think of two strong examples where the "folded code" test can be seen in action. First, tests.

Think about a block of tests, as we unfold it, we get a more detailed view of the forest. A completely folded test might only say:

describe('Stack', () => {})

We know that this tests something called Stack, which gives us some indication of what we might expect. Unfolding a layer reveals more detail:

describe('Stack', () => {
  it('should make a new stack', () => {})
  it('should add an item to the stack', () => {})
  it('should pop off the top item from the stack', () => {})
  it('should indicate when the stack is empty', () => {})
})

And if we go further, we'd see the implementation details of those tests (I'll spare you that for now).

On the flip side, the second example is the corollary to these tests, the class that we're testing.

Now, I often prefer factory functions and think that you can see the same benefits of code folding when writing them, but I believe more people are familiar with classes. Perhaps not in JavaScript, but if you have a background in other languages.

If we were to write a Stack class, going layer by layer, you will see that each level of folding reveals more about it:

class Stack {}

Next, we start to reveal the API of the Stack:

class Stack {
  constructor() {}
  push(item) {}
  pop() {}
  isEmpty() {}
}

At this level, we've revealed what the public API of the class is. If this were a more complicated object, we'd also have some idea of the protected or private API as well. At the next level, we can see some of the implementation details.

class Stack {
  constructor() {
    this.stack = []
  }
  push(item) {
    this.stack.push(item)
  }
  pop() {
    return this.stack.pop()
  }
  isEmpty() {
    return this.stack.length === 0
  }
}

Now, you'll have to use your imagination a bit to apply this principle/test <Marker content="Honestly, I don't know what it is. Just a thought that's been in my brain for a few months." /> to your work. The stuff you work on day to day is far more complex than I can fit in an example, but I hope you're getting the gist of what I'm getting at. If you can improve how well your code reads at each level it's folded, you're probably writing code that you and your colleagues can update and maintain easily in the future.

Summary

Code folding is a way to reduce visual noise and get a higher level perspective on a module's functionality. Strive to make your code understandable even when it's folded through the use of good structure and descriptive variable and function names. Use this "test" as a way to gauge how well you're communicating the intention of your code to your colleagues and future self.

My Course Platform

Mon, 29 Nov 2021 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

So I had a wild idea a while back now:

<SocialPost authorName="Kyle Shevlin" authorHandle="@kyleshevl.in" authorProfile="https://bsky.app/profile/kyleshevl.in" avatarUrl="https://cdn.bsky.app/img/avatar/plain/did:plc:h4qem3f3cz6yvs3r3xvs634g/bafkreig7fzbknganveoij56depkm4dxax3yo2cudxf6mase23vccmqn5xa@jpeg" date="2021-06-14" content={` I'm starting a new project today. I'm going to build a mini-course on Array.reduce()!

I've seen a lot of confusion about this method, and I'd like to help people out.

For added difficulty, I'm going to try and get it done in just a week. `} />

You may have noticed that it's been a little more than a week since I wrote that tweet. 😅

There were a number of reasons that happened, but the main culprits were my estimate was way off, <Marker content="Classic." /> and burnout & depression hit me pretty hard this summer and fall. <Marker content="Shit happens. No need to hide that. Don't let it stop you permanently. Get help if you need it." />

But we're here now! Despite the challenges, the first version is built and ready for the world. Is it the greatest course platform the world has seen? Absolutely not. Could it use dozens of improvements? Hell yeah. But it's here, and I am proud of that.

For the rest of this post, I want to answer some common questions I imagine people will ask me about courses.kyleshevlin.com.

Why did you build it?

The biggest reason is to have control over how the content is created and released. Working with other course platforms has been great and very worthwhile, but I have had my struggles with timing and format. There have been weeks where I worked 16+ hours a day to get the content ready in time. By building a platform of my own, I get to write courses exactly how I would like to and publish them when I want to, for better or for worse.

I write my blog using MDX and will be writing all the lessons on my course platform with it, too. It makes it super easy for me to add code snippets as well as fun, little interactive React components right in the middle of my writing. It has become my favorite way to write long form content.

Another reason is just to prove I can do it. I've never really taken making serious money into my own hands. I don't expect this to make me rich by any means, but proving to myself that I'm capable of creating value of my own accord means something to me. I'm not highly motivated by business, by money, by growth, so attempting to do this is a big step out of my comfort zone. It's attempting to do something I don't find natural, but believe I am capable of doing and it will benefit my family's life.

How did you build it?

If you look into the tweet thread, I explain in some detail how I got started. I literally copied the code of this blog into a new directory and started ripping out the bits I didn't need and building the bits I did need. I wanted my branding to be consistent from kyleshevlin.com and courses.kyleshevlin.com. Eventually, I'll probably create a shared component library for the two apps.

So, to be specific, it's built with Gatsby <Marker content="It's still on v2, ha. I have to find time to do the upgrade all the way to v4." /> Here are some of the other pieces of the tech stack:

Supabase for my database & auth
Stripe for payments
Netlify for deploys & serverless functions
Emotion for my styling
MDX for my authoring
Vimeo for my video hosting

Some of this may change as time goes by, but for me, this was the simplest way I could get started, and I'm a big fan of keeping things simple.

What courses are you offering?

Right now, only the course on Array.reduce() will be available. I have started planning some additional courses to make next. Please feel free to send me a tweet with course suggestions.

Are there any "extras" that come with the course?

Yes. When you purchase a course, you'll get an invite to my private Discord server so that you can ask me questions about the material and get help from other people learning the material.

Will your egghead courses be on your platform?

The short answer is no. They will remain on egghead for as long as they will have them there. If those topics find their way on to this platform, it will be done as a revamp of the material. New videos with new written content for each lesson as well.

What are your goals for the platform?

I've never been a goal-oriented person. I think of myself more as a trajectory-oriented person. I try and get my life moving in the direction I want to head and see where it takes me.

To that end, I don't have MRR or DAU goals. Instead, I would like to see the platform have satisfied students. I would like to derive enough income from the platform to pay off my student loans early. I do not anticipate making enough money from it to quit a day job, and I am more likely to view it as a supplemental business.

My trajectory is aimed towards sustainability. Can I make it as simple as possible to make quality content doing a little bit at a time, rather than these all out sprints I've done in the past.

What are your next steps for the platform?

There are two things remaining on my TODO list:

I may shoot a few more videos for the Array.reduce() course for those lessons that currently don't have one
Implement "licenses" so that a business can buy bulk access to a course

After that, I have a few ideas for the next courses. My hope is to keep them very tight and small. Once I have a few products to put out there, I will work on allowing you to buy bundles of courses in some fashion.

What can I do to help?

Thanks for asking. The simplest answers are:

Buy the course if it will help you
Fill out the feedback at the end of the course when you finish it
Share the course with people who could use it
Cheer me on via Twitter

Closing remarks

Thanks for taking the time to read this. I look forward to seeing you over on my course platform and seeing where this journey takes us.

How I Would Use a UI Library

Sat, 06 Nov 2021 00:00:00 GMT

I've recently been working on a project that uses Chakra UI. I've enjoyed using it, for the most part. I've had a few moments that made me go, "Do I want to build my own UI library?" and then immediately snuffed that thought out of existence. Ain't nobody got time for that.

That said, working with Chakra has made me think of an architectural pattern I would be very tempted to employ if I was building the project's design system from the ground up and knew it was going to be a long-living project.

I'll get right to the chase. Here's my idea: for every UI component you're using in the library, create a facade of your own and consume the facade throughout your app. Do not consume the library directly in your features and other component compositions. If I implemented this, I would go so far as to create an ESLint rule that enforced this pattern.

Before I explain all the reasons why, here's a simple facade example. You'll probably think I'm nuts.

import React from 'react'
import { Button as ChakraButton } from '@chakra-ui/react'

export default function Button(props) {
  return <ChakraButton {...props} />
}

I can hear you saying, "Ok, why in the hell would you recommend this, Kyle?" The answer is simple. This creates a lot of flexibility and likely will save me future pain when requirements change at a very low cost now.

"YAGNI! YAGNI! You're Not Gonna Need It!" I hear you scream. Maybe you're right. But I've never worked in a project that lasted a decent amount of time without some upheaval to the UI components.

Here is a short, non-exhaustive list of things you can do easily with this one layer of indirection:

Swap out the library

If you need/want to try a different component library, you can swap out the implementation under the hood without any change to consumers of your UI components (your other developers/teammates). You can make this change component by component. You don't have to do a wholesale, sweeping change.

Add or Restrict `props`

If you want to add props that aren't on the underlying component, you can do so and map them to some functionality. Or you can create useful aliases to props if they would benefit your team.

Also, you can restrict which props can be used in the underlying UI library. Maybe there's some weird prop you just really want to avoid using. All easily done with a layer of indirection.

Rename/Remap `props`

If you ever need to rename/remap a prop because of an update to the component library, you can do so without needing to change every instance of that component throughout your app. No codemods. Just one simple change.

How I would implement this

I would start by making two directories: features and ui. I may need to add this to my React project structure post.

Then, every UI component in my app gets a facade in the ui directory. No exceptions.

Finally, I would implement an ESLint rule preventing the import of any third party UI library into the features directory. Features can only import components from other features or the ui directory.

Downsides

I can think of one downside to this approach. Documentation.

Consuming the UI library directly in your app means you rely solely on the documentation of the UI library. If you use the facade pattern, you have to indicate to your consumers where to find the information they need. This means pointing to the documentation of the implementation details, or writing your own docs to cover them. If you end up adding or restricting props, you're going to need to document how the component is used anyways.

Summary

Give yourself some future flexibility by using a facade between the UI library you're using and your features. The extra work could save you a lot of pain down the line.

What is a Factory Function?

Fri, 05 Nov 2021 00:00:00 GMT

Building upon closures, I want to teach you about "factory functions", too. Factory functions often use closures, so it makes sense to learn them together. So if you don't know what a closure is or need a refresher, I encourage you to read that blog post first.

A factory function is a function that returns a new object. <Marker content="On occasion, it may return some other data structure." /> The key feature of a factory is that its only job is to pump out those items, just like an actual factory.

The simplest factory function returns a static object of keys and values. Ever needed to turn a small list of values into an object? Take that tuple and give it to a factory function, like so:

const createPerson = (name, twitterHandle) => ({
  name,
  twitterHandle: `@${twitterHandle}`,
})

const kyle = createPerson('Kyle', 'kyleshevlin')
console.log(kyle.twitterHandle) // '@kyleshevlin'

That's not all that interesting, but it can be a useful way to generate objects. If you had a long list of person-related tuples like this, you could use createPerson with Array.map to turn them into props for a React component.

const people = [
  ['Kyle', 'kyleshevlin'],
  ['Jane', 'janeDoe12345'],
  ['John', 'johnDoe67890'],
]

function PeopleList() {
  return (
    <ul>
      {people.map(personTuple => {
        const person = createPerson(...personTuple)

        return (
          <li key={person.name}>
            <Person {...person} />
          </li>
        )
      })}
    </ul>
  )
}

This is a great use of a factory function, but let's move on to a more interesting use case.

Replacing Classes with Factories

The place I use factories most often is when I want to return an object with methods but use closures to create private methods and values. Even better, I never have to even think about the this keyword.

When I created my data structures and algorithms course on egghead, I used factory functions to create the data structures. Let's make a createQueue factory to show you how this strategy works.

function createQueue() {
  // Create an array in closure. This is a private variable.
  const queue = []

  // This could have been a private method, if we didn't also want to expose it
  // Notice how simple this is to understand. No need for `this`
  const isEmpty = () => queue.length === 0

  return {
    enqueue(x) {
      queue.push(x)
    },
    dequeue() {
      return queue.shift()
    },
    peek() {
      if (isEmpty()) return undefined
      return queue[queue.length - 1]
    },
    get length() {
      return queue.length
    },
    isEmpty,
  }
}

const queue1 = createQueue()

What's great about this pattern is that it's compatible in every browser. Private fields and private methods for JavaScript classes are widely implemented, but not every where (and never will be).

I recently used this pattern to upgrade my shevyjs package. I was able to have truly private values and functions that I couldn't have back when I originally wrote the code. I highly recommend taking a look at the source code to see a more complex factory function in action.

Composition with Factories

There are 100s of posts out there on the difficulty of building object hierarchies with inheritance. I kind of want to skip that part and jump right to composition. <Marker content="Maybe I'll find the energy to write that post or update this one in the future, but I just don't have it in me right now." />

Let's imagine we're building a game with animal characters. Animals are notoriously difficult to create inheritance hierarchies for because of their diversity and literal exceptionality.

In my game, let's say I want to create Hawk, Penguin and FlyingFish factories. How can I use composition to make this possible?

There are some shared traits with these animals. Hawks and Penguins both have wings, but not FlyingFish. Penguins and FlyingFish both swim, but Hawks don't. While also Hawks and FlyingFish fly, while Penguins don't, despite their wings.

Simply put, inheritance can't help us here. Let's compose our factories:

First, we can make factories that createBirds and createFish, they will create very small objects.

const createBird = () => ({
  hasWings: true,
})

const createFish = () => ({
  hasFins: true,
})

There are more properties we could add, but we should be careful with adding too many to the base object. Next, we can create factories for objects based on what they do. Focusing on what something does, versus what it is is a great way to find these kinds of compositional pieces:

const createFlyer = () => ({
  canFly: true,
  fly(vx, vy, vz) {
    // Do something with the velocities
  },
})

const createSwimmer = () => ({
  canSwim: true,
  swim(vx, vy, vz) {
    // Do something with the velocities
  },
})

Now that we have those, we can create compositions to create our various animal factories easily:

const createHawk = () => ({
  ...createBird(),
  ...createFlyer(),
})

const createPenguin = () => ({
  ...createBird(),
  ...createSwimmer(),
})

const createFlyingFish = () => ({
  ...createFish(),
  ...createFlyer(),
  ...createSwimmer(),
})

Look how clean that is! Ahh, just fills my heart with joy. Imagine trying to do that with classes?

Summary

Factory functions are functions that return objects. We can use factory functions and closures to have private variables and private functions, only exposing what we want to our consumer through the object we return, all while avoiding the this keyword. Factories make for easy composition of values and functionality. Use them when inheritance can't solve your problems.

Careful with Context Composition

Mon, 18 Oct 2021 00:00:00 GMT

import Example1 from './_Example1' import Example2 from './_Example2' import Example3 from './_Example3' import Counter from './_Counter'

Recently, I helped a small team fix a performance issue involving React Context. It was a fairly simple fix that I want to share with you. I'm going to set up the problem, show you the small change we needed to make, and share a small library I made to help you out in the future.

The Problem - Poor composition

To understand this post, we need to establish a shared context (pun intended). We need to understand that whenever state changes in a React app, the component in which the change occurs will be rerendered. That means rerendering all the components that are called in that component's function body. Let's make this clear with some examples. I'm going to create a Box. The background color for Box will change every time it renders. We'll force it to rerender with a forceUpdate function:

import { Button } from './Button'
import Flex from './Flex'
// A spacing helper function from my shevyjs library
// It's an alias of the `baseSpacing` method
// Spacer uses this under the hood
import { bs } from './shevy'
// These can be found on my snippets page
import randomRGB from './snippets/randomRGB'
import useForceUpdate from './snippets/useForceUpdate'

function Box() {
  return (
    <div
      style={{
        backgroundColor: randomRGB(),
        height: bs(4),
      }}
    />
  )
}

function App() {
  const forceUpdate = useForceUpdate()

  return (
    <Flex direction="column" gap={1}>
      <Button onClick={forceUpdate}>Force Update</Button>
      <Box />
    </Flex>
  )
}

And we can see it here:

Perfect. The background color of Box changes every time it's rendered and it rerenders due to a state change. Now, let's add React Context to the mix.

Let's create a Context, Provider, and a custom hook for consuming that context. We're going to use forceUpdate as the only value passed to the Provider.

import React from 'react'

const MyContext = React.createContext()

function MyProvider({ children }) {
  const forceUpdate = useForceUpdate()

  return <MyContext.Provider value={forceUpdate}>{children}</MyContext.Provider>
}

const useMyContext = () => React.useContext(MyContext)

Now, I'm going to purposely make a bad choice, and add a Box component to MyProvider. Notice that Box will now be in the same scope that the state change associated with forceUpdate occurs (because forceUpdate creates a state change inside the useForceUpdate hook).

function MyProvider({ children }) {
  const forceUpdate = useForceUpdate()

  return (
    <MyContext.Provider value={forceUpdate}>
      {children}
      <Box />
    </MyContext.Provider>
  )
}

Now, let's change the App a bit, using our new Context and custom hook.

function Trigger() {
  // Remember that the only value of our context is `forceUpdate`
  // but we purposely want to consume our context at the moment
  const forceUpdate = useMyContext()

  return <Button onClick={forceUpdate}>Force Update</Button>
}

function App() {
  return (
    <MyProvider>
      <Trigger />
    </MyProvider>
  )
}

Now, you will notice that the resulting UI is exactly the same. We have a button on top of a box. Here's the thing to pay attention to: Typically, only consumers of a context will be forced to rerender when the context value updates, but because we made a bad decision and put our Box in the same function that has a state change, it's going to rerender, too. Look at it:

If you're not paying attention, you may be confused why Box is rerendering when it doesn't consume your context, but it all has to do with how we chose to make our composition. Let's fix it now.

The Solution - Only expose `children` in a `Provider`

The problem is we're rendering a component in the same scope as the state change of our context. If we move Box from MyProvider and into our App instead, we'll have the same UI, but Box won't rerender when we click the Trigger.

// No more `Box` in this component
function MyProvider({ children }) {
  const forceUpdate = useForceUpdate()

  return <MyContext.Provider value={forceUpdate}>{children}</MyContext.Provider>
}

function App() {
  return (
    <MyProvider>
      <Flex direction="column" gap={1}>
        <Trigger />
        <Box />
      </Flex>
    </MyProvider>
  )
}

And let's see it in action. Notice, Box will not rerender. Click the Trigger all you want, it will not change.

I assure you, a state change is still occurring, but because Box is not rendered in the scope of the state change, but rather as one of the children of MyProvider, it won't rerender. Our UI is exactly the same in all scenarios so far, but we can see how using the correct composition improves how our app functions.

A More Robust Solution: `react-generate-context`

I'm a believer that if you can put guide rails in place to keep people on a good path, you should use them. When I saw the mistake the team was making, I realized I could build a small package that puts these guide rails in place. Say hello to react-generate-context.

This library is a single function, generateContext, that receives a custom hook to manage the value for your Context and returns to you the Provider and custom hook for that context.

The main feature? Because you don't have direct access to the Provider, you can't put any other components inside of it.

import generateContext from 'react-generate-context'

const [MyProvider, useMyContext] = generateContext(() => {
  const forceUpdate = useForceUpdate()
  return forceUpdate
})

Notice that the function we pass to generateContext is itself a custom hook. We use it to establish the very same value we did before. We can consume useMyContext in Trigger just like before, too.

To make a slightly better example, and the one you'll find if you visit the Github page for it, let's make a Counter:

const useCounterValue = ({ startingCount = 0 }) => {
  const [state, setState] = React.useState(startingCount)
  const handlers = React.useMemo(
    () => ({
      inc: () => {
        setState(s => s + 1)
      },
      dec: () => {
        setState(s => s - 1)
      },
    }),
    [],
  )

  return [state, handlers]
}

const [CounterProvider, useCounter] = generateContext(useCounterValue)

function Counter() {
  const [count, { inc, dec }] = useCounter()

  return (
    <div>
      <div>{count}</div>
      <div>
        <button onClick={inc}>+</button>
        <button onClick={dec}>-</button>
      </div>
    </div>
  )
}

function App() {
  return (
    <CounterProvider startingCount={100}>
      <Counter />
    </CounterProvider>
  )
}

And here it is in action:

Using this package, it's impossible to screw up your Provider in a way that creates unnecessary rerenders for components. That's a win in my book.

Summary

Resist any urge to put other components in the scope of your custom Provider for a React Context. Doing so means rerendering those components whenever the state of the context changes. Instead, only expose children from your custom Provider and compose components under the Provider. Using react-generate-context removes some of this boilerplate for you.

Comparing `useRef` and `useState`

Wed, 22 Sep 2021 00:00:00 GMT

import BackgroundCounter from './_BackgroundCounter' import HookCategories from './_HookCategories.astro' import RandomBox from './_RandomBox' import RefRandomBox from './_RefRandomBox'

When I discuss React with people, I often hear that others find useRef to be confusing. People are uncertain about when and why they should use it. They often opt to use useState instead when perhaps it's not the right choice. I think one way of gaining an understanding of useRef is to compare it with useState, so let's do that.

Before we get into the specific differences, I want to share a realization I recently had. I realized that the standard React Hooks come in four categories:

Notice that I put useRef in two categories. It doesn't fall neatly into one or the other. It holds a bit of state, whatever value is assigned to ref.current, making it a "State Manager". But it's also a "Stabilizer" because changing the value of ref.current does not cause a component to update.

useState, on the other hand, is designed to update a component. <Marker content="That's kind of the whole point, ha." /> In fact, I like to help people understand useState better by showing them how to make a useForceUpdate hook with it.

If you have written React for long enough, or have had the chance to work or search through some class component code, you may have used or come across an invocation of this.forceUpdate(). React class components have a method, forceUpdate, that you can use to imperatively force a component to rerender. It was an escape hatch of last resort. The move to React Hooks meant we lost this escape hatch, right?

Wrong.

We can create that same imperative escape hatch function like so: <Marker content={You can also find this code on my <a href="/snippets">Snippets</a> under <a href="/snippets/use-force-update">useForceUpdate()</a>.} />

const useForceUpdate = () => {
  const [, setState] = React.useState(true)
  const forceUpdate = React.useCallback(() => {
    setState(x => !x)
  }, [])

  return forceUpdate
}

Let's break this code down. First, we only destructure the state setter from the useState hook. <Marker content="With array destructuring, you can skip values at any index just be not declaring a variable name at that position." /> We don't actually need the state, we just need it to change whenever we want to force an update. Next, we make a callback function, stabilize it with useCallback, and use a function updater to flip the boolean back and forth. We then return our function from the hook. If we include this in a component, which we will see soon enough, we can force it to update. Let's put this into practice.

As I've demonstrated before in my post on React.memo, one way to visually see that a component has updated is to give it a random background color with each render. Let's make a component that does just that. First, the randomRGB function: <Marker content={This, too, can be found on my <a href="/snippets">Snippets</a> page under <a href="/snippets/random-rgb">randomRGB()</a>} />

const random255 = () => Math.floor(Math.random() * 255)

const randomRGB = () => {
  const r = random255()
  const g = random255()
  const b = random255()

  return `rgb(${r}, ${g}, ${b})`
}

Next, we'll make a box with a "Force Update" button that uses randomRGB.

function Box() {
  const forceUpdate = useForceUpdate()

  return (
    <div style={{ backgroundColor: randomRGB(), padding: 10 }}>
      <button onClick={forceUpdate}>Force Update</button>
    </div>
  )
}

And let's see it in action.

Neat. Now, hopefully it's clear what causes a rerender with useState. The question we must now ask ourselves is, "How does this relate to useRef?". Let's try to make a similar box, but use useRef instead. We'll have to create our own state updater to do this since useRef doesn't give us one.

function RefBox() {
  const ref = React.useRef(true)
  const flip = React.useCallback(() => {
    ref.current = !ref.current
  }, [])

  return (
    <div style={{ backgroundColor: randomRGB(), padding: 10 }}>
      <button onClick={flip}>Try to update</button>
    </div>
  )
}

I bet you just clicked that button repeatedly and wondered if it's actually doing anything. I assure you it is, check your console. I snuck a console.log into flip on you.

useRef is a mutable value store. In other words, we can imperatively update the ref by assigning a new value to ref.current. However, a component does not update when ref.current changes. Some other kind of state update needs to happen in order for the component to rerender.

Let's make an example that combines these two features together. We'll make a box with a counter as a ref. We'll update that counter in the background and see the current value of that ref whenever we force the component to update.

function BackgroundCounter() {
  const counter = React.useRef(0)
  const forceUpdate = useForceUpdate()

  React.useEffect(() => {
    const interval = setInterval(() => {
      counter.current++
    }, 100)

    return () => {
      clearInterval(interval)
    }
  }, [])

  const reset = () => {
    counter.current = 0
    forceUpdate()
  }

  return (
    <div style={{ backgroundColor: randomRGB() }}>
      <div>{counter.current}</div>
      <div>
        <button onClick={forceUpdate} type="button">
          Force Update
        </button>
        <button onClick={reset} type="button">
          Reset
        </button>
      </div>
    </div>
  )
}

And let's see how that works.

Notice that the value displayed only updates when we force it to. It's been changing in the background this entire time, and yet, because it was a ref, the component never updates. It was probably a pretty big number the first time you updated it, too. It's been running since you started reading this article.

So when might we practically want to use useRef? Well, the answer is the combination of those facts, "Whenever we need a value that will always be available, can be changed when necessary, without updating the component." I know that seems unhelpful, but let's make another example.

useRef essentially allows us to create a value in closure for the lifetime of the component. If you need a refresher on closures, I got you. Have you ever had an effect that you wanted to ensure only ran once? <Marker content="Be careful here. This might only be the behavior you <em>think</em> you want. This is the kind of thing where bugs quickly creep up." /> We can make a useEffectOnlyOnce hook by using a ref.

function useEffectOnlyOnce(effect, dependencies) {
  const hasRun = React.useRef(false)

  React.useEffect(() => {
    if (hasRun.current) return

    hasRun.current = true
    effect()
  }, dependencies)
}

Or what about an effect that can only run after a component has initially mounted?

function useEffectAfterInitialMount(effect, dependencies) {
  const isMounted = React.useRef(false)

  React.useEffect(() => {
    if (!isMounted.current) {
      isMounted.current = true
      return
    }

    effect()
  }, dependencies)
}

Or, I don't know, what about an effect that only runs every nth time because you just want to be silly?

function useEffectEveryNthTime(effect, dependencies, n) {
  const count = React.useRef(0)

  React.useEffect(() => {
    count.current++

    if (count.current % n === 0) {
      effect()
    }
  }, dependencies)
}

The point is a ref is very useful when you need to track a value for the lifetime of a component but don't need it's every change to update the UI. If you need that, you probably need to use a different state manager hook.

Summary

Changing useState's value will always cause a rerender, even if that state isn't used anywhere in the component. Changing useRef's value will never cause a rerender, even if you use that state somewhere in the component.

useRef is useful for having a stable reference to a value throughout the lifetime of a component. It is a mutable value held in the closure of your component function and can be used by the functions created in the body of the component function.

What is a Closure?

Thu, 02 Sep 2021 00:00:00 GMT

In JavaScript, and some other languages, too, there is the concept of a "closure". This concept can be confusing at first, but once understood, can become a useful tool in your repertoire. I want to help you discover how useful it can be.

In short, a "closure" occurs when a bit of "state", created inside of a function body, is exposed, with some indirection, to the outside world in the function's return. To make sense of this, let's break down a few things.

This is a function.

function() {}

When I create values inside of this function, they are scoped to the body, the {}, of the function. They cannot be accessed from outside of the function body.

function counter() {
  let count = 0
}

console.log(count) // Uncaught ReferenceError: count is not defined

If I return the count, the outside world can access the value, but it has no means of updating the value. Think of this as a bit of "state", but one that cannot be updated.

function counter() {
  let count = 0
  return count
}

const count = counter()

console.log(count) // 0

If instead of returning the count, I instead return an object that gives you access to reading the current count and methods for updating count, I will have exposed a bit of "state" that can be updated.

function createCounter() {
  let count = 0

  return {
    /**
     * Read the current state
     */
    state: () => count,
    /**
     * Increment the state by 1
     */
    increment: () => {
      count++
    },
    /**
     * Decrement the state by 1
     */
    decrement: () => {
      count--
    },
  }
}

const counter = createCounter()

console.log(counter.state()) // 0
counter.increment()
counter.increment()
counter.increment()
console.log(counter.state()) // 3

Now, I have a bit of state from our createCounter function body that is held in the memory of my program so long as I still have access to the returned counter object. That is the closure.

I can read that state, I can update that state, but not directly. I do it indirectly through the API established by the returned object. <Marker content="The <code>createCounter</code> function is actually a <strong>factory function</strong>, which I hope to write about next." /> Can you start to see how useful this is?

This method can be used to create persistent state for the life of our program, it can be used for partially applying values to curried functions, it can be used to create truly private functions and values, something we don't yet have for classes in JavaScript. The applications are numerous.

I highly encourage you try making a few simple closures (if you haven't before), to get the hang of it. I think it can be a real eye opener, and you'll start to think of the returns of your functions as little APIs that your program interacts with.

Summary

A closure is created when state held inside of a function body is exposed to the world outside of that function through its return value. It remains accessible, albeit indirectly, so long as the returned value exists in the program.

Prefer Function Updaters in State Setters

Mon, 30 Aug 2021 00:00:00 GMT

import ItemSelectorBad from './_ItemSelectorBad'

This one will be short and sweet. <Marker content="At least I thought so when I started writing this, and I have no intention of changing the sentence now" /> You're using React. You have some state.

const [selectedItem, setSelectedItem] = React.useState(null)

You're already on board with the concepts in useEncapsulation and Prefer Declarative State Updaters, so you make a custom hook combining your state with the functions that will update that state.

function useItemSelection() {
  const [selectedItem, setSelectedItem] = React.useState(null)

  const handlers = React.useMemo(
    () => ({
      selectItem: item => {
        setSelectedItem(item)
      },
      unselectItem: () => {
        setSelectedItem(null)
      },
    }),
    [],
  )

  return [selectedItem, handlers]
}

Fantastic. Your selection logic is encapsulated in a nice, little custom hook. Your boss and colleagues love you and your code. All is well in the world!

Until...

You get some new requirements.

"We would love it if clicking on the currently selected item would unselect the item, rather than do nothing. Can you do that?"

Of course we can! But the question is how shall we do it? There are at minimum, two ways. Let's do it the less-than-great way first.

In order to "unselect" an item, we need to know that the item we're selecting is the same as current selectedItem. We could use the selectedItem that's in scope.

function useItemSelection() {
  const [selectedItem, setSelectedItem] = React.useState(null)

  const handlers = React.useMemo(
    () => ({
      // ...same handlers as before

      smartSelectItem: item => {
        // Here we use `selectedItem` from the parent scope
        // We're _also_ assuming the "items" have an `id`
        // We will fix that later
        if (item?.id === selectedItem?.id) {
          setSelectedItem(null)
          return
        }

        setSelectedItem(item)
      },
    }),
    // Now we had to add `selectedItem` as a dependency
    // All handlers will update _every_ time `selectedItem` updates
    [selectedItem],
  )

  return [selectedItem, handlers]
}

We can pop this into a component and see that it works.

Great, this works as expected. Why is it less-than-great?

Because we're relying on a dependency we don't need to rely on, and in so doing, we're forcing our state updaters to change unnecessarily.

If we use a "function updater" instead of relying on the selectedItem in scope, we can avoid the selectedItem dependency entirely.

const handlers = React.useMemo(() => {
  // ...same handlers as before, except...
  smartSelectItem: item => {
    setSelectedItem(currentItem => {
      if (item?.id === currentItem?.id) return null
      return item
    })
  }
}, [])

Now we no longer have a dependency because React is giving us all the information we need to determine the next state within the state setter itself. On top of that, we get a tidy little, almost pattern matching like function body. The fact that each branch of logic must return the nextState helps us in other ways. I've made the following bug a few times in my career: <Marker content="And lost a few hours here and there yelling at my computer about it. <span>😅</span>" />

{
  smartSelectItem: item => {
    if (item?.id === selectedItem?.id) {
      setSelectedItem(null)
    }

    setSelectedItem(item)
  }
}

See my mistake?

I forgot to return in the guard statement. Classic.

Other Benefits

Hooks solved a lot of problems, but they didn't get rid of a few "gotchas". In fact, useState created an extra gotcha you didn't have to deal with in class component days. Let's start there:

Object updates are not merged anymore

In the class component days, you could create a state like this:

this.state = {
  error: null,
  data: null,
  loading: false,
}

And you could do updates like this:

this.setState({ loading: true })

And your state would be:

console.log(this.state) // { error: null, data: null, loading: true }

But try this with a hook instead:

const [state, setState] = React.useState({
  error: null,
  data: null,
  loading: false,
})

setState({ loading: true })

console.log(state) // { loading: true }

What?! That's right, objects aren't merged. They are replaced.

I personally think this makes sense. By making the state setter more rudimentary, the API becomes straightforward. No longer do you need to know about the "behavior" of the state setter. It's less information you need to store in memory, and I'm a big fan of that.

You can get around this using function updaters:

const [state, setState] = React.useState({
  error: null,
  data: null,
  loading: false,
})

setState(currentState => ({
  ...currentState,
  loading: true,
}))

console.log(state) // { error: null, data: null, loading true }

Calling state setters more than once in a handler body

This "gotcha" has also been true since the class component days. If you call a state setter more than once in the same function body, there's a really good chance that the update will not be what you expect when that function body completes.

Here's an absurd example, with a useTripleCounter hook:

function useTripleCount() {
  const [state, setState] = React.useState(0)

  const handlers = React.useMemo(
    () => ({
      inc: () => {
        setState(state + 1)
        setState(state + 1)
        setState(state + 1)
      },
      dec: () => {
        setState(state - 1)
        setState(state - 1)
        setState(state - 1)
      },
    }),
    [state],
  )

  return [state, handlers]
}

If I use this in a component, what's going to happen? All three setStates are going to be called, utilizing the same state dependency and state will only change by a value of 1. Not to mention, our handlers update every single time state updates, which may lead to more rerenders than necessary.

But, if we swap those updates for function updaters:

const handlers = React.useMemo(
  () => ({
    inc: () => {
      // often I shorten `state` to just `s` when the update is this small
      setState(s => s + 1)
      setState(s => s + 1)
      setState(s => s + 1)
    },
    dec: () => {
      setState(s => s - 1)
      setState(s => s - 1)
      setState(s => s - 1)
    },
  }),
  [],
)

What happens now? Now our updates are all applied. Our count increments and decrements by 3. I hope you can see how this might be useful in a real situation. <Marker content="Though I might recommend you find a way to <em>not</em> call a state setter multiple times in the same function body instead." />

Summary

Using function updaters leads to fewer gotchas and requires fewer dependencies than simply replacing the current state. Consider using them more often to improve your stateful React components.

Bonus: Improving the `useItemSelection` hook

I wanted to take a moment and make this hook a little better before finishing the post. This relates to my recent post on dependency injection which you should read.

Did you happen to notice another dependency in the useItemSelection hook? Here it is in full so you can look for it:

function useItemSelection() {
  const [selectedItem, setSelectedItem] = React.useState(null)

  const handlers = React.useMemo(
    () => ({
      selectItem: item => {
        setSelectedItem(item)
      },
      unselectItem: () => {
        setSelectedItem(null)
      },
      smartSelectItem: item => {
        setSelectedItem(currentItem => {
          if (item?.id === currentItem?.id) return null
          return item
        })
      },
    }),
    [],
  )

  return [selectedItem, handlers]
}

Hopefully you recognized that smartSelectItem knows a bit too much about the shape of the items being selected. What if these items are not objects? What if they are but don't have ids, but some other key?

Let's use dependency injection and a default parameter to fix this:

const tryId = x => x?.id

function useItemSelection(getKey = tryId) {
  const [selectedItem, setSelectedItem] = React.useState(null)

  const handlers = React.useMemo(
    () => ({
      selectItem: item => {
        setSelectedItem(item)
      },
      unselectItem: () => {
        setSelectedItem(null)
      },
      smartSelectItem: item => {
        setSelectedItem(currentItem => {
          if (getKey(item) === getKey(currentItem)) return null
          return item
        })
      },
    }),
    [getKey],
  )

  return [selectedItem, handlers]
}

Now useItemSelection is a bit more flexible. Perhaps you want to use name as a key instead:

const [state, handlers] = useItemSelection(x => x?.name)

No longer does useItemSelection force your data into a shape. You can easily conform useItemSelection to your data.

Dependency Injection and Default Parameters

Thu, 19 Aug 2021 00:00:00 GMT

I've been working on lessons for a new course recently, and one of the the lessons I created inspired me to share one of my favorite techniques for creating flexible functions: dependency injection and default parameters. Let's dig in.

Dependency injection

Now, I don't have a computer science degree, so my understanding of what "dependency injection" is might be a little different than yours, but allow me to explain how I understand it so we're on the same page for the rest of the blog post.

Let's start by coming to agreement on what a "dependency" is. Let's say I have the following function:

function formatString(str) {
  return capitalize(str)
}

This is a simple, well named function. It formats a string. But the part I want to focus on for a moment is the use of capitalize. What is capitalize in this situation?

It is a dependency.

formatString depends on capitalize (for now). If capitalize isn't in scope for formatString, the program falls apart and throws an error. In this way, anything a function <Marker content="Or class, which is more typically used when describing dependency injection." /> depends on is a dependency.

This, of course, begs the next question: what does it mean to "inject" a dependency. Let's modify our formatString function a little bit and find out.

Instead of relying on capitalize to be in the same scope, let's make it a parameter of the function and pass capitalize in as an argument.

function formatString(str, formatter) {
  return formatter(str)
}

const capitalizedHello = formatString('hello', capitalize)
console.log(capitalizedHello) // 'Hello'

Now the formatter of our formatString function is passed in as an argument. This allows us to pass in other formatters as well.

const scream = str => [...str].map(x => x.toUpperCase()).join('')
const snakeCase = str => str.replace(/\s/g, '_')

const str = 'hello world'

formatString(str, scream) // HELLO WORLD
formatString(str, snakeCase) // hello_world

But what happens if we forget to pass in a formatter?

*Cue the womp womp womp noises 🎺

It falls apart, right? We can solve this with a default parameter.

Default parameters

JavaScript functions can be variadic, meaning they can be called with a variable number of arguments. When a function is called without an argument for a particular parameter, that parameter is assigned undefined. However, if this is undesirable behavior, we can define defaults for these unassigned parameters using default parameters.

In the case of our formatString function, we can make use of the identity function.

const identity = x => x

The identity function simply returns whatever is passed in. Give it a string. Get that string right back. It's perfect for a default parameter in our formatString function. <Marker content="It turns out, the identity function is a useful default parameter in a lot of other functions, too" />

function formatString(str, formatter = identity) {
  return formatter(str)
}

formatString('hello world') // hello world

Now, we don't need to provide a dependency if the default one suits our needs. Are you starting to see how this can bake flexibility into the programs you write?

Practical example

I'm currently working on a course to help people understand Array.reduce() better. It confuses a lot of people, and if you're one of them, know help is coming.

In the course, we do a lot of exercises using reduce to build up our muscle memory. One of the more practical exercises is a counts function. It receives an array, and counts the items in the array based on some criteria. The question is, how do we determine the criteria for counting the items?

In the case of primitive values, such as Numbers, Strings and Booleans, the criteria is fairly simple: use the item itself. Let's start building this counts function, but with a for loop. Don't want to spoil all my course material:

function counts(items) {
  const result = {}

  for (const item of items) {
    if (result[item] === undefined) {
      result[item] = 0
    }

    result[item]++
  }

  return result
}

Now if we call counts on some arrays with primitives, we'd get results like these:

counts([true, false, true, true, false, false, true])
// { true: 4, false: 3 }

counts([1, 2, 2, 3, 3, 3])
// { '1': 1, '2': 2, '3': 3}

counts(['apple', 'banana', 'apple', 'orange', 'orange', 'apple'])
// { apple: 3, banana: 1, orange: 2}

That works great, but how do we handle situations where our items aren't primitives? Or situations where we might want to do something more complicated than use the item itself as the key? <Marker content="Or handle <code>undefined</code> as a value?" />

You guessed it. Dependency injection and a default parameter.

Let's add an argument to our counts function, a getKey callback function that will be passed the item (and some other arguments). This function will determine the key to be used in our counts function for us.

function counts(items, getKey /* what should the default parameter be? */) {
  const result = {}

  // Notice the change we make with entries()
  for (const [index, item] of items.entries()) {
    // This is the same signature as the callback for .map or .filter
    const key = getKey(item, index, items)

    if (result[key] === undefined) {
      result[key] = 0
    }

    result[key]++
  }

  return result
}

Now, if we have a more complicated array of items, or simply want to do something more complicated with a primitive array of items, we can. Let's say I'm counting inventory of some clothing. I want to be able to generate counts based on the color of the shirt and the size of the shirt.

const shirts = [
  { color: 'red', size: 'M' },
  { color: 'blue', size: 'M' },
  { color: 'red', size: 'S' },
  { color: 'red', size: 'L' },
  { color: 'blue', size: 'S' },
]

counts(shirts, item => item.color)
// { red: 3, blue: 2 }

counts(shirts, item => item.size)
// { L: 1, M: 2, S: 2 }

We can even use it to do something like count how many even and odd numbers are in a list.

const nums = [1, 2, 3, 4, 5, 6, 7, 8, 9]

counts(nums, x => (x % 2 ? 'odd' : 'even'))
// { odd: 5, even: 4 }

Injecting the getKey dependency makes this function a lot more flexible. We just have one thing remaining. Did you figure out what the default getKey function should be?

That's right. It should be identity. Our final counts function looks like this:

function counts(items, getKey = identity) {
  const result = {}

  for (const [index, item] of items.entries()) {
    const key = getKey(item, index, items)

    if (result[key] === undefined) {
      result[key] = 0
    }

    result[key]++
  }

  return result
}

Summary

Functions can be made more flexible by passing in their dependencies rather than relying on them being available in their scope. We can set good defaults to handle most cases, and then override that parameter with argument of our own which injects the dependency. This pattern can be seen in something as small as the examples here, to much bigger systems.

Additional resources

One of the most fantastic talks I've ever seen is "Nothing is Something" by Sandi Metz. I have watched this talk half a dozen times in my life, it's that good. Even if you never write a line of Ruby, deep diving on her talks is well worth your time.

This talk, "Nothing is Something", really explores how dependency injection and object composition is the way to create truly flexible programs. I strongly encourage you to give it a watch:

Discriminated Unions and Destructuring in TypeScript

Wed, 11 Aug 2021 00:00:00 GMT

I'm writing this post because I've forgotten the following material enough times to warrant leaving myself a permanent resource for future reference. I figure it will likely help out a few of you as well.

I am a big fan of state machines, but often find myself unable to use them in the projects I work on. People are so hesitant to give them a try. I'll never understand it. Given this, I turn to the next best thing: enums.

I like to enumerate the finite states my functions can return. If you're writing TypeScript, something I find myself doing more and more of these days, enumerated states often mean using "discriminated unions".

A discriminated union is a type where a key or value can be used to determine the rest of the shape of that type. An example might be several types for objects that have a kind key, like so:

type GetPostsSuccess = {
  kind: 'success'
  context: {
    data: { posts: [] }
  }
}

type GetPostsFailure = {
  kind: 'failure'
  context: {
    error: { message: 'something went wrong' }
  }
}

I can combine these with a union:

type GetPostResults = GetPostsSuccess | GetPostsFailure

And now I can discriminate that union by the kind key:

function getPosts(): GetPostResults {
  // Let's assume something happens and I get a result
}

function doSomethingWithPosts() {
  const result = getPosts()

  switch (result.kind) {
    case 'success':
      return result.context.data.posts

    case 'failure':
      return result.context.error.message
  }
}

I don't have to check if result.context has error or data in either case because the TypeScript compiler knows that if result.kind is "success", then the rest of the object has context.data.posts. This is a really nice feature, but it's easily broken with destructuring.

Changing that example only slightly, we break everything:

function getPosts(): GetPostResults {
  // Let's assume something happens and I get a result
}

function doSomethingWithPosts() {
  const { kind, context } = getPosts()

  switch (kind) {
    case 'success':
      return context.data.posts // Error

    case 'failure':
      return context.error.message // Error
  }
}

If you try this in TypeScript, which you can do here, it will error. Twice, actually. It will tell you that data doesn't exist on context in the 'success' case and that error doesn't exist in the 'failure' case. To which you will respond with, "Sure the heck does!"

You, a mere mortal, can determine precisely what shape the type is, but alas, the TypeScript compiler can not.

Why?

In short, TypeScript loses the "refinement" of the discrimination when we use object or array destructuring. If you destructure an object or an array, TypeScript is unable to remember the shape of the whole based on a part. If we destructure kind, it completely forgets what context specifically is, and instead types it as a union of what it could be:

type context =
  | {
      data: { posts: [] }
    }
  | {
      error: { message: 'something went wrong' }
    }

It's created a union that's no longer discriminated and you're stuck having to check what keys or what objects again. Not ideal.

I'll give you another example using an array as a tuple. This is a replication of the very problem I was working on today when I ran into this.

I was trying to set up some state to follow the progress of calling an API. This is a very common pattern in web apps that benefits a lot from using enumerated states. Here are the types I created:

enum States {
  IDLE = 'IDLE',
  LOADING = 'LOADING',
  SUCCESS = 'SUCCESS',
  FAILURE = 'FAILURE',
}

type Post = {
  title: string
  body: string
}

type Data = { posts: Array<Post> }

type Results =
  | [States.IDLE, undefined]
  | [States.LOADING, undefined]
  | [States.SUCCESS, Data]
  | [States.FAILURE, Error]

Examining Results, we can see a discriminated union based on the States enum. Let's create a custom hook that will use these types and fetch our posts:

function useGetPosts(): Results {
  const [result, setResult] = useState<Results>([States.IDLE, undefined])

  useEffect(() => {
    setResult([States.LOADING, undefined])

    fetch('/api/posts')
      .then(res => res.json())
      .then(data => {
        setResult([States.SUCCESS, data])
      })
      .catch(error => {
        setResult([States.FAILURE, error])
      })
  }, [])

  return result
}

Going through the code, our typechecker is satisfied. Our Results tuple is always one of our four possible results. Let's make use of this in a component.

function Posts() {
  const result = useGetPosts()
  const [state, context] = result

  switch (state) {
    case States.IDLE:
      return <div>idle</div>

    case States.LOADING:
      return <div>loading...</div>

    case States.SUCCESS: {
      return (
        <div>
          {context.posts.map(post => (
            <div key={post.title}>
              {post.title} {post.body}
            </div>
          ))}
        </div>
      )
    }

    case States.FAILURE: {
      return <div>{context.message}</div>
    }
  }
}

What do you think happens in this case? We lose our refinement!

We've done a perfectly natural thing in modern JavaScript. We've returned a small array from our custom hook with our state and some relevant context, and then we destructured that state and that context where we make use of that hook so that our code is really easy to read for humans. But it's not easy for the compiler. <Marker content="Compiler schmiler! This really grinds my gears." />

Instead, we need to make adjustments to keep our refinement.

function Posts() {
  const result = useGetPosts()

  switch (result[0] /* state */) {
    case States.IDLE:
      return <div>idle</div>

    case States.LOADING:
      return <div>loading...</div>

    case States.SUCCESS: {
      // We can destructure here because our `context` is refined to the
      // correct shape by the switch statement. We can also skip
      // destructuring `state` and rename `context` to `data` in one step
      const [, data] = result

      return (
        <div>
          {data.posts.map(post => (
            <div key={post.title}>
              {post.title} {post.body}
            </div>
          ))}
        </div>
      )
    }

    case States.FAILURE: {
      const [, error] = result
      return <div>{error.message}</div>
    }
  }
}

This produces no TypeScript errors. I find the code to be ok. I could live with this, but it does not bring me joy.

In this particular situation, it might be best to stick with an object instead of a tuple. Then at least you could have result.state and result.context. You would lose the convenience of renaming the values to be contextually appropriate though, eg data in SUCCESS and error in FAILURE.

Hopefully this has helped you understand discriminated unions a bit better and prevents you from getting stuck on these destructuring gotchas in the future. At the very least, I hope writing this helps me with those things in the future, too.

Prefer Declarative State Updaters

Sat, 07 Aug 2021 00:00:00 GMT

Since the advent of React hooks, I have seen a pattern emerge that I think is less than ideal. I've started calling it the "naked state setter" pattern.

Before I explain it, I want to be clear: it's not an anti-pattern. You're not in any danger if you use it, but I don't think it's the best pattern. I also think the growing use of types, eg. TypeScript or Flow, has obscured this less-then-ideal pattern, so recognizing it can be even trickier.

Let me break down what I'm seeing with some code. I'm going to use a rudimentary example, so I'm going to ask you to use some imagination throughout this post. Let's build a simple counter: <Marker content="Big surprise, right?" />

function Counter() {
  const [count, setCount] = React.useState(0)
  return <div>{count}</div>
}

Before you get distracted wondering why I have state when I have nothing changing the state, I want to point out what the "naked state setter" is. It's the setCount in this example. It's bare. It's naked. It's not wrapped in anything. Get it?

Let's finish our component (for now).

import { Button } from './components/Button'

function Counter() {
  const [count, setCount] = React.useState(0)

  return (
    <div>
      <div>{count}</div>
      <div>
        <Button
          onClick={() => {
            setCount(s => s + 1)
          }}
        >
          +
        </Button>
        <Button
          onClick={() => {
            setCount(s => s - 1)
          }}
        >
          -
        </Button>
        <Button
          onClick={() => {
            setCount(0)
          }}
        >
          reset
        </Button>
      </div>
    </div>
  )
}

We've written all of our state updater functions inline. This isn't that uncommon, and honestly, there are many situations where this is fine. But just because it's fine, doesn't mean it can't be better.

So what is the problem with these state updater functions?

They don't tell you what they do! You have to read the body of the function to get that information. They barely wrap our naked state setter in anything. Just a pair of {}. It's like wrapping our callback function in a toga. We are very close to the bare skin.

What if, instead, we made declarative state updater functions?

import { Button } from './components/Button'

function Counter() {
  const [count, setCount] = React.useState(0)

  const incrementCount = React.useCallback(() => {
    setCount(s => s + 1)
  }, [])

  const decrementCount = React.useCallback(() => {
    setCount(s => s - 1)
  }, [])

  const resetCount = React.useCallback(() => {
    setCount(0)
  }, [])

  return (
    <div>
      <div>{count}</div>
      <div>
        <Button onClick={incrementCount}>+</Button>
        <Button onClick={decrementCount}>-</Button>
        <Button onClick={resetCount}>reset</Button>
      </div>
    </div>
  )
}

Now, we have three declarative state updaters. They describe what they do. They're wrapped in more than just {}. They have a name. As I'm reading the UI, it's very clear what action will be taken for each onClick event.

"But why does this matter, Kyle? It's all in the same component. It's simple. I can understand it!"

Ok. I hear you. You're right that in this contrived example, it's understandable. But what about when we have to pass those state updaters down to some children components?

Let's say this component looked like this:

import CounterActions from './CounterActions'

function Counter() {
  const [count, setCount] = React.useState(0)

  // What props should CounterActions get?
  return (
    <div>
      <div>{count}</div>
      <CounterActions />
    </div>
  )
}

In this case, I've got another component that renders the actions of the Counter. CounterActions has the UI responsible for updating the state in Counter. In order to do that, we have a few choices in what we pass to CounterActions.

Naively, we could just give it setCount.

<CounterActions setCount={setCount} />

This works, right? I can write all those updaters in the CounterActions component. But what if I don't control CounterActions? Maybe I'm giving them a little too much leeway by giving them the naked state setter. What if CounterActions arbitrarily decides to increment and decrement by values other than 1? What if I'm giving them a little too much control? Nothing stops someone from writing CounterActions like this:

import { Button } from './components/Button'

function CounterActions({ setCount }) {
  return (
    <div>
      <Button
        onClick={() => {
          setCount(false)
        }}
      >
        +
      </Button>
      <Button
        onClick={() => {
          setCount({})
        }}
      >
        -
      </Button>
      <Button
        onClick={() => {
          setCount(null)
        }}
      >
        reset
      </Button>
    </div>
  )
}

It's chaos! Mayhem! CounterActions can run amuck with all the power of that naked state setter getting passed down as a prop. We gotta stop that!

"Ok, just add some types. That'll prevent the misuse," you say.

Sure, let's try it.

import { Button } from './components/Button'

function Counter() {
  const [count, setCount] = React.useState<number>(0)

  return (
    <div>
      <div>{count}</div>
      <CounterActions setCount={setCount} />
    </div>
  )
}

function CounterActions({ setCount }) {
  const incrementCount = React.useCallback(() => {
    setCount(s => s * 3)
  }, [])

  const decrementCount = React.useCallback(() => {
    setCount(s => s / 2)
  }, [])

  const resetCount = React.useCallback(() => {
    setCount(1000)
  }, [])

  return (
    <div>
      <Button onClick={incrementCount}>+</Button>
      <Button onClick={decrementCount}>-</Button>
      <Button onClick={resetCount}>reset</Button>
    </div>
  )
}

Ahhhh! Even types haven't saved us from this mess. It's even worse. Passing the naked state setter means that now the logic of my count state exists somewhere else and I can't restrict how it's used.

This is where declarative state updaters really shine.

Instead, let's define the API that we want CounterActions to use. We don't care how CounterActions or any further children use it, but we know they can't misuse it. <Marker content="Too badly." />

import CounterActions from './CounterActions'

function Counter() {
  const [count, setCount] = React.useState(0)

  const incrementCount = React.useCallback(() => {
    setCount(s => s + 1)
  }, [])

  const decrementCount = React.useCallback(() => {
    setCount(s => s - 1)
  }, [])

  const resetCount = React.useCallback(() => {
    setCount(0)
  }, [])

  return (
    <div>
      <div>{count}</div>
      <CounterActions
        incrementCount={incrementCount}
        decrementCount={decrementCount}
        resetCount={resetCount}
      />
    </div>
  )
}

Now, I don't have to worry about how CounterActions uses my updaters. They can't really screw it up. They may make a broken, less than optimal Counter, but it won't be because they can arbitrarily update state. They can only use what I allow them to use. It's the perfect amount of power to pass to another component.

A step further

What makes declarative state updaters even more powerful is how easily they can be refactored into a good custom hook. I'm actually going to do two refactors here at once: first, move the logic into a custom hook, and second, swap three useCallbacks for a single useMemo.

import CounterActions from './CounterActions'

function useCounter() {
  const [count, setCount] = React.useState(0)

  const handlers = React.useMemo(
    () => ({
      increment: () => {
        setCount(s => s + 1)
      },
      decrement: () => {
        setCount(s => s - 1)
      },
      reset: () => {
        setCount(0)
      },
    }),
    [],
  )

  return [count, handlers]
}

function Counter() {
  const [count, { increment, decrement, reset }] = useCounter()

  return (
    <div>
      <div>{count}</div>
      <CounterActions
        incrementCount={increment}
        decrementCount={decrement}
        resetCount={reset}
      />
    </div>
  )
}

Hopefully you can see how nice it is to wrap our naked state setters to create quality declarative state updaters.

Time for you to use your imagination

This is the part where I need you to think about how you're writing your code right now and apply the concepts here to the more important and likely complex work you are doing. Here's what I hope you take away.

Passing a naked state setter to children might be dangerous, even with types
Declarative state updaters put you in control and prevent misuse
Declarative state updaters are easy to refactor into custom hooks

So go on, wrap those naked state setters up with some thing.

How I Structure My React Projects

Thu, 01 Jul 2021 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

Recently, my friend Chance and I had this exchange on Twitter:

Cause that's what I would do. `} />

It's true. It really doesn't matter. That said, I'm going to share a few of my preferences and why they are what they are.

Warning: These are my opinions. You don't have to agree with them. If you don't agree with them, that's ok. Just know, I'm not going to engage in an argument with you about these opinions.

Single file components

Don't have a folder named MyComponent with an index.tsx, styles.ts|css, and types.ts file, etc.

Do have a file named MyComponent.js|jsx|tsx and have all related styles and types in the same file.

Why?

First, it is a waste of time and annoying AF to have to search for a file in my editor by typing MyComponent followed by index to ensure I get the right file.

This is one of my least favorite features of "convention over configuration" frameworks like Ember and should be avoided in React projects. You end up with hundreds and hundreds of files that have the same name, index.js or component.js and you always have to do two-part searches. What an absolute waste of keystrokes. I know you may think that's trivial, but it adds up when you're searching for dozens and dozens of files every day. It's never good enough to just do MyComponent. You need to add styles or types or use arrow keys to navigate a list to get the file you were looking for. What a waste!

Second, having files that only exist to export tightly coupled information, like styles and types is equally wasteful and can lead to some organizational footguns. Put the info directly in the same file. You'll convey information faster, improve Intellisense speed, and more. Plus, you get the bonus of not creating an export unless other modules actually need that value. When you do the multi-file approach, you run the risk of people importing styles and types in an ad hoc fashion and it's a fast way to running into duplication and organizational messes.

Sub-components in same file, too

Don't make a separate file for a small sub-component that won't be reused by another part of the system.

Do use sub-components where it makes sense, but keep them in the same file.

Why?

Related to single file components, if you are breaking up a bigger component into sub-components and those sub-components are relatively small and are not intended for reuse, keep those in the same file as well.

function BigComponent(props) {
  return (
    <div>
      <SubComponentA />
      <SubComponentB someProp={props.someProp} />
    </div>
  )
}

function SubComponentA() {
  return <div>Sub A</div>
}

function SubComponentB({ someProp }) {
  return <div>{someProp}</div>
}

So long as SubComponentA and SubComponentB have no reason to be exported or used elsewhere, there's nothing wrong with keeping them within the same file. In fact, it encourages you to break your monolithic components down into reasonable and understandable pieces.

There is one downside to this if you're using TypeScript. You will have to re-declare the types of your props for every component you do some prop drilling for. Given that you can often define a Props type, and then reuse the types in it with Pick<> or something similar, I find this to be a reasonable tradeoff.

Feature folders

Don't just have a folder named components and throw everything in there.

Do have a folder named features where each sub-folder is a specific feature containing all the files related to that feature.

Why?

I think when you're first starting a project or doing a side project, it's fine to have a single components folder and throw everything into it. But soon enough, you'll realize you have a set of components that are shared and many components that are really just one-off abstractions for a single feature. Keeping these in the same folder misrepresents how these components should be used in your system.

I have found it better to take those components related to a single feature to give that feature a name and contain all the files for that feature in that folder. Doing so, allows you to treat the feature similar to a package, exporting precisely what you intend to the rest of your system. You can even write eslint rules that prevent people from importing values that are nested further than the top level of your features folder. It forces you to think about the interfaces of your system and to define useful boundaries.

This also has the benefit of more accurately representing your organizational information. I have found this to be a useful means of helping people onboard to complex projects. Rather than asking them to try and piece everything together from across your codebase, it is easy to pick a feature and explore that sub-tree of your system.

Summary

Don't create extra files just to export something that's only used by a single component, like styles and types. Use single file components to encourage exporting precisely what the rest of the system needs and improve file search by a few keystrokes each time.

Similarly, keep sub-components in the same file until they become useful abstractions for the system.

When you do have these useful components to break out, determine if they belong to part of your shared system <Marker content="Perhaps your design system?" />, or really belong solely to a feature. Use feature folders to identify boundaries in your system.

What are “Magic Values”?

Sat, 26 Jun 2021 00:00:00 GMT

I recently did a code review for an aspiring developer and instructed them to "get rid of the 'magic values' in their code." It dawned on me that it might not have been obvious what I meant, so I figured I would take a few moments, and paragraphs, to explain.

A "magic value" is a string or number used in a program that is essential to its proper function but provides no context or explanation for why it is what it is. The best explanation is that it "magically" works.

We know that there is no magic in programming, <Marker content="Though it certainly seems like it at times." /> and so we should do our best to remove "magic" from our code so that future you or others understand what we write today more clearly.

Here are some common "magic values" I save as variables in my code.

Time related numbers

Let's say we are comparing two Dates and we want to see if they are within three days of each other. We could do:

function isWithinThreeDays(date1, date2) {
  const difference = Math.abs(date1 - date2)
  return difference <= 259200000
}

Now, you might be clever enough to figure out that 259200000 is the number of milliseconds in three days, but I doubt you would figure it out with a quick glance. Better is:

const DAY_IN_MS = 1000 * 60 * 60 * 24

function isWithinThreeDays(date1, date2) {
  const difference = Math.abs(date1 - date2)
  return difference <= DAY_IN_MS * 3
}

Now our number isn't so "magic" anymore. It's a lot easier to understand that we're comparing difference with three days worth of milliseconds.

`localStorage` keys

If I ever have to store something in localStorage for an app, I make sure to turn my storage key into a constant variable. This way I have a single string declared, but a variable I can use over and over and over and know with certainty it will be correct. No typos possible.

const STORAGE_KEY = 'kyleshevlin:theme'

const currentTheme = localStorage.getItem(STORAGE_KEY)

const updateTheme = theme => localStorage.setItem(STORAGE_KEY, theme)

Regexes

Assuming you are a human, you probably can't read complicated regexes with full comprehension at a glance. Better to give your patterns a really good variable name and use that in your program. Would you rather have:

function isValidEmail(email) {
  return /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/.test(
    email.toLowerCase()
  )
}

Or this?

// You can even go the extra mile and leave a comment about the pattern
// or the URL where you found it: https://stackoverflow.com/questions/46155/how-to-validate-an-email-address-in-javascript
const VALID_EMAIL_PATTERN = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/

function isValidEmail(email) {
  return VALID_EMAIL_PATTERN.test(email.toLowerCase())
}

Summary

Avoid "magic values" in your code. Don't be afraid to pull strings, numbers and more out and give them some context with a great name. It'll prevent bugs in your code from typos, and make your programs easier to understand in the future.

`useMemo` and Stable Values

Tue, 08 Jun 2021 00:00:00 GMT

The most common pattern I use when writing custom React hooks is to return a tuple of [state, handlers]. state is the value held by the hook, and handlers is an object with methods that update the state. <Marker content="I really need to write a post about this pattern next." /> The way I write the handlers object typically raises some questions. <Marker content="And potentially a few eyebrows." /> I'll show you an example from a basic useSwitch hook.

function useSwitch(initialState = false) {
  const [state, setState] = React.useState(initialState)

  // PAY ATTENTION HERE
  const handlers = React.useMemo(
    () => ({
      on: () => {
        setState(true)
      },
      off: () => {
        setState(false)
      },
      toggle: () => {
        setState(s => !s)
      },
      reset: () => {
        setState(initialState)
      },
    }),
    [initialState]
  )

  return [state, handlers]
}

The typical question I get, and why I'm writing this post, is "Why did you use useMemo instead of several useCallbacks?"

The answer has two parts, but both are straightforward:

useMemo is the simplest way I know to create a stable value
A handlers object of methods is the nicest API I can provide my hook users

Creating stable values

useMemo returns a memoized value. Learn about memoization here if you need to first. This means that as long as the dependencies don't change, useMemo will return the cached value from when it was previously computed. It is made clear in the docs that this is not a guarantee, but for all intents and purposes, we can treat it like it is one. <Marker content="Recalculations when no dependencies have changed are rare." /> Therefore, we can use useMemo to eliminate value changes that may cause unnecessary renders downstream. I have found useMemo especially useful for values stored by reference: arrays, objects, sets, etc, and hence why I use it for my handlers object.

Nice APIs

Often, the abbreviation API is reserved for the interface for getting items from a database or a service, but often I think about what I'm returning from a function as an API as well. I think this is the best way to think about custom React hooks. Ask yourself, "What API am I giving users of this?" as you design it.

When it comes to custom hooks, the API pattern of a tuple of [state, handlers] is very simple, yet flexible for the user. Perhaps my user only needs one method from handlers. Or needs to rename a method to be more semantically accurate for their purposes:

function Door() {
  const [isOpen, { toggle }] = useSwitch(false)

  return (
    <div>
      <p>The door is {isOpen ? 'open' : 'closed'}.</p>
      <div>
        <Button onClick={toggle}>Toggle door</Button>
      </div>
    </div>
  )
}

Imagine if I did not use an object for my handlers? What if we wrote it as a collection of useCallbacks instead?

function useSwitch(initialState = false) {
  const [state, setState] = React.useState(initialState)

  const on = React.useCallback(() => {
    setState(true)
  }, [])

  const off = React.useCallback(() => {
    setState(false)
  }, [])

  const toggle = React.useCallback(() => {
    setState(s => !s)
  }, [])

  const reset = React.useCallback(() => {
    setState(initialState)
  }, [initialState])

  return [state /* WHAT DO I DO HERE? */]
}

Do I return each callback as a positional item in the tuple? No! That would be a pain in the ass.

function useSwitch(initialState = false) {
  // ... all the code from before
  return [state, on, off, toggle, reset]
}

function Door() {
  // you can skip items while array destructuring by not assigning the value
  // at that index a variable name
  const [isOpen, , , toggle] = useSwitch(false)

  // ... the rest of the code
}

So we're back to putting them in an object:

function useSwitch(initialState = false) {
  // ... all the code from before
  return [state, { on, off, toggle, reset }]
}

But that object is getting recreated every render. <Marker content="So is the array literal, but try not to fixate on that too much. You can stabilize that, too, if you'd like." /> Might as well use useMemo and return a stable object. They're practically never going to change anyways!

Summary

useMemo is a way of creating stable values. It can be useful for values stored by reference, like an object of methods. Use it to optimize the performance of downstream consumers of that value. That's it.

Symbolic Logic

Wed, 12 May 2021 00:00:00 GMT

In college, I double majored in Philosophy and Mathematics. A required class for both of those majors was one called Symbolic Logic, or often referred to as Propositional Logic. The course teaches you to break arguments down into an algebraic notation and follow a set of principles to come to logically sound conclusions.

I have found that as a software engineer I frequently use the principles this course taught me in my programming. I may not look at some code and specifically say out loud, "That's a modus ponens" or "That's a hypothetical syllogism", but I know they're there. <Marker content={I have said, "I can use DeMorgan's Law here," many times.} />

My hope with this post isn't to radically change your ability to code, but rather give you some vocabulary for discussing logic in your programs and more.

Foundational knowledge

There are a few things you need to know before reading the rest of this post. I'm going to express all of these logical principles with pseudo-code as best as I can. This accomplishes two things (at least). First, it makes it easier for me to type (rather than using the formal symbols more commonly used in textbooks on the subject). Second, it is my hope that using a code-like syntax will help you relate the concepts to your coding work more easily, therefore improving the learning of the concepts.

In my pseudo-code, I will be using the traditional letters used in symbolic logic, p and q, as placeholders for propositions. You can think of them as variables in our logical equations. To the best of my knowledge, p was chosen as an abbreviation of "proposition", and then letters are chosen by alphabetical order. Just like real variable names, you can choose to replace them with something more meaningful if that helps you.

Here is a small legend of my pseudo-code:

p or q represent propositions, or elements of an argument
=> is used for "entails". It can also be read as "If p, then q"
--- is used to indicate the end of the original set of propositions. What follows are conclusions derived from those propositions.
! is used for "negation"
& is used for "and"
| is used for "or"
=== is used for "material equivalence"

Certain conclusions can only be derived from applying other logical principles. When a principle is applied, an abbreviation of the principle's name, as well as the line numbers of the propositions required to impart that principle, will be noted next to the conclusion.

Rules of Inference

The first set of logical rules we are going to discuss can be categorized as "rules of inference". That is, from the information at hand, we can logically deduce a set of conclusions. This set of logical principles may be useful in debugging programs, as they will teach you to arrive at sound conclusions given the information you have. Let's get started.

Modus Ponens

Modus ponens is the most foundational rule of inference we can learn. I would tell you what the Latin means, but honestly, I think it would only add confusion rather than clarity, so I'll leave you to read the wiki on it on your own. The rule reads as follows:

If p, then q. p is true, therefore q.

And in our symbolic logic format, it looks like:

1. p => q
2. p
---
3. q   1,2 M.P.

If one proposition entails another and the first proposition is true, we can conclude that the second proposition is true. We use this all of the time in programming:

if (data) {
  doSomethingWith(data)
}

This principle is also used frequently when debugging code. If you do not have the result you would expect from a condition, then you must not have a truthful condition.

The opposite, if I have the result I expect, then I must have a truthful condition, cannot be logically deduced and is a common fallacy known as "affirming the consequent". The reason this fails is that there may be other propositions that entail q other than p. Be careful when you program in making this fallacy. Getting the right result doesn't necessarily guarantee it got there by the path you expected. Always verify.

Modus Tollens

Our next rule of inference is modus tollens, whose Latin meaning might also cause more confusion than clarity, wiki here. It is closely related to modus ponens. It follows:

If p, then q. Not q, therefore not p.

And in symbolic form, reads as:

1. p => q
2. !q
---
3. !p   1,2 M.T.

I have always found modus tollens fascinating. Heuristically, we would gravitate towards saying, "Not p entails not q", but this isn't quite true. Why? Because other elements of the universe can cause q. We only know with certainty that the truthful condition of p entails the consequent of q. Thus, we also know with certainty, that the absence of q ensures the absence of p.

In programming, if we know that we have written a condition correctly, and we do not get the desired result, than we can deduce we have not met our condition. Worse than not meeting the requirements our condition, is knowing we have not satisfied our condition and, yet, our desired result still occurs. That, my friends, is a bug.

Conjunction and Simplification

No more Latin principles. I promise. Our next rules can be considered partners, and therefore will be taught together.

conjunction is the combining of two propositions: p, q, therefore p & q.

1. p
2. q
---
3. p & q   1,2 Con.

Simplification is taking a conjunction and reducing it to one of its propositions: p & q, therefore p.

1. p & q
---
2. p   1 Simp.

In programming, we create a number of conjunctions and simplifications all the time. A conjunction could be creating a condition based on two different values, and a simplification could be the destructuring of a key/value from an object.

Hypothetical Syllogism

This logical principle is sometimes known as "double modus ponens", you'll soon see why.

p entails q and q entails r. Therefore, p entails r.

1. p => q
2. q => r
---
3. p => r   1,2 H.S.

For me, hypothetical syllogism just makes sense, which has always made it a bit difficult to explain to others. Essentially, it's a chain of modus ponens, and removing the middle link in that chain.

It is closely related to the transitive property. For example, in math, if you had x > y and y > z, then you can infer that x > z.

In programming, correct usage of hypothetical syllogism may show you that you're able to reduce a few steps in a particular program, recognizing that one antecedent, p entails a further consequent, r.

Absorption

This one is probably the first oddball we're going to encounter and it might not be terribly useful for programming, though there might be times it is useful in debugging. Absorption goes as follows:

If p, then q. Therefore, if p, then p & q.

1. p => q
---
2. p => p & q   1 Abs.

The premise of this principle builds upon a conjunction. If a condition leads to a result, then it is true that having that condition means having both the condition and the result. Another way to think about this is, the condition doesn't disappear because it has led to a result. It is still present, and therefore, can be combined with the result to make new inferences.

Disjunctive Syllogism

This one might seem odd at first, so I'll give you an insight right away. The key to understanding disjunctive syllogism is understanding that when | is used, it guarantees that one of the premises is true. The rule goes as follows:

p or q. Not p. Therefore, q.

If we have a scenario where we have one premise or another, and we know for certain that we do not have one of them, we can deduce that we have the other. In our symbolic format, it looks like this:

1. p | q
2. !p
---
3. q   1,2 D.S.

This one might be a bit harder to use directly while programming. The best scenario I can think of is if you have a condition that's being met based on an ||, and you know for certain that one of the operands is false, then you know the other is true.

Constructive Dilemma

This rule of inference is is essentially combining modus ponens with disjunctive syllogism. The rule goes:

p entails q, and r entails s. p | r. Therefore, q | s.

We have two entailment clauses, this antecedent leads to that consequent. If we have a premise that says we have one or the other antecedent, in this case p | r, then it follows that we have one or the other consequent q | s. In symbolic form, it looks like this:

1. (p => q) & (r => s)
2. p | r
---
3. q | s   1,2 C.D.

A constructive dilemma essentially occurs whenever we have multiple conditional statements in some code. If we have multiple if statements, we can think of those as entailments clauses. Because we know the set of antecedents, we also know the set of consequents that come from those if statements.

function passwordStrength(str) {
  if (!str) return
  if (meetsTheseConditions(str)) return 'weak'
  if (meetsTheseOtherConditions(str)) return 'strong'
}

Here we have three if statements and the set of their consequents contains weak, strong, or undefined. If we extrapolate this, we can see we have multiple constructive dilemmas.

1. noString => undefined
2. weakString => 'weak'
3. strongString => 'strong'
---
4. (noString => undefined) & (weakString => 'weak')   1,2 Conj.
5. (noString => undefined) & (strongString => 'strong')   1,3 Conj.
6. (weakString => 'weak') & (strongString => 'strong')  2,3 Conj.
7. undefined | 'weak'   4 C.D.
8. undefined | 'strong'   5 C.D.
9. 'weak' | 'strong'   6 C.D.

Addition

p, therefore p | q.

This one's odd, but useful for meeting the requirements for other logical principles. Essentially, if you have a proposition, then you have that proposition or any other proposition in the universe.

1. p
---
2. p | q   1 Add.

I'll come up with a rudimentary symbolic logic problem to show you what I mean. Let's combine addition with constructive dilemma. I'll give a set of premises and a conclusion we should be able to reach.

1. (p => q) & (r => s)
2. p

How do we prove the conclusion q | s? We can do the following:

3. p | r   2 Add.
4. q | s   1,3 C.D.

Rules of Replacement

The next set of principles we will learn are known as "rules of replacement". These rules will teach us logically sound ways of swapping one set of premises for another. These rules can often be applied when trying to improve the legibility or even the performance of some code.

Double Negation

p === !!p

We are all not unfamiliar with this concept, right? <Marker content="See what I did there?" /> Or would it be better to ask, "We are all familiar with this concept, right?"

The most common time you'll see this in coding is if you come across the "double bang" !!. This is often used in JavaScript to coerce a value into a boolean. It is the equivalent of calling Boolean(value). I prefer to use Boolean(). It's easier to read.

Commutation

p | q === q | p as well as p & q === q & p

The rule of commutation means that, for certain logical operations, the order of the arguments does not matter. | and & are commutative operations. In mathematics, + and * are commutative.

This rule can actually be useful in optimizing our program's performance. In JavaScript, when using a logical operand such as && or ||, we can improve performance by making the left side of the operation a case that is most like to "short circuit" the operation.

Short circuiting a logical operation occurs when the left side of the infix operator guarantess the result. If the left side of conjunction is false, as in false && ..., then the right side is irrelevant and not evaluated. Similarly, if the left side of a disjunction is true, as in true || ..., then the right side is irrelevant and not evaluated. We can use this to our advantage. Let's make an example.

Let's say I want to determine if I should wear my rain jacket. I only wear my rain jacket when it's both cold and raining.

const requiresRainJacket = weather => isCold(weather) && isRaining(weather)

Now, consider the order of functions here. As written, we'll only get to the isRaining check if it's cold. Is this the best order? I live in a pretty cool climate, it could probably evaluate that function to true for 7-8 months of the year. <Marker content="I run pretty cold, wear a hoodie most of the year" /> Two-thirds of the time, our function won't short circuit. Arguably, the isRaining check is more important, and more likely to short circuit than the isCool check. So we can gain a slight improvement by flipping the conditions.

const requiresRainJacket = weather => isRaining(weather) && isCold(weather)

Tautology

p === p | p as well as p === p & p

This one is quite possibly my favorite. <Marker content="It also has pretty much no practical use in programming. Sorry." /> A tautology is when we say that some thing is that thing. Like, the weekend is the end of the week. It's the kind of thing that when you were a kid you might have responded with a loud and emphatic, "Duhhh!".

In symbolic logic, we can use tautologies to achieve propositions that enable the inference of other propositions.

Association

(p | (q | r)) === ((p | q) | r) and (p & (q & r)) === ((p & q) & r)

This rule of replacement may have you thinking we're writing a LISP with all the parentheses. This is similar to commutation, in that the rule of association says that, for certain logical operations, the grouping of operations does not matter. Again, this is similar to how in mathematics, if all the operations of an equation are + or *, it doesn't matter which one you do first.

It's not often that this will come up in programming. In fact, it's more likely to come up when something is not associative. In other words, sometimes you'll find a bug when you're parentheses group conditions in the wrong way. It's quite likely if the operations are associative, than your formatter may remove the groupings altogether.

Transposition

p => q === !q => !p

Transposition is a replacement that we can see derives from modus tollens. In programming, sometimes it is easier to read or write that the negation of one thing results in the negation of the other. Another way to think about this is "absence". Sometimes it can be easier to say, "The absence of this condition results in the absence of this other condition". Hopefully, that's some food for thought.

Material Implication

p => q === !p | q

This rule of replacement is the logical conclusion of a modus ponens. If we have an entailment, where a condition leads to a result, then we can conclude that, at any given time, we either don't have a truthful condition or we have the result.

In programming, we can recognize that either a condition isn't met or its result exists.

// There is no universe where the condition is false
// && the result exists simultaneously. They are mutually
// exclusive propositions

if (condition) {
  return result
}

Exportation

(p & q) => r === p => (q => r)

When I first started writing this rule of replacement, I thought, "There's no way this is useful", but then I realized that exportation happens all the time. The rule works like this: If a consequent is the result of a conjunction, then we can simplify that conjunction, and deduce that one condition leads to the entailment of the rest. <Marker content="Confusing, I know. Give me a minute to explain." />

A simpler way to understand this, is probably just to see it. Have you ever written code like this?

if (thisCondition) {
  if (thisOtherCondition) {
    // ... some result
  }
}

If you have, then you've written the right side of an exportation. Can you see it? The logical replacement is:

if (thisCondition && thisOtherCondition) {
  // ... some result
}

Now, I bet you've done that refactor a lot. Combine this with "short circuiting", and you may have vastly improved some nasty nested if-else code. Might I suggest you read my post "When elses Make Your Code Worse" some time.

Material Equivalence

(p === q) === ((p => q) & (q => p)) and (p === q) === ((p & q) | (!p & !q))

This one is fairly complex looking, but breaking it down makes it more digestible.

Two propositions are equivalent if it can be demonstrated that they entail one another. Two propositions are also equivalent if it can be demonstrated that their conjunction is true or the conjunction of their negations is true.

Distribution

(p & (q | r)) === ((p & q) | (p & r)) and (p | (q & r)) === ((p | q) & (p | r))

The rule of distribution is the same for math as it is for symbolic logic. You might recall from an algebra class having an equation that looked like 3(2x + 4y) = 42. You might be required to distribute the 3 to make it 6x + 12y = 42. Or the opposite, factoring out the 3 if you had been given the latter equation. It works the same way for logic.

You can see this in complicated conditional code sometimes:

if (conditionA) {
  if (conditionB || conditionC) {
    // ... some result
  }
}

That's the same as:

if ((conditionA && conditionB) || (conditionA && conditionC)) {
  // ... some result
}

De Morgan's Theorems

!(p & q) === (!p | !q) and !(p | q) === (!p & !q)

Saving the best <Marker content="Best is debatable." /> and most useful for last. You should probably memorize this one.

The negation of the conjunction of two premises is equivalent to the disjunction of the negation of each premise. Also, the negation of the disjunction of two premises is equivalent to the conjunction of the negation of each premise.

Simple, right?

Let's use a code example to make it simpler. Let's say we have an item and we want to determine if it's notForSale:

const notForSale = !(inStock(item) && hasPrice(item))

This might be easier to read and understand as:

const notForSale = !inStock(item) || !hasPrice(item)

Same thing goes for ||s. Maybe we want to determine if an event is coming soon:

const isUpcomingSoon = !(inThePast(event) || isBeyondThreshold(event))

// is the same as
const isUpcomingSoon = !inThePast(event) && !isBeyondThreshold(event)

Knowing De Morgan's Theorems can help you refactor tricky conditionals into more legible code for you and your team.

Conclusion

And that's it. Everything there is to learn about symbolic logic. <Marker content="It's not." /> Truthfully, this is just scratching the surface. I hope that there's something in this post that inspires you and maybe helps you in a refactor or two.

Set Theory

Wed, 21 Apr 2021 00:00:00 GMT

I find Sets and set theory to be a fascinating concept, both in the abstract <Marker content="As a mathematical and philosophical concept." /> and in the concrete <Marker content="I enjoy using them in JavaScript" />, and one that I find more and more useful as time goes on. I've wanted to write an introductory post on the topic for a while now and hope it might inspire a similar interest in Sets for you.

What is a Set?

A Set is a collection of unique elements. Those elements can be literally anything. There exists the set of all integers that are factors of 3, the set of all aquatic mammals, the set of all of my siblings.

A Set can be full of many elements, such as the set of all blades of grass in my lawn <Marker content="Sorry, looking at my backyard as I write this!" />, or a set can be empty, such as the set of all humans living on planets other than Earth.

Sets, in the abstract, also don't have a sense of "order". If I'm talking about the set of all whole numbers between the values of 1 and 5, they do not necessarily need to come in the order: 1, 2, 3, 4, 5. They can be thought of just as equally in the order: 2, 1, 4, 3, 5 or any other order. <Marker content="In the concrete, a <code>Set</code> data structure in JavaScript does have order and can be iterated over with <code>for..of</code>" /> In this way, Sets are like bag data structures.

Throughout the rest of this post, I will be using drawings to aid in my explanation, so to get started, here's a Set:

It is important to note that Sets often exist within a universe:

Sets interacting with other Sets

Sets become far more interesting (and useful) when we consider how they interact with one another.

Unions

The union of Set A and Set B is the Set containing all the elements from Set A and all the elements from Set B.

function union(setA, setB) {
  // Make a copy
  const result = new Set(setA)

  for (let element of setB) {
    result.add(element)
  }

  return result
}

Intersections

The intersection of Set A and Set B is the Set containing the elements in Set A that are also in Set B. You may recognize this as a Venn Diagram.

function intersection(setA, setB) {
  const result = new Set()

  for (let element of setA) {
    if (setB.has(element)) {
      result.add(element)
    }
  }

  return result
}

Differences

The difference of Set A and Set B is the Set containing all the elements from Set A that are not in Set B.

function difference(setA, setB) {
  const result = new Set()

  for (let element of setA) {
    if (!setB.has(element)) {
      result.add(element)
    }
  }

  return result
}

Note that the difference between two sets is dependent upon the order of the arguments. That is, given that Set A and Set B are not equal sets, then difference(setA, setB) will not be equal to difference(setB, setA)

Symmetric differences

The symmetric difference of Set A and Set B is the Set containing all the elements that are not shared by Set A and Set B.

function symmetricDifference(setA, setB) {
  const result = new Set()

  for (let element of setA) {
    if (!setB.has(element)) {
      result.add(element)
    }
  }

  for (let element of setB) {
    if (!setA.has(element)) {
      result.add(element)
    }
  }

  return result
}

Note, unlike difference, symmetricDifference will achieve the same result regardless of argument order. In this case, symmetricDifference(setA, setB) will result in the same set as symmetricDifference(setB, setA).

Complements

The complement of a Set A is the Set containing all of the elements not in Set A. By default, this would be all the other elements in the universe, but when constrained, complements can be useful.

For example, the symmetric difference of Set A and Set B is equivalent to the complement of the intersection of Set A and Set B. We can figure this out by first creating the union of Set A and Set B, then their intersection, and then getting the difference of those two results.

const all = union(setA, setB)
const shared = intersection(setA, setB)
const notShared = difference(all, shared)

Subsets and Supersets

Set A is a subset of Set B if every element of Set A is in Set B.

We can make use of Array.prototype.every to help us with this one.

function subset(setA, setB) {
  return [...setA].every(element => setB.has(element))
}

Set A is a superset of Set B if Set B is a subset of Set A.

function superset(setA, setB) {
  return [...setB].every(element => setA.has(element))
}

Subsets and supersets are useful when categorizing elements. For example, React is a subset of JavaScript. If someone tells me that they know React, I can safely deduce that they know some JavaScript as well. However, if someone tells me they know JavaScript, I cannot deduce that they know some React. They might, they might not.

Disjointed Sets

Set A and Set B are considered disjointed if they share no elements.

Another way to think about disjointed sets is that their intersection is the empty set, and therefore has a size of 0. We can use that to determine if two sets are disjointed or not.

function disjoint(setA, setB) {
  return intersection(setA, setB).size === 0
}

It is not uncommon to create disjointed unions, as we will soon see.

Where am I using Sets without maybe realizing it?

Type systems!

When you describe a value as the type string, what you're really saying is that this value belongs to the Set of all strings. When you type an array as Array<number>, you're saying that this array belongs to the Set of all arrays containing numbers.

This is why types that use | and & are called union types and intersection types respectively.

If I have a type that is string | number, I'm really saying that this item belongs to the union of the set of all strings and the set of all numbers. This is a disjointed union, since it's impossible for a value to be both shared by the set of strings and the set of numbers. <Marker content="The string of a number is still a string, at least for the sake of types and sets." />

Are there practical uses?

Quite a few, but you have to get used to looking for them. I have used sets for tag/category systems (I use Sets for my tags on this site). I've used them for making efficient filtering systems, too. It's sometimes easiest to think of filtering items in terms of unions and intersections.

Another place you've probably seen them over and over is in vector drawing tools. Take a look at Figma for instance. If I make two vector shapes, select them both and then look at my options, don't these look strangely familiar? They even use some of the same words to describe the operation.

At its core, manipulating vector graphics is as simple as doing some Set operations. Every shape is a Set of points, and we can use the operations to manipulate those points into complex shapes.

Summary

Sets are a collection of unique elements. Learning the fundamentals of Sets and set theory may open up some new ways of thinking of operating with data for you. Your mileage may vary. At the very least, I hope you find words like "unions" and "intersections" less intimidating (if they ever were at all).

Resources

There's one specific library I like to share with people in regards to Sets that I want to share with you: Zet. It's incredibly simple and excellent. I encourage you to read the source code as well.

Additional Notes

It's worth noting that there are proposals to improve Sets in JavaScript in the works: https://github.com/tc39/proposal-set-methods. The work here will replace the need for libraries like Zet in the future.

What is a Tuple?

Thu, 01 Apr 2021 00:00:00 GMT

As a JavaScript developer, we don't have an official Tuple data type like we do Array or Object, but that doesn't mean we don't have tuples in our code. In a post I'm working on, I realized I have several tuples in my code and it might be worth taking a minute to explain what a tuple is.

We get tuples from mathematics. A tuple is a finite, ordered list of elements. In JavaScript, this would be likely represented as an array. I can create a tuple to represent a person like so:

const personTuple = ['Kyle', 35, 'Portland, OR']

Looking at personTuple, we can see that it is a finite length of 3 items, and that those items are in a particular order: name, age, and location.

When might I use a tuple?

A tuple can be a convenient way to create and use key/value data.

"But Kyle, where are the keys? I don't see any!"

Good question.

If objects are explicit key/value stores, we can think of tuples as implied key/value stores. Remember, a tuple is an ordered list. We can't jumble up the items of the list without breaking the contract of the tuple. Therefore, we can infer the keys of a tuple by the order of the list.

For example, if I have a function that receives a personTuple, I should be able to safely array destructure and get the right order of values every time.

function personIntro(personTuple) {
  const [name, age, location] = personTuple

  return `Hi, my name is ${name}. I am ${age} years old from ${location}.`
}

Array destructuring makes the implicit key/value store of the tuple pretty clear.

Wait, are we using tuples all the time?

You are if you're using React! Think about what is returned to you everytime you use useState or useReducer. It's a tuple!

const [state, setState] = React.useState()

What is [state, setState] but a tuple? It is a [value, setter] tuple. Same goes for useReducer, but swap setter for dispatcher.

If I create a custom hook that returns [state, handlers], what have I done but created a tuple?

function useSwitch(initialState = false) {
  const [state, setState] = React.useState(initialState)

  const handlers = React.useMemo(
    () => ({
      on: () => {
        setState(true)
      },
      off: () => {
        setState(false)
      },
      toggle: () => {
        setState(s => !s)
      },
    }),
    [],
  )

  return [state, handlers]
}

Turns out tuples are everywhere.

What makes a tuple different than an array?

An array is generally a list of items of unknown and unforeseen length. It can hold a few items, a lot of items, or no items at all.

It's also more common for an array to be homogenous. That is, all the items in the list are the same type. You have an array of strings, an array of numbers, an array of person objects.

Tuples, on the other hand, are lists of items of known, foreseen length. They have a finite number of items. They are more often hetergenous, as well. Our personTuple from before had two strings and a number.

Tuples and type systems in JS

The distinctions between arrays and tuples are rather clear when using a type system with JavaScript, such as TypeScript or Flow. If we have an array of numbers, we may type it in either of the following ways in TypeScript.

const nums: Array<number> = [1, 2, 3, 4, 5, 6]

const nums2: number[] = [1, 2, 3, 4, 5, 6]

In either case, it's pretty clear that what we're returning is a homogenous array of numbers. It doesn't matter what length the array is, just that each item in it is of the same type.

Compare this to typing a custom React hook that returns state and handlers as a tuple.

type SwitchTuple = [
  state: boolean,
  handlers: {
    on: () => void
    off: () => void
    toggle: () => void
  },
]

function useSwitch(initialState = false): SwitchTuple {
  const [state, setState] = React.useState(initialState)

  const handlers = React.useMemo(
    () => ({
      on: () => {
        setState(true)
      },
      off: () => {
        setState(false)
      },
      toggle: () => {
        setState(s => !s)
      },
    }),
    [],
  )

  return [state, handlers]
}

Instead of a homogenous array type, like number[], we've instead given it a tuple type, clearly demarcating the state and handlers to be returned.

Summary

Tuples are ordered lists of finite length that can be used as implicit key/value stores. While JavaScript doesn't have a Tuple yet (there is a TC39 proposal to add it), you might already be using them. You may find them useful for particular algorithms, writing custom hooks and more.

Conditional React Hooks

Tue, 30 Mar 2021 00:00:00 GMT

You want to conditionally call a hook, but you can't do that because of rules. What do you do?

The answer is remarkably simple: Conditionally render a renderless component that uses the custom hook.

Many years ago, I coined the phrase "renderless component" in this blog post. It's a component that uses the lifecycle methods to update app state but has no associated UI. It renders null, hence "renderless". These days, replace "lifecycle methods" with "custom hooks", and the same concept applies and, therefore, we can achieve the same result.

If we call a custom hook in a component:

function AutoSave({ data }) {
  useAutoSave(data)
  return null
}

And then conditionally render that component in another component:

function Document({ data, shouldAutoSave }) {
  return (
    <div>
      {shouldAutoSave && <AutoSave data={data} />}
      <div>
        <Editor data={data} />
      </div>
    </div>
  )
}

I can't tell you when or why you may need to do this, but it's a little tool to throw in your toolbelt and pull out when the occasion calls for it.

Debounce and Throttle Callbacks with React Hooks

Tue, 23 Mar 2021 00:00:00 GMT

This one will be short and to the point. I recently ran into a problem while trying to create a debounced callback with React hooks. If you're using the react-hooks ESLint package with the recommended settings, then it will warn you that you can't do the following:

import React from 'react'
import { debounce } from 'lodash'

function Search({ onSearch }) {
  const [value, setValue] = React.useState('')

  // This use of `useCallback` has a problem
  const debouncedSearch = React.useCallback(
    debounce(val => {
      onSearch(val)
    }, 750),
    [onSearch]
  )

  const handleChange = React.useCallback(
    e => {
      setValue(e.target.value)
      debouncedSearch(e.target.value)
    },
    [debouncedSearch]
  )

  return <input type="text" value={value} onChange={handleChange} />
}

This looks fine, but here's the warning:

Error: React Hook useCallback received a function whose dependencies are unknown. Pass an inline function instead react-hooks/exhaustive-deps

useCallback expects an inline function. Handing it the returned function from a debounce or throttle doesn't cut the mustard. Why? The ESLint rule can't figure out what the exhaustive dependencies should be. How do we fix this?

It might seem odd, but useMemo comes to the rescue.

function Search({ onSearch }) {
  const [value, setValue] = React.useState('')

  // This is the solution
  const debouncedSearch = React.useMemo(
    () =>
      debounce(val => {
        onSearch(val)
      }, 750),
    [onSearch]
  )

  const handleChange = React.useCallback(
    e => {
      setValue(e.target.value)
      debouncedSearch(e.target.value)
    },
    [debouncedSearch]
  )

  return <input type="text" value={value} onChange={handleChange} />
}

Think about it. useMemo is used to store a memoized value that should only be recalculated when the dependencies change. So what if that memoized value is a function?

It wasn't obvious to me to do this at first, but it makes sense. We want the returned function, and we want it to have the correct exhaustive dependencies, and update whenever they change. useMemo does exactly that.

You can use this same technique with throttle, too. Really any higher ordered function that returns a function. Sky is the limit.

Lastly, credit where it's due. I came across this idea from this GitHub comment. Maybe give it a thumbs up if you found this helpful.

How to Use React Context Effectively

Thu, 11 Mar 2021 00:00:00 GMT

React Context has always been a somewhat controversial tool. It was an experimental API for the longest time, but was eventually made a standard part of the API. Now with React Hooks, React Context is easier to use than ever, but that also makes it easy to use poorly. In this post, I want to go over how I personally use React Context. I think you'll find it succinct and useful.

What is React Context?

Conceptually, I think of React Context as a wormhole component. It's designed to get a value from a Provider to all its distantly-related child Consumers, without passing the value through all the components in between. In short, it's a way to avoid "prop drilling".

How to create a Context

A Context is created with the React.createContext method.

const MyContext = React.createContext()

My first tip. Don't bother with providing a defaultValue. If you're consuming context without a Provider higher in the tree, either you're making a big mistake or you know exactly what you're doing. With no insult intended, it's more likely that you're making a mistake and not providing a defaultValue will provide a signal that there's a problem you need to fix. <Marker content="The exception to this is if you must provide a default value for a type system. Hopefully the types save your bacon in that scenario then." />

Creating a Context returns an object with two properties, Provider and Consumer, both of which are components. Providers are parent components that receive a value prop that they wormhole to all their Consumer children. Here's a quick example using a ThemeContext:

const ThemeContext = React.createContext()

function App() {
  return (
    <ThemeContext.Provider value="light">
      <Header />
      <Main />
      <Footer />
    </ThemeContext.Provider>
  )
}

function Header() {
  return (
    <ThemeContext.Consumer>
      {theme => {
        return (
          <header
            style={{
              backgroundColor: theme === 'light' ? '#eee' : '#111',
            }}
          >
            <Nav />
          </header>
        )
      }}
    </ThemeContext.Consumer>
  )
}

As you can see, the Header component consumes the ThemeContext with a Consumer component. The theme makes its way to the Header without needing to pass the value in as a prop. Now that you've seen how the Consumer component works, with the component and the render prop API, I want you to forget it. Obliterate it from your memory. I'm going to show you a better way to consume a Context soon enough.

Now that we understand roughly how to create and use a React Context, let's discuss some of the philosophy behind using it well.

Think locally before globally

It is tempting, once you learn React Context, to use it as a global store. It certainly can function that way and might even be effective, but I personally do not think of it this way. At least, it's not my first thought when I need global data.

In my opinion, Contexts should be related to a single concern and not a gathering place for all your data. Therefore, I find I use Context more often when working on a localized concern, such as a particular feature in my app.

It is possible to use globally, but you should at least pause before you do and consider if there's an alternative that might be more useful for your situation. If there is not, then that's fine. Don't sweat it and proceed with Context.

As we'll discuss soon, React Context can lead to a lot of rerenders if the data passed to the value prop changes frequently. If I must use a Context Provider at a high level in the tree, such as a ThemeProvider, I want to make sure this component does not change value often so that my app performs well.

Always export your own `Provider`

I cannot remember a single time in my years of writing React where there was a good reason for me not to create a custom Provider for a context. I do this like so:

const ThemeContext = React.createContext()

export function ThemeProvider({ children }) {
  return <ThemeContext.Provider value="light">{children}</ThemeContext.Provider>
}

Why do I do this? I do this so that I have full control over value. I do not want to give users of my Provider options that I do not explicitly control. I can give them props that will allow them to alter whatever value is eventually set to, but I am still in control. This prevents a number of future problems and encapsulates the concerns of the Context well.

Expose an API

The point of creating a Context, at least to me, is to define specifically how you want the Consumers to be able to interact with their corresponding Providers. Another way to say this is, if I'm going to provide Consumers with some state, I'm also going to provide them with the handlers for that state. I'm a big fan of providing specific state updaters to the consumers of my components, like so:

const ThemeContext = React.createContext()

export function ThemeProvider({ children }) {
  const [theme, setTheme] = React.useState('light')

  const handlers = React.useMemo(
    () => ({
      lighten: () => {
        setTheme('light')
      },
      darken: () => {
        setTheme('dark')
      },
      toggle: () => {
        setTheme(s => (s === 'light' ? 'dark' : 'light'))
      },
    }),
    [],
  )

  return (
    <ThemeContext.Provider value={[theme, handlers]}>
      {children}
    </ThemeContext.Provider>
  )
}

This might seem verbose to some of you, but by creating a handlers object with specific updaters for the theme state, we can guarantee that our theme state is never updated to a non-supported theme value.

Create a custom hook for your Context

There was a short window of time where we needed to use the Context.Consumer render prop pattern, but I haven't used it since React Hooks made consuming context significantly easier.

Rather than pass my Context object around and passing it into React.useContext in every component that needs it, I export a custom hook from the same file I create the Context instead, like so:

export const useThemeContext = () => React.useContext(ThemeContext)

Now, any component that needs to consume the ThemeContext can import useThemeContext and use it. Like so:

function Header() {
  const [theme, { toggle }] = useThemeContext()

  return (
    <header
      style={{
        backgroundColor: theme === 'light' ? '#eee' : '#111',
      }}
    >
      <Nav />
      <button onClick={toggle}>Toggle theme</button>
    </header>
  )
}

Optimize components that consume your custom hook

From the React docs:

All consumers that are descendants of a Provider will re-render whenever the Provider’s value prop changes.

Remember that quote. All Consumers rerender when the Provider updates, regardless of whether it is necessary or not. This means, if you're not careful, you could be causing a lot of unnecessary rerenders in your application. React makes us, the users of React, responsible for preventing unnecessary rerenders, so how do we do this for components that consume a context?

There are primarily two ways to accomplish. Both use memoization but in different ways.

The first way is to turn the component that consumes the context into a "container component" and to use React.memo on the "presentational component" that the container returns. Like so:

export function HeaderContainer({ children }) {
  const [theme, { toggle }] = useThemeContext()

  return <Header theme={theme} toggleTheme={toggle} />
}

const Header = React.memo(function Header({ theme, toggleTheme }) {
  return (
    <header
      style={{
        backgroundColor: theme === 'light' ? '#eee' : '#111',
      }}
    >
      <Nav />
      <button onClick={toggleTheme}>Toggle theme</button>
    </header>
  )
})

This works because we turn the value of the context into props that are passed to a memoized component. The memoized component only updates if the props change.

The second technique does not require an extra component, but instead uses React.useMemo to memoize what we return from the component that consumes the context. Like so:

function Header() {
  const [theme, { toggle }] = useThemeContext()

  return React.useMemo(
    () => (
      <header
        style={{
          backgroundColor: theme === 'light' ? '#eee' : '#111',
        }}
      >
        <Nav />
        <button onClick={toggle}>Toggle theme</button>
      </header>
    ),
    [theme, toggle],
  )
}

This strategy works by memoizing the output of our component. It only recalculates our output if one of the ThemeContext related values changes. <Marker content="It is likely someone will say, “That's not true!” and they would be pedantic, but also correct. The React docs mention that values memoized with <code>useMemo</code> might be recalculated without the dependencies changing, but it works how we expect most of the time and will never calculate incorrectly, so don't worry about it." />

Summary

That's it. That's how I use React Context effectively. To recap:

Don't worry about a default value
Think locally and small before globally
Make your own Provider
Expose an API
Export a custom hook, don't bother with a Consumer render prop component
Memoize the components that consume the context, either by:
- Container and React.memoized presentational components
- React.useMemo the component's output

Hope this helps you use React Context more effectively in your apps.

Facade Pattern

Wed, 17 Feb 2021 00:00:00 GMT

We live in exciting times (for JavaScript developers). There's almost a library for everything you can imagine on npm and you can add packages to your projects so quickly. It's really quite a bit of fun when you take a second to think about it.

However, this ability to quickly grab and use packages hides some technical debt you might be creating when you do so. There's a reason these packages are called "dependencies", and if you're not careful, you can wind up dependent upon something that is terribly difficult to manage or remove later.

To that end, I want to introduce you to a pattern of programming called the "facade pattern". I get the term from the "Gang of Four" (aka GoF) book, Design Patterns. It's a classic piece of computer science literature on the topic of object oriented programming. I don't talk much about OOP, but there are plenty of patterns and goodies to borrow from it. Use the link above if you'd like to check it out.

Essentially, the facade pattern is this: we add a layer of abstraction between the consumer of some code and the implementation of that code. In regards to packages like I'm describing above, it's creating a wrapping function or class that uses the package (or several). There are at least 2 reasons to do this:

Greater control of the exposed API

Often a facade pattern is used to simplify a more complex class, object, or function's implementation from the consumer of the facade.

To give yourself the flexibility to later swap packages and other implementation details without affecting the code that uses the facade

With the facade pattern, we're able to hide details "under the hood", changing them when necessary without affecting the API exposed by the facade and consumed by the rest of your application. I want to explore these two reasons in this post.

When to Use a Facade Pattern

There are some libraries so essential to your work that wrapping them in a facade would provide no benefit. If your project is built in React, it doesn't make sense to wrap the React library in a facade because you'll probably want access to its entire API and you won't be swapping out any implementation details under the hood of your facade. React would be such an essential part of your project that if you change it, you want to have to change everything else, too.

On the other hand, libraries for fetching data, date formatting, and more can make good candidates for the facade pattern. Let's look at fetching data as an example.

For a long time, and perhaps in many of your apps still, the axios library was a popular way to fetch data. You might have used it directly in some code somewhere like this:

import React from 'react'
import axios from 'axios'

function DetailPage({ id }) {
  const [data, setData] = React.useState(null)

  React.useEffect(() => {
    axios
      .get(`your/api/url/pages/${id}`)
      .then(res => res.json())
      .then(json => {
        setData(json)
      })
  }, [id])

  return data !== null && <div>{JSON.stringify(data, null, 2)}</div>
}

Now, imagine you have dozens, maybe hundreds or more components that are similar. They're fetching and posting data around your app, all using axios directly.

One day, your team decides that you want to drop the axios dependency and switch to using fetch instead. What's your immediate thought? I bet it's something like, "Oh shit! Now I have to change every single place we use axios!"

Not a fun thought to have.

You might get lucky. You might be able to write a codemod that can manage the problem, but what if you never put yourself in that situation in the first place? If we use a facade pattern, we can hide axios under the hood, only consuming it in a single place. Something like:

// API.js
import axios from 'axios'

export default class API {
  get(url) {
    return axios.get(url)
  }

  post(url, options) {
    return axios.post(url, options)
  }

  // other methods, you get the idea...
}

// DetailPage.js
import React from 'react'
import API from './API'

function DetailPage({ id }) {
  const [data, setData] = React.useState(null)

  React.useEffect(() => {
    API.get(`your/api/url/pages/${id}`)
      .then(res => res.json())
      .then(json => {
        setData(json)
      })
  }, [id])

  return data !== null && <div>{JSON.stringify(data, null, 2)}</div>
}

Now if we want to replace axios, we simply update the implementation details of our API facade without having any affect on our components. Let's replace it with native fetch:

// API.js
export default class API {
  get(url) {
    return fetch(url)
  }

  post(url, options) {
    return fetch(url, {
      method: 'POST',
      ...options,
    })
  }
}

Not only was it really painless to swap the implementation, it allowed us to manage some details and complexity that the consumers of our facade don't need. In this case, we bake in the method value of POST on the post method, so that our users don't have to change the instances of API.post() in the application.

Now, because of our facade, if another great library for fetching data comes along that has features we want over native fetch, we can update the implementation of API with out needing to change any of our components that use it.

Additional Thoughts

Admittedly, I haven't had a chance to really try this pattern out on a massive codebase. I want to be upfront with you about that. I have been thinking about it a lot, though, because of some of the challenges I have seen at work. It's really easy to stuck for years using some outdated library because it has become too essential to the application. I think using this pattern on key parts of your project could save you from a massive overhaul in a few years.

For example, right now your project might use the moment library, but you'd like to try date-fns instead. A facade would make that possible. You probably only use about 25% of the library anyways, so only expose what you need from it. With a facade already in place, it will certainly make it easy to switch to Temporal when it lands. <Marker content={<code>Temporal</code> is a new datetime object coming to JavaScript. You can read more here: <a href="https://github.com/tc39/proposal-temporal">https://github.com/tc39/proposal-temporal</a>} />

There are some tradeoffs to consider, too. You are adding a layer of abstraction that will likely require documentation. How else will you and your team know how to use the facade? Also, creating code means you're responsible for its maintenance and improvements. It's not as simple as just using another method or function from the library. You have to put in the work to update the facade if there are features of the underlying library you want to use. But it still might be a tradeoff worth making, hiding complexity that can be swapped or improved in the future. You'll have to decide for yourself.

useEncapsulation

Thu, 28 Jan 2021 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

Update November 22nd, 2021: I added a recording of my CascadiaJS on this topic to the end of this post. Enjoy!

Recently, I shared this tweet:

<SocialPost authorName="Kyle Shevlin" authorHandle="@kyleshevl.in" authorProfile="https://bsky.app/profile/kyleshevl.in" avatarUrl="/images/kyle-headshot.jpg" date="2020-11-23" content={` 🔥 take I haven't fully thought through incoming: Every use of useEffect should be in a custom hook with a damn good name.

It's frequently difficult to read & comprehend intention of the code when effects are strewn about. Better to encapsulate and provide context. `} />

This tweet was my response to some refactoring of our codebase, but having more than a month now to practice this a few more times, I'm convinced this pattern is the right way to go. I'll go further and say most uses of React hooks should be encapsulated in a custom hook, and I'm going to try and convince you of that on this post.

Before we get started, it will benefit you greatly if you read my post on encapsulation first. In that post, I argue that the primary purpose of a function is to encapuslate all the elements of a concern together into a single structure. We're going to apply this pattern to how we work with React Hooks.

The Problem

Given the nature of our work, that requirements change frequently and therefore code changes frequently, too, it is not surprising that our codebases become messy. Our logic gets strewn about like tools left on a workbench. The problem is that hidden in the mess of functions and objects is important information that is getting lost. Important historical decisions left without explanation or context and more. I'll try to come up with a contrived example quickly.

Imagine we have a Component that can be toggled into two states: off and on. We'll use React Hooks to set this up.

function Component() {
  const [state, setState] = React.useState('off')

  const on = React.useCallback(() => {
    setState('on')
  }, [])

  const off = React.useCallback(() => {
    setState('off')
  }, [])

  const toggle = React.useCallback(() => {
    setState(s => (s === 'on' ? 'off' : 'on'))
  }, [])

  return (
    <div>
      <div>State: {state}</div>
      <div>
        <button type="button" onClick={on}>
          Turn On
        </button>
        <button type="button" onClick={off}>
          Turn Off
        </button>
        <button type="button" onClick={toggle}>
          Toggle
        </button>
      </div>
    </div>
  )
}

Alright, so far so good. Our Component is pretty simple so far and it feels like all of its concerns are handled in an orderly way. But requirements change and now perhaps our component also needs an input field (don't ask me why, I told you this is contrived).

function Component() {
  const [toggleState, setToggleState] = React.useState('off')
  const [inputState, setInputState] = React.useState('')

  const on = React.useCallback(() => {
    setToggleState('on')
  }, [])

  const off = React.useCallback(() => {
    setToggleState('off')
  }, [])

  const toggle = React.useCallback(() => {
    setToggleState(s => (s === 'on' ? 'off' : 'on'))
  }, [])

  const handleInputChange = React.useCallback(e => {
    setInputState(e.target.value)
  }, [])

  const resetInput = React.useCallback(() => {
    setInputState('')
  }, [])

  return (
    <div>
      <div>State: {toggleState}</div>
      <div>
        <button type="button" onClick={on}>
          Turn On
        </button>
        <button type="button" onClick={off}>
          Turn Off
        </button>
        <button type="button" onClick={toggle}>
          Toggle
        </button>
      </div>
      <div>
        <label htmlFor="randomWord">Random Word</label>
        <input
          type="text"
          id="randomWord"
          onChange={handleInputChange}
          value={inputState}
        />
        <button type="button" onClick={resetInput}>
          Reset Input
        </button>
      </div>
    </div>
  )
}

Are you starting to see the problem I'm seeing? Even though we wrote relatively clean and clear code, we have started to create a gap between related implementation details.

We need to call our hooks in the same order every render of Component. Those are the rules. To accomplish this, we've followed a common organizational pattern with our declarations of state near the top of our component and our various event handlers further down. But in following this pattern, we've separated the toggle state and its event handlers with the interruption of declaring another instance of useState. Even worse, our input state is separated from its related handlers by three unrelated function declarations. Just imagine this in your codebase and I'm sure you've seen far worse! This can quickly become a nightmare.

There is, fortunately, a very simple solution: custom hooks.

Why Custom Hooks are the Solution

A custom hook is just a function and functions are structures we can use to encapsulate the related elements of a concern and expose an API to our function's consumer. In the case of our Component, these custom hooks are fairly simple to create.

function useOnOff() {
  const [state, setState] = React.useState('off')

  const handlers = React.useMemo(
    () => ({
      on: () => {
        setState('on')
      },
      off: () => {
        setState('off')
      },
      toggle: () => {
        setState(s => (s === 'on' ? 'off' : 'on'))
      },
    }),
    [],
  )

  return [state, handlers]
}

function useInput() {
  const [state, setState] = React.useState('')

  const handlers = React.useMemo(
    () => ({
      handleInputChange: e => {
        setState(e.target.value)
      },
      resetInput: () => {
        setState('')
      },
    }),
    [],
  )

  return [state, handlers]
}

function Component() {
  const [toggleState, { on, off, toggle }] = useOnOff()
  const [inputState, { handleInputChange, resetInput }] = useInput()

  return (
    <div>
      <div>State: {toggleState}</div>
      <div>
        <button type="button" onClick={on}>
          Turn On
        </button>
        <button type="button" onClick={off}>
          Turn Off
        </button>
        <button type="button" onClick={toggle}>
          Toggle
        </button>
      </div>
      <div>
        <label htmlFor="randomWord">Random Word</label>
        <input
          type="text"
          id="randomWord"
          onChange={handleInputChange}
          value={inputState}
        />
        <button type="button" onClick={resetInput}>
          Reset Input
        </button>
      </div>
    </div>
  )
}

Take notice, our Component now only consumes custom hooks. These custom hooks give us a little more context to what they mean, and we don't have the implementation details of our state handler functions sitting in the middle of our component function.

Another benefit of this pattern is that dependencies quickly become obvious because they end up being arguments to our custom hooks. What if our useInput hook should begin with an initial state other than an empty string and we use that for resetting the input as well?

function useInput(initialState = '') {
  const [state, setState] = React.useState(initialState)

  const handlers = React.useMemo(
    () => ({
      handleInputChange: e => {
        setState(e.target.value)
      },
      resetInput: () => {
        setState(initialState)
      },
    }),
    [initialState],
  )

  return [state, handlers]
}

function Component({ startingWord }) {
  //...
  const [inputState, { handleInputChange, resetInput }] = useInput(startingWord)
  //...
}

There are even more benefits. By adding this layer of abstraction between our component and the standard React hooks, we can change the implementation of our custom hook's API without changing the component. Perhaps I want to use a reducer instead of useState for our useOnOff hook: <Marker content="I know this example is ridiculous. If I ever think of a better one, I'll update the post." />

function onOffReducer(state, action) {
  switch (action) {
    case 'ON':
      return 'on'
    case 'OFF':
      return 'off'
    case 'TOGGLE':
      return state === 'on' ? 'off' : 'on'
    default:
      return state
  }
}

function useOnOff() {
  const [state, dispatch] = React.useReducer(onOffReducer, 'off')

  const handlers = React.useMemo(
    () => ({
      on: () => {
        dispatch('ON')
      },
      off: () => {
        dispatch('OFF')
      },
      toggle: () => {
        dispatch('TOGGLE')
      },
    }),
    [],
  )

  return [state, handlers]
}

Obviously, this type of change might be completely unnecessary for my example, but I hope you can recognize where this layer of abstraction might be useful to you when you have to change the implementation details of a hook. We were able to replace the entire state management of our hook without changing the API, which means our component behaves the same way, even though the implementation of that behavior has changed quite a bit.

How to Enforce this Pattern

What good is a pattern if you can't come up with a way to get others to use it? To steer them down the good path? We can do that for this pattern with an ESLint plugin and rule. Thus, I give you the eslint-plugin-use-encapsulation and the prefer-custom-hooks rule! You can find it here: https://github.com/kyleshevlin/eslint-plugin-use-encapsulation.

Following the installation instructions, you'll see that prefer-custom-hooks will warn you whenever you use a React hook directly inside a component. The only way around the warning (other than disabling the rule), is to use the React hooks from within a custom hook.

Summary

By opting to write all the hooks consumed by your components as custom ones, you will be providing future devs (including yourself) useful context by encapsulating all the pieces of a concern into a single function. By doing this, you gain all the benefits of proper encapsulation and make your components more declarative. You might even gain a few useful reusable hooks in the process.

useEncapsulation Talk at CascadiaJS

I recently gave a talk on this topic at the CascadiaJS conference and wanted to share that recording with you. Enjoy!

Encapsulation

Tue, 29 Dec 2020 00:00:00 GMT

This post will be short and sweet, yet it is my sincere hope that after reading this blog post, you will think about functions a little differently than you did before.

Functions are one of the first abstractions a programmer learns. Second only to variables. We learn functions as a means of repeating a set of instructions, and later how to parameterize that set of instructions with function arguments. Perhaps you were even taught something like this:

function sayHello(name) {
  return 'Hello, ' + name
}

sayHello('Kyle') // Hello, Kyle
sayHello('friend') // Hello, friend

Now, you have a function you can reuse. Reusability was and is touted as the great benefit of functions. The primacy of this benefit is touted everywhere with lesson upon lesson on DRY code. <Marker content={DRY stands for "don't repeat yourself".} /> However, I will contend that reusability is not the primary purpose of a function. No, reusability is rather a wonderful property of functions that comes as the result of their true primary purpose: encapsulation.

What is “encapsulation”?

"Encapsulation" is the act of taking all the elements of a concern and containing them within a structure. The most common structure of encapsulation is a function, as I will discuss here, but you can also think of modules, objects and classes (and more) as structures for encapsulation (if used well).

But what do I mean by all the elements of a concern? Let's come up with an example of some code suffering from a lack of encapsulation.

function createBudgetSummary(transactions) {
  const { length } = transactions
  let income = 0
  let spent = 0

  transactions.forEach(transaction => {
    const { inflow, outflow } = transaction
    if (inflow) {
      income += inflow.amount
    }
    if (outflow) {
      spent += outflow.amount
    }
  })

  const format = new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
    minimumFractionDigits: 2,
  }).format

  let difference = income - spent

  income = format(income)
  spent = format(spent)
  difference = format(difference)

  const inflection = length === 1 ? 'transaction' : 'transactions'

  let summary = `After ${length} ${inflection}, your total is ${difference}\n`
  summary += `Your income totaled ${income}.\n`
  summary += `Your spending totaled ${spent}.\n`

  return summary
}

Quite a bit going on in there. It's mostly legible. A programmer can follow what's happening in the function, but there are related bits strewn about, a lot of mutated variables, and it's very imperative. What if that function read like this instead?

function createBudgetSummary(
  transactions,
  summaryFormatter = defaultSummaryFormatter,
) {
  const income = getIncome(transactions)
  const spent = getSpent(transactions)
  const summary = summaryFormatter({
    quantity: transactions.length,
    income,
    spent,
  })

  return summary
}

Is it easier or harder to understand this function than the previous one? Easier, right? Each line declares what's happening explicitly. Get the income. Get the expenses. Format the summary. You don't have to decipher what a bunch of lines of code, possibly scattered around the body of the function, intend to do. You just read it top to bottom, from the function name to function name.

But I can hear you say, "But Kyle! All you did was hide a bunch of details in functions!"

You're partly right. I did move the details elsewhere, but I didn't hide them. I encapsulated them in functions focused on that particular concern. You want to see? Here are the other functions:

const formatForUSD = value => {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
    minimumFractionDigits: 2,
  }).format(value)
}

const inflect =
  (singular, plural = singular + 's') =>
  quantity =>
    quantity === 1 ? singular : plural

const getIncome = transactions => {
  return transactions.reduce(
    (acc, { inflow }) => (inflow ? acc + inflow.amount : acc),
    0,
  )
}

const getSpent = transactions => {
  return transactions.reduce(
    (acc, { outflow }) => (outflow ? acc + outflow.amount : acc),
    0,
  )
}

const defaultSummaryFormatter = ({ quantity, income, spent }) => {
  const inflection = inflect('transaction')(quantity)
  const difference = income - spent

  // I'm spltting this on 3 lines for blog legibility
  // You could do this as a multiline template string, no problem
  let summary = `After ${length} ${inflection}, your total is ${difference}\n`
  summary += `Your income totaled ${formatForUSD(income)}.\n`
  summary += `Your spending totaled ${formatForUSD(spent)}.\n`

  return summary
}

"What's so great about this?!" you exclaim. "It's more lines of code!"

True, but every function is simpler, focused, and tells you what concern it encapsulates. By writing our code this way, we gain a number of benefits:

Easier to digest

By focusing on encapsulation, we make our functions focused, small and containing all the elements they need to do their job. In our original code, we destructured length really early on in the function body, even though it wasn't used for 15 lines or so. As a human, this adds an unnecessary strain to remember where these bits of info are. It's simpler to create functions that keep these elements tightly located to where they are needed. By doing so, our code becomes more legible and more declarative. I like to think of it as the function names tell a story.

Mental offloading of information

This one you might disagree with, but I find if I have good functions, I don't always have to understand their details to know what's important to me at that given moment.

If I'm looking at createBudgetSummary and I'm trying to change the format of the summary, I don't need to know how the program gets the income, I just know there's a function that does getIncome. I can offload that information, or never take it on to begin with. Those details aren't important to me until I either need to change income or have found a bug in its implementation (which I can easily write a test for). I can make changes to getIncome, without changing the API of summaryFormatter.

Easier to refactor

Let's say you just hate Array.prototype.reduce. <Marker content="There's a whole cult of <code>reduce</code> haters on Twitter. I don't blame them, but I do like to poke and prod them a bit. 😁" /> Nothing stops you from writing:

const getIncome = transactions => {
  let total = 0

  transactions.forEach(({ inflow }) => {
    if (inflow) total += inflow.amount
  })

  return total
}

It becomes trivial to change implementation details without having an impact on other parts of the code.

We can recognize opportunities for flexibility more easily

Take a look at defaultSummaryFormatter. This isn't part of the original code. But once you realize what the purpose of those final lines of code are, you can see an opportunity to make our createBudgetSummary function more flexible and powerful. By using dependency injection with a default parameter, it's trivial to change what format we output, so long as the summaryFormatter makes use of the same data.

We gained reusable functions

We didn't set out to make reusable functions, but we got a few anyways. inflect is a highly reusable function because it encapsulates a single idea: return the right word. The way I wrote it, you can create any number of inflector functions wherever you need one.

There are even more opportunities to create further encapsulated functions. We could break our formatForUSD function and break it down into an abstraction to make more formatters, like so:

const makeCurrencyFormatter = (locale, currency) => {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
    minimumFractionDigits: 2,
  }).format
}

const formatForUSD = makeCurrencyFormatter('en-US', 'USD')

Now, you can easily make other currency formatters for other locales and currencies.

Summary

Encapsulation is the act of gathering all the elements of a single concern and containing them within a structure. In this post, we focused on functions. By encapsulating concerns and giving them good names, we made our code more declarative, easier to read, and easier to refactor. Furthermore, by properly encapsulating concerns, we found opportunities to make the code more flexible and gained even more reusability.

Use Old School State

Thu, 17 Dec 2020 00:00:00 GMT

import FirstCounter from './_FirstCounter' import SecondCounter from './_SecondCounter' import FirstDoubleStepper from './_FirstDoubleStepper' import SecondDoubleStepper from './_SecondDoubleStepper' import ThirdDoubleStepper from './_ThirdDoubleStepper'

Disclaimer: I have no idea if this is a good idea. Just something you can do if you want.

If you're like me, you've been writing React for quite some time. While I don't spend much time writing class components these days, <Marker content="I still work with plenty of class components regularly." /> you might recall that you can pass a second argument to this.setState, a callback function that is called after the state update.

This callback function was a simple way to sequence some functionality. Set some state, do something once it has happened. What if we could recreate some of that simple magic with hooks? <Marker content="It's not magic. Sadly, with code as with life, it never is." />

Generally, with hooks we would have this as two parts. An instance of React.useState to manage the state changes, and an instance of React.useEffect to respond when the state changes. It might even be better and simpler to write your code this way (hence my opening disclaimer).

const [state, setState] = React.useState(/* initialState */)

React.useEffect(() => {
  // do something with `state` here
}, [state])

We can create a custom hook that encapuslates these two parts. I'll warn you ahead of time. We're going to make a first attempt, run into a problem and fix it later. Let's do this step by step. First our hook function as a wrapper for useState:

function useOldSchoolState(initialState) {
  return React.useState(initialState)
}

Cool. What's our next requirement? That setState allow an optional second argument. We can do this by creating a wrappedSetState and returning that.

function useOldSchoolState(initialState) {
  const [state, setState] = React.useState(initialState)

  const wrappedSetState = React.useCallback((update, callback) => {
    setState(update)

    if (callback) {
      callback()
    }
  }, [])

  return [state, wrappedSetState]
}

This looks pretty good, but there's a problem. The callback is supposed to run after the state update has taken effect. Which is a perfect word for how we're going to solve this issue, with an useEffect hook.

React.useEffect always runs after render, and components re-render after a state update. So, if we move the callback to a useEffect hook, it will ensure that it runs after our state has updated. We need to come up with a way to store the callback function and call it in the useEffect hook.

function useOldSchoolState(initialState) {
  const [state, setState] = React.useState(initialState)
  const callbackRef = React.useRef(null)

  const wrappedSetState = React.useCallback((update, callback) => {
    setState(update)

    if (callback) {
      callbackRef.current = callback
    }
  }, [])

  React.useEffect(() => {
    if (callbackRef.current) {
      callbackRef.current()
      callbackRef.current = null
    }
  })

  return [state, wrappedSetState]
}

Sweet. Now we can run a callback after the state update. Let's make an arbitrary example. A Counter that logs out a message.

function Counter() {
  const [state, setState] = useOldSchoolState(0)

  const inc = () => {
    setState(
      s => s + 1,
      () => {
        console.log(`Count went up to ${state}`)
      },
    )
  }

  const dec = () => {
    setState(
      s => s - 1,
      () => {
        console.log(`Count went down to ${state}`)
      },
    )
  }

  return (
    <div>
      <div>Count: {state}</div>
      <div>
        <Button onClick={inc}>+</Button>
        <Button onClick={dec}>-</Button>
      </div>
    </div>
  )
}

However, one might notice there's a small problem, one that would be avoided in the class component version. Can you spot it? <Marker content="Hint: check the console." />

In class components, this refers to the instance of the component, so if we were to try and get values derived from this, such as this.state and this occurs in a function called after the state was updated, then we would get the updated values for this.state. But if we try and access state in our callback, it will be incorrect. It will be the whatever state was at the time setState was called due to the closure created. In other words, we cannot access the updated state by using state in the callback function. What if the action we'd like to depends on that updated state?

Remember how useEffect runs after the state update triggered a render. This means that the value of state inside our useOldSchoolState hook is when the effect is run is the nextState in comparison to the value of state at the time the callback was created and state closed over. Thus, if we pass state in our useOldSchoolState to the callback, we'll have access to the nextState in the callback. Like so:

function useOldSchoolState(initialState) {
  const [state, setState] = React.useState(initialState)
  const callbackRef = React.useRef(null)

  const wrappedSetState = React.useCallback((update, callback) => {
    setState(update)

    if (callback) {
      callbackRef.current = callback
    }
  }, [])

  React.useEffect(() => {
    if (callbackRef.current) {
      callbackRef.current(state)
      callbackRef.current = null
    }
  }, [state])

  return [state, wrappedSetState]
}

Now that we are passing the updated state to the callback, let's update our Counter component to make use of this.

function Counter() {
  const [state, setState] = useOldSchoolState(0)

  const inc = () => {
    setState(
      s => s + 1,
      nextState => {
        console.log(`Count went up to ${nextState}`)
      },
    )
  }

  const dec = () => {
    setState(
      s => s - 1,
      nextState => {
        console.log(`Count went down to ${nextState}`)
      },
    )
  }

  return (
    <div>
      <div>Count: {state}</div>
      <div>
        <Button onClick={inc}>+</Button>
        <Button onClick={dec}>-</Button>
      </div>
    </div>
  )
}

Excellent. Now our Counter will log out the correct value in the callback. However, there is yet one more problem with this approach. What happens if we call setState inside of our callback, and furthermore, what happens if we provide this second setState a callback as well?

Let's make a new component and try it out. We'll make a contrived DoubleStepper, but it'll make my point:

function DoubleStepper() {
  const [state, setState] = useOldSchoolState(0)

  cons step = () => {
    setState(
      s => s + 1,
      ns1 => {
        console.log('first callback', ns1)
        setState(
          s => s + 1,
          ns2 => {
            console.log('second callback', ns2)
          }
        )
      }
    )
  }

  return (
    <div>
      <div>Steps: {state}</div>
      <Button onClick={step}>Step</Button>
    </div>
  )
}

Let's break that down really quick. When we trigger step, the first setState shall update the state by 1 and callback with the next state. Inside of that callback, we'll call setState again, which will also update the state by 1 and has a callback that should display the second state update.

But does it?

Try it out and find out. Make sure you check the console.

Well, what do you know? It doesn't work right, does it? What's going on? Adding a few console.logs to our useOldSchoolState code will make this clear:

function useOldSchoolState(initialState) {
  const [state, setState] = React.useState(initialState)
  const callbackRef = React.useRef(null)

  const wrappedSetState = React.useCallback((update, callback) => {
    console.log('starting wrappedSetState')
    setState(update)

    if (callback) {
      console.log('setting callbackRef')
      callbackRef.current = callback
    }
  }, [])

  React.useEffect(() => {
    console.log('starting effect')
    if (callbackRef.current) {
      callbackRef.current(state)
      console.log('nullifying callbackRef')
      callbackRef.current = null
    }
  }, [state])

  return [state, wrappedSetState]
}

Now try it.

When we click the button of our DoubleStepper component, we see the following logs:

// starting wrappedSetState
// setting callbackRef
// starting effect
// first callback 1
// starting wrappedSetState
// setting callbackRef
// nullifying callbackRef
// starting effect

Notice that nullifying callbackRef only occurs once, when we might expect it to occur twice. What's worse is that our ref is nullified after having set the ref for the next callback, but before that callback has a chance to be called in the next effect. What we need is a way to sequence callbacks in an orderly fashion. What can we do to manage that?

We can add a simple queue data structure, and only process one callback at a time in the queue.

function createQueue() {
  const queue = []

  return {
    add(item) {
      queue.unshift(item)
    },
    remove() {
      return queue.pop()
    },
    get length() {
      return queue.length
    },
  }
}

This is a very simple queue with no bells and whistles. Let's use it to store callbacks, and then remove callbacks one by one instead, like so:

function useOldSchoolState(initialState) {
  const [state, setState] = React.useState(initialState)
  const queue = React.useRef(createQueue())

  const wrappedSetState = React.useCallback((update, callback) => {
    setState(update)

    if (callback) {
      queue.current.add(callback)
    }
  }, [])

  React.useEffect(() => {
    if (queue.current.length) {
      queue.current.remove()(state)
    }
  }, [queue.current.length, state])

  return [state, wrappedSetState]
}

Now, we manage to only run one callback per effect, which in the case of the DoubleStepper gets it working as expected. I haven't tested this on even more challenging scenarios, so I can't make guarantees regarding how bulletproof this implementation is, but I am satisfied with the exploration for now.

Admittedly, that was quite a bit of work for a seemingly simple hook, but I think the work was worthwhile. It forced me (and hopefully you) to think about breaking the problem down, and fixing pieces of it step by step.

Helpful Debugging Hooks

Fri, 04 Dec 2020 00:00:00 GMT

import ChangeExample from './_ChangeExample'

Update 08/19/2021: I created and published a package of these hooks so you can import them and use them without having to write them yourselves. Install them with:

npm install use-debugger-hooks

You can see the repo here: https://github.com/kyleshevlin/use-debugger-hooks. Hope this helps you with your debugging!

Recently, I needed to do some debugging to improve a few components that were rerendering unexpectedly. In that process of research and trial & error, I came away with a few useful hooks that I want to share with you.

In short, every time props or state changes in a React component, it will rerender. This is, unequivocally, a good thing. When a component is rendering more often than expected and it's an actual performance problem for your app, then you need to determine what props, state or other values are changing between renders. In order to do this, you first need a way of retaining the previous value of something.

This can be accomplished with use of useRef and useEffect in a custom usePrevious hook.

function usePrevious(value) {
  const ref = React.useRef()

  React.useEffect(() => {
    ref.current = value
  }, [value])

  return ref.current
}

This hook isn't new at all. In fact, you can find it in the official React docs as well as other places. This hook works because useEffect is always run after render. So during the current render phase we get the previously stored value, then the useEffect runs to update the value. Pretty cool.

Now that we can store a previous value, we want to determine if the current value and previous value are different, and if they are different, let's log that information out. To do so, let's create another custom hook: what I call useLogChanges:

function useLogChanges(value) {
  const previousValue = usePrevious(value)
  const changes = getChanges(previousValue, value)

  if (changes.length) {
    changes.forEach(change => {
      console.log(change)
    })
  }
}

function getChanges(previousValue, currentValue) {
  // Handle non-null objects
  if (
    typeof previousValue === 'object' &&
    previousValue !== null &&
    typeof currentValue === 'object' &&
    currentValue !== null
  ) {
    return Object.entries(currentValue).reduce((acc, cur) => {
      const [key, value] = cur
      const oldValue = previousValue[key]

      if (value !== oldValue) {
        acc.push({
          name: key,
          previousValue: oldValue,
          currentValue: value,
        })
      }

      return acc
    }, [])
  }

  // Handle primitive values
  if (previousValue !== currentValue) {
    return [{ previousValue, currentValue }]
  }

  return []
}

Great. I pulled out the getChanges function since we really don't need the implementation details cluttering the useLogChanges hook. That reads simply enough now. You can pass this hook any value and log out changes with each render. We could do something like this to debug a component's props for example:

function MyComponent(props) {
  useLogChanges(props)

  return <OtherComponent {...props} />
}

Now, every time MyComponent rerenders, we will be informed what props changed that caused the rerender.

Here's a very rudimentary example. This component just generates a random number and passes it to a child component every time you press the button. The child component uses useLogChanges on its props. The changes to the props will be logged out with each render. Open the console, and give it a try.

But what about side effects? Can I also use useLogChanges to debug when effects run? Absolutely.

Let's make use of useLogChanges inside a useEffectDebugger hook.

function useEffectDebugger(effect, dependencies) {
  useLogChanges(dependencies)
  React.useEffect(effect, dependencies)
}

Now you have a drop in replacement for useEffect that will tell you which dependency changed to cause an effect to run. If you really wanted, you could make drop in replacements for any of the standard React library hooks with this pattern.

function useCallbackDebugger(callback, dependencies) {
  useLogChanges(dependencies)
  return React.useCallback(callback, dependencies)
}

function useMemoDebugger(memoizer, dependencies) {
  useLogChanges(dependencies)
  return React.useMemo(memoizer, dependencies)
}

// ...etc

That's all there is to it. Nothing fancy. Just a little hooks composition for you. I hope you find this helpful in your React component debugging!

Headlight Vision

Tue, 10 Nov 2020 00:00:00 GMT

I've been struggling a lot lately with my inner self-talk. It's never been all that fantastic but even worse than usual lately. I think this is the result of the difficult year we're all facing and a new venture I'm undertaking that has me really doubting myself.

"Great opener, Kyle! Really got us in good spirits!" you say.

I know, but bear with me. Part of why I get like this is I am wired to look at people more successful than me and compare myself to them. I could write endlessly about people I admire and could never be like. Whenever I get like this, stuck in my comparisons, I try and think about a metaphor that my friend Jason Lengstorf shared with me a year or two ago that I think is just brilliant.

When you're struggling with confidence and doubt, and perhaps feeling further behind than your peers, consider this scenario:

Imagine you're in a car, driving down a dark road in the middle of the night. Naturally, you have your headlights on.

When you're driving at night and you have your headlights on, what exactly can you see?

Turns out, not a whole lot.

You can only see what is more or less directly in front of you. You can see a few other cars that are further on their journey than you are. Why are they further ahead?

Maybe they had a head start, maybe they have a fancier car, maybe they're a better driver, who knows? But notice, really notice, that what you see in this tiny sliver of light shooting out from the front of your car, is but a small fragment of what's actually out there in the dark.

If it wasn't dark, and we didn't need our headlights, and we looked around in all directions, what would we see?

We would see that there are many people driving outside of our headlight vision, in all sorts of directions.

There are some way to the left. There are some way to the right.

And multitudes and multitudes more people behind us.

There are even people who aren't on the road yet that soon will be.

If you're always driving in the dark with your headlights on, you'll only notice the people directly ahead of you.

Sure, you can strive after them. Put your foot on the gas pedal and go, but there's almost certainly always someone else still out in front. It's exhausting to try and keep up and there's a good chance you'll run out of gas. You will probably feel, as I often do, like shit because you aren't where they are.

If and when this happens, remember that you need some daylight and a broader perspective. Remember there are people all around you, and what you do may not make an impression on those ahead of you, it will be tough to see in a rear-view mirror, but can make a huge difference to the people left, right, and behind you.

Keep them in mind. Don't get locked into your headlights. And drive safe.

Pattern Matching in JavaScript

Sun, 18 Oct 2020 00:00:00 GMT

Today, I want to share with you a coding pattern I frequently use when writing conditional JavaScript. I've made several tweets about it throughout the years and it's high time that I finally write a blog post that I can use as a reference. In fact, I use this pattern so often that my manager at work started to call it the "Kyle pattern". It shouldn't be called that, but I'll take it as a compliment.

I call what I'm about to show you "a poor person's pattern matching" or "makeshift pattern matching". It's not quite the real thing, but it does a pretty good job of coming close to it and is plenty useful.

Before you go further, you should understand switch statements pretty well. If you're not familiar with how they work in JavaScript, I recommend reading the MDN docs on switch. With that, let's get to it.

What is "pattern matching"?

I first encountered "pattern matching" when I started to learn ReasonML a few years ago. In ReasonML, a strongly typed functional language, you have variants. A variant is a union type, but unlike TypeScript, we can have conditional logic based on the type of value passed in, not just the value itself. This is a really powerful mechanism for handling conditional functionality in our programs.

With ReasonML's switch, when we pass in a value, we look at the value's type and choose different logical paths accordingly. On their home page, they share this example:

type schoolPerson = Teacher | Director | Student(string);

let greeting = person =>
  switch (person) {
  | Teacher => "Hey Professor!"
  | Director => "Hello Director."
  | Student("Richard") => "Still here Ricky?"
  | Student(anyOtherName) => "Hey, " ++ anyOtherName ++ "."
  }

<Note>

The syntax highlighter I am using, Shiki, doesn't currently support ReasonML. If you know where I can find a Textmate grammar for ReasonML, let me know and I'll make a pull request to the project. As a stopgap measure, here's the equivalent code written in OCaml, which is what the ReasonML syntax is based on.

type school_person = Teacher | Director | Student of string

let greeting person =
  match person with
  | Teacher -> "Hey Professor!"
  | Director -> "Hello Director."
  | Student "Richard" -> "Still here Ricky?"
  | Student any_other_name -> "Hey, " ^ any_other_name ^ "."

</Note>

This mechanism quickly becomes the most robust way of doing conditional logic as you use the language. As you work with it, you get comfortable thinking in variants instead of thinking in if/elses or ternaries. But ReasonML's switch and JavaScript's switch are a bit different, so how can we recreate some of this magic in JavaScript?

Flipping `switch` on its head

When using a switch statement in JavaScript, we most commonly use the expression (the part in parentheses, which makes this parenthetical kind of meta) as if it's the left half of a strictly equals check (===), and each case as the right half. An example of this I expect a lot of you to be familiar with would be a state reducer a la Redux and/or React.

const reducer = (state, action) => {
  switch (action.type) {
    case 'DATA_REQUESTED':
      return { ...state, status: 'loading' }

    case 'DATA_RECEIVED':
      return { ...state, data: action.payload.data, status: 'loaded' }

    case 'DATA_FAILED':
      return { ...state, error: action.payload.error, status: 'error' }

    default:
      return state
  }
}

As we make calls to reducer, our switch tries to match the action.type to the case with the same string. However, this limits how useful our switch can be because we can only operate on a single value in the expression. Is there a way around this limitation?

There sure is.

Rhetorical question incoming. What are we doing with the switch expression and the cases exactly? We're strictly comparing (===) two values and seeing if they come out true or false.

Instead, what if we use switch (true) and make each of our cases an expression? This opens up some possibilities.

With each case as an expression, we can do things we couldn't before, such as:

Do multiple comparisons on the same value
Use predicate functions to match cases <Marker content="A predicate is a function that returns a boolean." />
Use multiple values in those predicate functions
Use RegExp.prototype.test to match patterns
and whatever else you can dream up

The key to using switch (true) in this way is to think of each case expression as a pattern. Sure, we can't match on variants in the wonderful way that ReasonML can, but we can use the tools we have to get the matches we want. Let's look at some examples.

In this first example, I've created an areWeThereYet function. It generates responses to that annoying question based on the milesToGo.

function areWeThereYet(milesToGo) {
  switch (true) {
    case milesToGo <= 1:
      return "We're hereeeee!"

    case milesToGo <= 10:
      return 'Almost. Just a little further.'

    case milesToGo <= 100:
      return 'A little more than an hour.'

    case milesToGo <= 250:
      return 'Just a half day away.'

    default:
      return "We're not even close so stop asking!"
  }
}

Personally, I find this easier to read than the same code with if/else if/elses. You might disagree, that's ok. Stick with me.

The next thing that makes switch (true) similar to pattern matching is the ability to now use functions in each case to generate matches. Let's consider the ReasonML example above, and adapt it a bit to JavaScript.

// I need you to use your imagination here, and pretend
// that all of these predicate functions exist and work correctly :)
const greeting = person => {
  switch (true) {
    case isTeacher(person):
      return 'Hey Professor!'

    case isDirector(person):
      return 'Hello Director.'

    case isRicky(person):
      return 'Still here Ricky?'

    case isStudent(person):
      return `Hey, ${person.name}.`
  }
}

There are other benefits to using a switch this way, such as case fall-throughs. Rather than writing it as an OR expression (||), you could write two cases that use fall-throughs to respond the same way. I'll "sanitize" a little snippet of an idea from work to show this.

// Again, use your imagination and envision a larger switch
switch (true) {
  // ...other cases

  case isEcommerceItems(items):
  case isCMSItems(items):
    return prepareForCollectionList(items)
}

There are a few other patterns to try with this, but I feel like I've given you a pretty good idea of how to get started. I'm trusting you to try it out and practice the pattern.

If you want an idea to get started with, you might try to solve the "Gilded Rose" kata with switch (true) and regexes. <Marker content="Just Google 'Gilded Rose'. You'll get a bazillion hits." /> I was once given this kata as an interview question and I found my pattern matching trick to be a useful way to solve the problem.

Additional Notes

There is a TC39 proposal to add pattern matching to JavaScript, but it's been stalled at Stage 1 for quite some time. You can find the proposal repo here.

There is an interesting package called safety-match created by my Webflow coworker @suchipi. Check it out if you're interested in pattern matching with TypeScript.

Another popular TypeScript package for pattern matching is ts-pattern. It's highlighted feature is that it can be exhuastive, ensuring every possible type case is covered.

Update: Years after writing this post, I decided to try and make a simple, type-safe pattern matching library of my own. I called it kase. It's not remarkably more useful than simply using switch (true), but it was an interesting exercise that involved some TypeScript shenanigans with the "builder pattern". You can find it here: https://github.com/kyleshevlin/kase

Generator Functions

Sat, 12 Sep 2020 00:00:00 GMT

import Collatz from './_Collatz' import SimplePayment from './_SimplePayment'

Have you ever heard of the Baader-Meinhof phenomenon? It's a cognitive illusion where once you become aware of some thing, you see that thing every where. It's called an illusion because the thing was always there, you were just unaware of its presence.

I feel like generator functions are a bit of a Baader-Meinhof phenomenon for me. I never had a use for them, but once I figured out a single use for them, now I see reasons to use them everywhere. <Marker content="Maybe not the strongest segue, but bear with me." />

I recently used them while doing some maze generation experiments during some time off. Check out the tweets in this thread if that interests you. They were perfect for the problem I had at hand, and I want to take some time to explain what they are and why they might be useful to you.

What's a Generator Function?

A generator function is a special function, denoted by the use of the * in its declaration.

function* myFirstGenerator() {
  // do stuff here
}

This function is different. Calling this function will not return the value of your function's body. Not right away, at least. More on this shortly. Instead, it returns a Generator object. This object has several methods on it, but the one we're most concerned with is the next method. Calling next() on our generator object is how we return the next generated result from our generator function.

This result is an object with two properties: value and done. Let's discuss how we get these values first.

The most common way we will "return" values from a generator functions is with the yield keyword. Let's give it a try in a very rudimentary way.

function* myFirstGenerator() {
  yield 42
}

const generatorObject = myFirstGenerator()

console.log(generatorObject.next()) // { value: 42, done: false }
console.log(generatorObject.next()) // { value: undefined, done: true }

I want to draw your attention to a few things. First, as I pointed out, we call our generator function to get our generatorObject. Calling next returns an object with the yielded value and a done property. But why is done false on the first yield? There's nothing else returned in our function body, right?

Wrong.

Just like all normal JavaScript functions, there is an implicit return undefined if there isn't an explicit return statement in the function body. This implicit return undefined is what we get on the second call of the next method. Hence why value is undefined and done is now true.

From this, we can deduce that using return instead of yield is how to stop a generator.

Let's combine the use of return with multiple yields. Yes, that's right. You can yield as many times as you would like in a generator function.

function* countTo(number) {
  let i = 0

  while (i < number - 1) {
    i++
    yield i
  }

  return number
}

const countTo3 = countTo(3)

console.log(countTo3.next()) // { value: 1, done: false }
console.log(countTo3.next()) // { value: 2, done: false }
console.log(countTo3.next()) // { value: 3, done: true }
// Let's call it an extra time to see what happens
console.log(countTo3.next()) // { value: undefined, done: true }

As you can see, our function "counts" as we expect and is done when we expect, too.

Something Mildly More Interesting

Let's try this on something mildly more interesting. Are you familiar with the Collatz conjecture. It's an algorithm in mathematics that returns a sequence of numbers. The algorithm is as follows:

Given any positive integer, if the number is even, divide it by 2, otherwise, multiply it by 3 and add 1. Repeat until you arrive at 1.

Writing this algorithm as a generator function is pretty straightforward and we can generate each step in the sequence.

const isOdd = num => Boolean(num % 2)
const collatz = num => (isOdd(num) ? 3 * num + 1 : num / 2)

function* collatzSequence(num) {
  let current = num

  while (current !== 1) {
    yield current
    current = collatz(current)
  }

  return current
}

const sequence = collatzSequence(17)

I want to draw your attention to something I find interesting about how we're able to write this algorithm with a generator. Because the function essentially pauses execution on the yield statement, we're able to yield the current number before mutating the current variable with the next collatz result. I've made a simple React component that will allow you to try out different numbers and generate the Collatz sequence.

Isn't that interesting? We're able to get each step in the sequence very easily, and the code is pretty simple to write as well.

Something Practical

Alright, let's make one more generator function, but use it to solve a practical problem. In fact, I'm going to use it to solve the very problem that inspired me to write this blog post: loan repayment.

If you follow me on Twitter, you probably know of my trevails with student loans. We've been paying them off aggressively for years, and still have a few more years to go, but how many to be exact? And how much will an extra $100 here or there help me? All questions that can be answered with a small program. So let's build a simplified version of it.

A loan has a principal (starting amount), an interestRate, a compounding period (how often it compounds), and a payment.

Let's start with the simplest part, a few helper functions:

// Basic compounding formula
const compound = (amount, rate) => amount + amount * rate

// Keeps floats to a max of 2 places past the decimal
const to2 = num => Number(num.toFixed(2))

Now, let's set about writing a makePayment generator function. I'll bake some details specific to student loans in the function, and make comments when I'm doing so.

function* makePayment(principal, rate, payment) {
  // Student loans compound daily, so we create a daily interest rate
  // by dividing our annual rate with the number of days in a year
  const dailyInterestRate = rate / 365
  let remaining = principal
  let totalInterestPaid = 0
  let paymentsCount = 0

  while (remaining > 0) {
    let beginWith = remaining
    let endWith = remaining

    // For simplification, we're going to treat each payment period
    // as 30 days long
    for (let i = 0; i < 30; i++) {
      endWith = compound(endWith, dailyInterestRate)
    }

    // Student loans pay the accrued interest first, then the principal
    // We're keeping this formula rudimentary, but this let's us see what
    // interest accrued since the last payment
    const interestAccrual = to2(endWith - beginWith)
    totalInterestPaid = to2(totalInterestPaid + interestAccrual)

    endWith = to2(endWith - payment)
    remaining = to2(endWith)
    paymentsCount++

    if (endWith <= 0) {
      endWith = 0
      remaining = 0

      return {
        beginWith,
        endWith,
        interestAccrual,
        paymentsCount,
        totalInterestPaid,
      }
    }

    yield {
      beginWith,
      endWith,
      interestAccrual,
      paymentsCount,
      totalInterestPaid,
    }
  }
}

As of the time of this writing, looks like I have about ~33 payments to go. It's pretty cool to see how much changing the payment can change how long it will take to pay the rest of the loan.

If I wanted to spend more time on this in this particular post, you could make some very cool data visualizations with generator functions sequencing each update to the visualization. Perhaps I'll explore this in a future post.

Summary

Generator functions are a special function that allow you to pause execution, yielding multiple (if not infinite) values from them. You might have to stretch your imagination to find a good use for them, but they're a handy tool to have in your tool chest.

If you'd like to read more about them, I suggest looking at the MDN docs on them.

Caveat

Generator functions will not work in any version of IE. Womp womp.

Multiple Boolean Props are a Code Smell

Fri, 28 Aug 2020 00:00:00 GMT

import CommonButton from './_CommonButton' import BetterButton from './_BetterButton'

You learn a lot working on a large, complicated codebase for an extended period of time. It's the kind of environment that exposes you to particular patterns often enough to develop thoughts and opinions around them. I want to share a quick opinion I have regarding a particular pattern here: multiple boolean props or state in a component is probably a code smell.

Imagine a CommonButton component for an application. This CommonButton has a default way of rendering:

<CommonButton>Click Me!</CommonButton>

<OffsetWrap> <CommonButton client:load>Click Me!</CommonButton> </OffsetWrap>

Now, imagine our app needs to change the background of the Button depending on the information that button needs to convey. Let's have a few different variations: a primary, warning, and danger styles. We could do this by passing our CommonButton a prop of that name.

<CommonButton primary>Click Me!</CommonButton>
<CommonButton warning>Click Me!</CommonButton>
<CommonButton danger>Click Me!</CommonButton>

What should this code look like? Maybe something like this:

function CommonButton({
  children,
  onClick = () => {},
  primary,
  warning,
  danger,
  type = 'button',
}) {
  let backgroundColor = '#33a1cc'
  if (primary) backgroundColor = '#17b890'
  if (warning) backgroundColor = '#ffd166'
  if (danger) backgroundColor = '#f0544f'

  return (
    <button onClick={onClick} type={type} style={{ backgroundColor }}>
      {children}
    </button>
  )
}

And then when we render our buttons from before, we would get:

<OffsetWrap> <div className="flex gap-2"> <CommonButton client:load primary> Click Me! </CommonButton> <CommonButton client:load warning> Click Me! </CommonButton> <CommonButton client:load danger> Click Me! </CommonButton> </div> </OffsetWrap>

That looks great, but there are some serious problems with this approach that make it rather smelly. The problem that bothers my coding olfactory senses the most is the existence of impossible states.

What should happen if the consumer does the following?

<CommonButton danger primary warning>
  Click Me!
</CommonButton>

Should it render as green, yellow, or red? Let's find out.

<OffsetWrap> <CommonButton client:load danger primary warning> Click Me! </CommonButton> </OffsetWrap>

If you put more than one of these boolean props in place, what happens? You see a leaking of the implementation details! Whatever way the component creator has decided to reconcile these impossible states is exposed. In this case, I wrote it so that danger was the last state checked that updates the background color. Therefore, the danger prop takes priority over all the other props, regardless of the order they are passed in.

Now, admittedly, this is not how we intend our component to be used. "The consumer should use the component correctly!" you might yell. True. They probably should, but we shouldn't write code that depends on others to just not make mistakes. Especially when we can programmatically defend against the problem in a simple way.

We could possibly stop the abuse of our CommonButton through an error/warning or even an ESLint rule, but there's a much easier thing that we can do. Get rid of the multiple boolean props.

Whenever we have multiple boolean props, especially ones related to the same concern, these should really be expressed as a single prop with an enumerated set of strings as the possible values. Let's make a BetterButton that follows this pattern.

const BUTTON_BGS = {
  default: '#33a1cc',
  primary: '#17b890',
  warning: '#ffd166',
  danger: '#f0544f',
}

function BetterButton({
  children,
  onClick = () => {},
  type = 'button',
  variant = 'default',
}) {
  const backgroundColor = BUTTON_BGS[variant] || BUTTON_BGS.default

  return (
    <button onClick={onClick} style={{ backgroundColor }} type={type}>
      {children}
    </button>
  )
}

This button not only moves our props into a single concern, but allows us to:

Move our styles into an enum
Handle incorrect variants gracefully
Make impossible states impossible
Makes later extension as simple as adding a variant

Now, our buttons look like this:

<BetterButton variant="primary">Click Me!</BetterButton>
<BetterButton variant="warning">Click Me!</BetterButton>
<BetterButton variant="danger">Click Me!</BetterButton>

<OffsetWrap> <div className="flex gap-2"> <BetterButton client:load variant="primary"> Click Me! </BetterButton> <BetterButton client:load variant="warning"> Click Me! </BetterButton> <BetterButton client:load variant="danger"> Click Me! </BetterButton> </div> </OffsetWrap>

Even better, when you try and give it some garbage as a variant, it doesn't leak our implementation details, it just uses the default styling.

<BetterButton variant="primary warning danger">Click Me!</BetterButton>
<BetterButton variant="garbage">Click Me!</BetterButton>

<OffsetWrap> <div className="flex gap-2"> <BetterButton client:load variant="primary warning danger"> Click Me! </BetterButton> <BetterButton client:load variant="garbage"> Click Me! </BetterButton> </div> </OffsetWrap>

This also applies to situations where you have multiple booleans around different concerns coming in. It's likely that what you really have are a number of finite "states" your component can be in, and it would be better to derive that state and pass it in as a prop, rather than muddy your code with conditional checks for your many booleans.

Again, this is just my opinion. I don't have any way of definitively proving that this approach is better, but I've found it to be useful for me in my career. Hope you also find this information useful.

Mental Model of Use Effect

Wed, 26 Aug 2020 00:00:00 GMT

One thing I have found challenging about React.useEffect is the mental model regarding the dependencies array.

It's very easy to get it in your head to use the dependency array as a means to constrain the calling of the effect, essentially treating it as a guard or conditional.

"If this value changes, do that effect."

The problem is that you'll often run into issues where you only want to run an effect when a single value changes, and thus you'll be tempted to leave out the other dependencies from the dependency array. Next thing you know, you'll be facing an ESLint warning about it. <Marker content="Assuming you're using ESLint with the React Hooks plugin." /> Like with the following code:

React.useEffect(() => {
  // Pretend these values are in the parent scope
  const diff = prevQuantity - quantity
  someHandlerFunction(diff)
}, [quantity])

This, more or less, works like we want it to. When quantity changes, we call the effect and call the handling function. However, this will also warn you that you haven't added all the dependencies. You might think, "I don't want this effect to run when the handler function changes! That'll break the code!"

Trust me, I get stuck in this loop a lot, too.

Here's what you need to understand. Simply put, not calling the effect whenever a dependency changes means you'll have stale values and functions. It will lead to bugs.

Instead, you must make the mental shift to:

Call this effect whenever the dependencies change, but add a conditional in the effect function that only triggers the changes you need, when you need them to happen.

The more correct code looks like this:

React.useEffect(() => {
  if (prevQuantity !== quantity) {
    const diff = prevQuantity - quantity
    someHandlerFunction(diff)
  }
}, [prevQuantity, quantity, someHandlerFunction])

Now we can call the effect whenever a dependency changes, while still not calling our handler function when we don't intend to.

Fixing this small mental model issue <Marker content="An issue for me. Maybe not for you." /> helps you avoid the ESLint warnings and write better code. Hope this helps you.

Update - August 27, 2020

I had an additional thought regarding this topic and wanted to add it to the post. Another way to think about the useEffect hook is to write the code as if the hook and the dependency array wasn't there first, and then wrap it in the hook and add the dependencies later.

If I think about this outside of the hook, my mental model for the functionality is, "If there's a difference between these two values, send the difference to this handling function." When we write that code, it looks like the body of our effect, but it makes sense in isolation.

if (prevQuantity !== quantity) {
  const diff = prevQuantity - quantity
  someHandlerFunction(diff)
}

Now that we've written the functionality we desire, the next step is to put React in charge of tracking all of these values for us.

// highlight-next-line
React.useEffect(() => {
  if (prevQuantity !== quantity) {
    const diff = prevQuantity - quantity
    someHandlerFunction(diff)
  }
  // highlight-next-line
}, [prevQuantity, quantity, someHandlerFunction])

Hope this little update also helps you in your mental understanding of the useEffect hook.

Tic-Tac-Toe in React

Sun, 02 Aug 2020 00:00:00 GMT

import BlankGrid from './_BlankGrid' import FirstGame from './_FirstGame' import SecondGame from './_SecondGame' import ThirdGame from './_ThirdGame' import FourthGame from './_FourthGame'

If video content is more your thing than reading a technical article, you can watch my collection of egghead lessons teaching the material found in this blog post. No matter which you prefer, I hope you enjoy the content.

A few weeks ago, I took some time off from work. I was feeling a little burnt out and needed to rest and have some fun. Sometimes that means not coding at all. Other times, it means coding some silly stuff of no real importance. Turns out, coding is still fun after all! I decided to do the latter on my staycation and code up a bunch of silly games. I'm going to share the simplest one with you here: tic-tac-toe.

Before we get started, I want to say that even though I don't build games for a living (or even really as a hobby), coding up a game from time to time is a great way to learn some new skills and patterns. It's also excellent exercise for your brain and trains you to think algorithmically. In fact, I once was asked to code tic-tac-toe in a job interview, so don't scoff at this post. It might help you land a job some day.

Tic-tac-toe is a very simple game, and because it's so simple, it makes for a good introduction to some of the principles of grid and turn-based games.

Let's start with a top-level Game component that will store the state of our tic-tac-toe game. For now, it's just an empty function that returns null, but it won't be this way for long.

function Game() {
  return null
}

Tic-tac-toe consists of a 3x3 grid on which the players put Xs and Os. We need a way to generate this grid and display the state of the data with a Grid component. We could do this a number of ways, but I'm going to create a 2-dimensional array of values. We will keep it very simple. Those values can only be null, X, or O.

For the sake of those new to 2-dimensional grids, I'm going to break this down piece by piece, or rather index by index. When we create games with a 2-dimensional array, the outermost array is the grid. The grid consists of rows which are also arrays. This is why it's called a 2-dimensional array. You might also come across the term "matrix" for this data structure.

A row consists of values. Each value in the row is a column in our grid. I typically think of each column value as a cell and refer to it as such in my game's program.

When we start a game of tic-tac-toe, our board consists of 3 rows and 3 columns, where every cell is the value of null. So our grid looks like this:

const grid = [
  [null, null, null],
  [null, null, null],
  [null, null, null],
]

For a game like tic-tac-toe, it is simple enough to manually create a starting grid like this. But, as you build more games, you will find that making a function to generate a grid for you will be quite helpful. My generateGrid function looks like this: <Marker content="You can make all sorts of varieties of this function. Do what suits your needs best" />

function generateGrid(rows, columns, mapper) {
  return Array(rows)
    .fill()
    .map(() => Array(columns).fill().map(mapper))
}

We can make a function specific for a tic-tac-toe game by baking in a few values:

const newTicTacToeGrid = () => generateGrid(3, 3, () => null)

Let's add a newTicTacToeGrid to our Game component so that we'll be able to pass it down eventually into other components.

function Game() {
  // This will eventually be a stateful grid
  const grid = newTicTacToeGrid()

  return null
}

Now that we can easily generate our tic-tac-toe grid, we need to render it. Coincidentally enough, using CSS Grid to display our grid works very well. Here's one of the ways I might approach this with React:

function Grid({ grid }) {
  return (
    // Wrapping the grid with a div of inline-block means that the grid
    // takes up only the space defined by the size of the cells, while
    // still allowing us to use fractional values for the grid-template-*
    // properties
    <div style={{ display: 'inline-block' }}>
      <div
        style={{
          // We set a background color to be revealed as the lines
          // of the board with the `grid-gap` property
          backgroundColor: '#000',
          display: 'grid',
          // Our rows are equal to the length of our grid
          gridTemplateRows: `repeat(${grid.length}, 1fr)`,
          // Our columns are equal to the length of a row
          gridTemplateColumns: `repeat(${grid[0].length}, 1fr)`,
          gridGap: 2,
        }}
      >
        {grid.map((row, rowIdx) =>
          row.map((cell, colIdx) => (
            // We put the colIdx first because that is our X-axis value
            // and the rowIdx second because that is our Y-axis value
            // Getting in the habit makes using 2d grids much easier
            <Cell key={`${colIdx}-${rowIdx}`} cell={cell} />
          )),
        )}
      </div>
    </div>
  )
}

const cellStyle = {
  backgroundColor: '#fff',
  height: 75,
  width: 75,
}

function Cell({ cell }) {
  return <div style={cellStyle}>{cell}</div>
}

The comments in the code block above explain most of my decisions, but just to recap quickly, we use CSS Grid to layout our rows and columns. We can do that by setting the grid-template-rows property equal to the length of our grid array, and making grid-template-columns equal to the length of the first row in our grid.

Since this is tic-tac-toe, we style it by giving the grid a background color and using the grid-gap property to "reveal" the grid lines by making each of our cells an offsetting background color. This is a clever and simple way to avoid having to write various borders for each cell.

Let's also be sure to pass grid from our Game component down into our Grid component.

function Game() {
  const game = newTicTacToeGrid()
  return <Grid grid={grid} />
}

Now when we render Game, it should look like something like this:

Now that we have our grid, we should make our Cells interactive. I'm going to add a button to each cell to make it clickable and accessible. I'm also going to pass a handleClick event handler function into the component to be used with the button's onClick property.

handleClick will be passed down as a prop from our top level Game component through the Grid to get to the Cell. We could also accomplish this with hooks or context, but I don't mind prop-drilling when our UI hierarchy is this small.

function Game() {
  const grid = newTicTacToeGrid()
  const handleClick = () => {}

  return (
    <div style={{ display: 'inline-block' }}>
      <Grid grid={grid} handleClick={handleClick} />
    </div>
  )
}

function Cell({ cell, handleClick }) {
  return (
    <div style={cellStyle}>
      <button type="button" onClick={handleClick}>
        {cell}
      </button>
    </div>
  )
}

Now, what should handleClick do? handleClick should take the coordinates of the cell clicked, and dispatch this action whatever is handling our state to determine the next state. This sounds like a good use case for useReducer. <Marker content="I will refactor this to use a state machine in the future. Don't worry." /> Let's update handleClick to accept x and y arguments and pass them on to some state management. This will add quite a bit of code, but I'll explain it in a bit.

// Simple way to deeply clone an array or object
const clone = x => JSON.parse(JSON.stringify(x))

// An enum for the next turn in our game
const NEXT_TURN = {
  O: 'X',
  X: 'O',
}

const initialState = {
  grid: newTicTacToeGrid(),
  turn: 'X',
}

const reducer = (state, action) => {
  switch (action.type) {
    case 'CLICK': {
      const { x, y } = action.payload
      // Since we need immutable updates, I often find the simplest thing to do
      // is to clone the current state, and then use mutations on the clone to
      // make updates for the next state
      const nextState = clone(state)
      const { grid, turn } = nextState

      // If the cell already has a value, clicking on it should do nothing
      // Also, pay attention, because our rows are first, the `y` value is the
      // first index, the `x` value second. This takes some getting used to.
      if (grid[y][x]) {
        return state
      }

      // If we're here in our program, we can assign this cell to the current
      // `turn` value
      grid[y][x] = turn

      // Now that we've used this turn, we need to set the next turn. It might
      // be overkill, but I've used an object enum to do this.
      nextState.turn = NEXT_TURN[turn]

      // We'll add checks for winning or drawing soon

      return nextState
    }

    default:
      return state
  }
}

function Game() {
  const [state, dispatch] = React.useReducer(reducer, initialState)
  const { grid } = state

  const handleClick = (x, y) => {
    dispatch({ type: 'CLICK', payload: { x, y } })
  }

  return <Grid grid={grid} />
}

Let's break this code down. We start with clone which is a helper function I will use to deeply clone the state so I can make mutations on the clone and return that. Remember, we need to make immutable updates with a reducer, so that it renders the new state.

Next, I create a simple enum to be able to easily get the next turn. You could probably do this with a simple ternary, but there are other places this information will be useful in the future.

After that, we create our initialState and a reducer. Our initialState has our grid and the current turn, and our reducer handles only one action at the time being, CLICK.

On a CLICK action, we use the x and y values of the payload to determine the next state. If the grid cell at those coordinates has a value, we return the current state so we don't trigger an update. Otherwise, we can set the value of that cell to the current turn, update the nextState.turn property and return the nextState. Putting this all together, we should have a Game that works like this:

Awesome. Our game is working... kind of. We can fill up the squares, but we don't have any means of resetting the game if we want to (or a draw occurs), and we don't have a way of determining if someone has won the game. Heck, we don't even know who's turn it is! Let's add these features next.

Let's start with the simplest of those tasks, whose turn it is:

function Game() {
  const [state, dispatch] = React.useReducer(reducer, initialState)
  // highlight-next-line
  const { grid, turn } = state

  const handleClick = (x, y) => {
    dispatch({ type: 'CLICK', payload: { x, y } })
  }

  return (
    <div style={{ textAlign: 'center' }}>
      {/* highlight-next-line */}
      <div>Next up: {turn}</div>
      <Grid Cell={ButtonCell} grid={grid} handleClick={handleClick} />
    </div>
  )
}

And let's add a reset button, too:

// Changing this into a function ensures that we get a new state object
// and run any of the functions inside of it. This is useful in other games
// where the starting grid may have randomized bits of state
// highlight-range{1-4}
const getInitialState = () => ({
  grid: newTicTacToeGrid(),
  turn: 'X'
})

const reducer (state, action) => {
  switch (action.type) {
    // highlight-range{1-2}
    case 'RESET':
      return getInitialState()

    //... remains the same
  }
}

function Game() {
  const [state, dispatch] = React.useReducer(reducer, getInitialState())
  const { grid, turn } = state

  const handleClick = (x, y) => {
    dispatch({ type: 'CLICK', payload: { x, y } })
  }

  const reset = () => {
    dispatch({ type: 'RESET' })
  }

  return (
    <div style={{ textAlign: 'center' }}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <div>Next up: {turn}</div>
        {/* highlight-next-line */}
        <button onClick={reset} type="button">Reset</button>
      </div>
      <Grid Cell={ButtonCell} grid={grid} handleClick={handleClick} />
    </div>
  )
}

Now, our tic-tac-toe game looks like this:

This is great. You, the reader and user can play, but it'd be really nice if the game told you if you won or not. Checking for win conditions is probably the most important part of creating a game like this (and is likely what the interviewer is looking for if you're asked to make a game like this).

We need to create an efficient algorithm that checks for the game at each step for a win. What are the win conditions of tic-tac-toe?

The game is won when 3 cells in a line contain the same value
A line is defined as a row, column, or diagonal

Let's break this down. At any given time, we need to check if three values are equal. There also happens to be only 8 lines in our game: 3 rows, 3 columns, and 2 diagonals. With these two observations, we can create a simple algorithm to determine if the game has been won at any point.

We'll start by making a helper function to evaluate our three values. We know if a square is null, we can return false immediately. Then we just need to know if all three values are the same. Since we're using the strings X and O, this is very simple to do: <Marker content="If you're a fan of fancy terms, I am using the <em>transitive property</em> to deduce that <code>a</code> is equal to <code>c</code>." />

const checkThree = (a, b, c) => {
  // If any of the values are null, return false
  if (!a || !b || !c) return false
  return a === b && b === c
}

Now, we need to create our 8 lines, get the values at those indices, and run checkThree on each line. I'm going to add a helper function that will flatten our 2-dimensional array into a 1-dimensional array. This will make this our checks a little bit easier to do. Flattening an array like this might be too inefficient in certain situations, so be careful and pay attention to the performance of your program, but in general, this a good trick to know. <Marker content="As of ES2019, JavaScript added <code>Array.prototype.flat()</code> to the language. If you're environment can handle this standard, you can easily use it instead." />

// Depending on your JavaScript environment, you can potentially
// use Array.prototype.flat to do this
const flatten = array => array.reduce((acc, cur) => [...acc, ...cur], [])

function checkForWin(flatGrid) {
  // Because our grid is flat, we can use array destructuring to
  // define variables for each square, I will use the points on a
  // compass as my variable names
  const [nw, n, ne, w, c, e, sw, s, se] = flatGrid

  // Then we simply run `checkThree` on each row, column and diagonal
  // If it's true for any of them, the game has been won!
  return (
    checkThree(nw, n, ne) ||
    checkThree(w, c, e) ||
    checkThree(sw, s, se) ||
    checkThree(nw, w, sw) ||
    checkThree(n, c, s) ||
    checkThree(ne, e, se) ||
    checkThree(nw, c, se) ||
    checkThree(ne, c, sw)
  )
}

We want to add our checkForWin function inside the CLICK case of our reducer. This will enable us to transition the game state into a winning state as soon as a win is detected. However, we have not setup any state that tracks whether the game has been won or not yet. We'll also want to add a status property to our state that we can update when a win is found.

const getInitialState = () => ({
  grid: newTicTacToeGrid(),
  // highlight-next-line
  status: 'inProgress',
  turn: 'X',
})

const reducer (state, action) => {
  switch (action.type) {
    //... still the same

    case 'CLICK': {
      const { x, y } = action.payload
      const nextState = clone(state)
      const { grid, turn } = nextState

      if (grid[y][x]) {
        return state
      }

      grid[y][x] = turn

      // highlight-next-line
      const flatGrid = flatten(grid)

      // highlight-range{1-4}
      if (checkForWin(flatGrid)) {
        nextState.status = 'success'
        return nextState
      }

      nextState.turn = NEXT_TURN[turn]

      return nextState
    }

    //... still the same
  }
}

Now that we have a status, we can use it in our Game component to display when we have a winner. I prefer to use enums over booleans for tracking states, and generally this results in making enumerated objects to respond to those states. In order to render some text when the game is won, I'll create a GAME_STATUS_TEXT enum. This enum is a method for each game status we have. This method can can receive the current turn as an argument, and render whatever is necessary. Almost always, this will return null, but when someone wins, we can tell them.

// highlight-range{1-4}
const GAME_STATUS_TEXT = {
  inProgress: () => null,
  success: turn => `${turn} won!`,
}

function Game() {
  const [state, dispatch] = React.useReducer(reducer, getInitialState())
  // highlight-next-line
  const { grid, status, turn } = state

  const handleClick = (x, y) => {
    dispatch({ type: 'CLICK', payload: { x, y } })
  }

  const reset = () => {
    dispatch({ type: 'RESET' })
  }

  return (
    <div style={{ textAlign: 'center' }}>
      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
        <div>Next up: {turn}</div>
        {/* highlight-next-line */}
        <div>{GAME_STATUS_TEXT[status](turn)}</div>
        <button onClick={reset} type="button">
          Reset
        </button>
      </div>
      <Grid Cell={ButtonCell} grid={grid} handleClick={handleClick} />
    </div>
  )
}

Before we check out this iteration of the game, I want to add something to our reducer to prevent a user from clicking anything but the reset button after a game has been won. By preventing this, I prevent some awkward state where after the first player has won the game, the second player can't "steal" by clicking a square that gives them three in a row. I also want to show this to demonstrate that a reducer does not have to be just a switch statement.

const reducer = (state, action) => {
  if (state.status === 'success' && action.type !== 'RESET') {
    return state
  }

  //... still the same
}

Now the only action a user can take when the game has been won is to reset the game. This seems fair to me. Check it out:

There is just one more thing I want to add to this game. I would like the game to reset immediately when the board is filled with a draw. Doing this just seems like a nice touch to add.

We could do the work of trying to figure out when a game cannot be won and indicate that the game is drawn to the users, but I will leave that to you to try and figure out and implement. For now, let's add a checkForDraw function to our game to bring this to completion.

Adding checkForDraw is simpler than it might seem. First, we need to know that the game has not been won. The game can't be a draw if it's been won. We can reuse checkForWin for that. <Marker content="It would be slightly more efficient to use the result of <code>checkForWin</code> so that we're not running the function twice in every loop. I leave that to you to implement." />

Once we know that the game has not been won, we need to determine if the grid has been completely filled in. Given that our values are null, X, or O, we can determine this by filtering our flatGrid with the Boolean constructor. If the filtered grid has a length that is less than the length of the flatGrid, then we know we have null squares and the game is not drawn yet.

function checkForDraw(flatGrid) {
  return (
    !checkForWin(flatGrid) &&
    flatGrid.filter(Boolean).length === flatGrid.length
  )
}

We add this into our CLICK case in our reducer, like so:

const reducer (state, action) => {
  switch (action.type) {
    //... still the same

    case 'CLICK': {
      const { x, y } = action.payload
      const nextState = clone(state)
      const { grid, turn } = nextState

      if (grid[y][x]) {
        return state
      }

      grid[y][x] = turn

      const flatGrid = flatten(grid)

      if (checkForWin(flatGrid)) {
        nextState.status = 'success'
        return nextState
      }

      // highlight-range{1-3}
      if (checkForDraw(flatGrid)) {
        return getInitialState()
      }

      nextState.turn = NEXT_TURN[turn]

      return nextState
    }

    //... still the same
  }
}

Conclusion

There you have it! A working game of tic-tac-toe in React in about 130ish lines of code. I'm pretty generous with the whitespace usage.

Now, what was the point of all this? It certainly wasn't to try and make something you can do in a matter of seconds on a piece of paper with a pencil. It was to get our brains to think about solving problems, and more importantly, figuring out what those fundamental problems are. This is programming. Breaking requirements and ideas down until they can be turned into code.

Learning to code tic-tac-toe can be a gateway to all sorts of other learning. You can now practice building other games, or learn other algorithms. You can even take what you know here and apply it to other languages. Learning to code the same app in different ways is also good practice for your brain.

I encourage you to try and take this a step further some how. Make it better. Make it faster. I would love to see what you come up with.

Using `React.memo` to Avoid Unnecessary Rerenders

Tue, 16 Jun 2020 00:00:00 GMT

import { Profile, MemoizedProfile, Parent, ObjectParent, RefParent, OtherObjectParent, } from './_Profile'

In my last post, I talked about the concept of memoization and how the technique is used to avoid calculating a previously calculated result of a function. I also made mention of the two memoization functions in React. This post is going to focus on React.memo and how to use it to avoid unnecessary rerenders of React components.

When Hooks were introduced to React in late 2018, we were also given some new top-level functions in the React API. One of those new functions is React.memo. It is the function component equivalent of using PureComponent for a class component.

If your component is a pure function, i.e. given the same inputs you get the same output, you can wrap the component in React.memo to prevent the component from rerendering if props haven't changed. <Marker content="It will still rerender if state or context changes." /> Let's create a simple Profile component that we can memoize to demonstrate.

function Profile({ name, location }) {
  return (
    <div>
      <div>{name}</div>
      <div>{location}</div>
    </div>
  )
}

const MemoizedProfile = React.memo(Profile)

If I add a few styles, give each component the same props, and render both of these components side by side, they will look perfectly identical.

Great. That's what we expect. There's nothing fancy about the initial render of a component with props. We give it a set of values, we expect the output to be the correct result.

Where React.memo becomes useful is when we introduce a parent component. In React, if a component updates, then it rerenders everything in that component. This is necessary. The new state of the component may affect anything rendered below it. This rerendering happens regardless of whether the child component has experienced a change or not. That's where React.memo comes into play.

A memoized component will skip rendering if its props have not changed. We can easily demonstrate this, and I get to share one of my simple little hacks for detecting unnecessary rerenders in the process.

We're going to change Profile slightly. We're going to give it a random background color every time it renders. <Marker content="Think of this as the equivalent of using outline: 1px solid red when debugging CSS." /> This is simple to write and do. Just make sure to remove it when you're ready to ship your code.

const random255 = () => Math.floor(Math.random() * 255)
const randomRGBA = () => {
  const r = random255()
  const g = random255()
  const b = random255()

  return `rgba(${r}, ${g}, ${b}, 0.3)`
}

function Profile({ name, location }) {
  return (
    <div style={{ backgroundColor: randomRGBA() }}>
      <div>{name}</div>
      <div>{location}</div>
    </div>
  )
}

const MemoizedProfile = React.memo(Profile)

Now, every time the component renders, a new background color will be applied. Let's create a Parent component that has a frivolous state change that should cause the Profile components to rerender.

function Parent({ children }) {
  const [, setState] = React.useState(false)
  const forceUpdate = () => setState(x => !x)

  return (
    <>
      <button onClick={forceUpdate}>Force Update</button>
      <div
        style={{
          display: 'grid',
          gridGap: bs(1),
          gridTemplateColumns: '1fr 1fr',
          marginTop: bs(0.5),
        }}
      >
        <Profile name="Kyle Shevlin" location="Portland, OR" />
        <MemoizedProfile name="Kyle Shevlin" location="Portland, OR" />
      </div>
    </>
  )
}

Notice that when you click "Force Update", only the regular Profile component updates. The memoized version does not. In the right scenarios, this can become a real performance boost.

What Does "Same Props" Mean?

We're going to make a small change to our Profile component again to demonstrate an important concept.

// Pay attention to how we've changed props
function Profile({ person }) {
  const { name, location } = person

  return (
    <div style={{ backgroundColor: randomRGBA() }}>
      <div>{name}</div>
      <div>{location}</div>
    </div>
  )
}

We've moved name and location into a person object. You can imagine this scenario happening often in any React app. You have an array of objects and you pass the whole object as a prop to a child component. How does this change how our memoized component works? Let's update our Parent component to now pass these objects into the component instead.

function Parent({ children }) {
  const [, setState] = React.useState(false)
  const forceUpdate = () => setState(x => !x)

  return (
    <>
      <button onClick={forceUpdate}>Force Update</button>
      <div
        style={{
          display: 'grid',
          gridGap: bs(1),
          gridTemplateColumns: '1fr 1fr',
          marginTop: bs(0.5),
        }}
      >
        <Profile
          person={{
            name: 'Kyle Shevlin',
            location: 'Portland, OR',
          }}
        />
        <MemoizedProfile
          person={{
            name: 'Kyle Shevlin',
            location: 'Portland, OR',
          }}
        />
      </div>
    </>
  )
}

Now let's give this set of components a try. Click the "Force Update" button below and pay attention to what updates.

Both components update! Why does this happen?

Even though the props are the same values with every update, the object passed into each component on every render is a new object. Objects are strictly compared by reference, not by their shape of keys and values. The simplest way to demonstrate this is to put this into your browser console and see the result

{} === {}

This is the same check that React.memo and PureComponent make and is called a "shallow comparison" of objects. Because we're creating new objects with each render to pass into our Profile components, this comparison always results in React needing to update. Hence why they both rerender every time that the Parent component updates.

To drive this point home, let's store these objects as refs inside of the component. A ref in React is an object that will not lose its reference across renders. By storing an object as a ref, we guarantee that we get the same object (referentially) with each render.

function Parent({ children }) {
  const [, setState] = React.useState(false)
  const forceUpdate = () => setState(x => !x)
  const personRef = React.useRef({
    name: 'Kyle Shevlin',
    location: 'Portland, OR',
  })

  return (
    <>
      <button onClick={forceUpdate}>Force Update</button>
      <div
        style={{
          display: 'grid',
          gridGap: bs(1),
          gridTemplateColumns: '1fr 1fr',
          marginTop: bs(0.5),
        }}
      >
        <Profile person={personRef.current} />
        <MemoizedProfile person={personRef.current} />
      </div>
    </>
  )
}

Now our memoized component is back to working as we expect. Because the object's reference is the same with each render, it skips rerendering. It's important to understand this fact, as it might have an impact on how you design your components.

`React.memo`'s Second Argument

Using a ref like we just did is not how I would recommend handling this situation. It was simply to demonstrate a point. This section is also primarily to demonstrate a point. Use what I'm about to show you sparingly. Following general best practices will keep you from needing this feature often.

Suppose we must pass an object into a component, and we know that often these objects will be "deeply equal" even if they aren't the same reference. We can use the second argument to React.memo to supply an areEqual function that determines if a component should rerender or not. This function is similar to implementing shouldComponentUpdate on a class component, in that we compare the previousProps to the nextProps, but opposite in what we want to return from the function. We want the areEqual function to return true when the component should not update. Let's update how we memoize Profile accordingly:

const personsAreEqual = (prevProps, nextProps) => {
  return (
    prevProps.person.name === nextProps.person.name &&
    prevProps.person.location === nextProps.person.location
  )
}

const MemoizedProfile = React.memo(Profile, personsAreEqual)

Now, if we use that in our example, we'll see that even without refs, our components behave as we expect.

Summary

We can improve the performance of our React apps by avoiding unnecessary rerenders with React.memo. We have to understand what it means to pass the "same props" to our components, though, in order to achieve this performance boost.

Memoization: What, Why, and How

Thu, 11 Jun 2020 00:00:00 GMT

import Adder from './_Adder' import Factorializer from './_Factorializer'

Recently, I spent an hour with one of my protégés <Marker content={"Mentee" is not a word. <a href="https://twitter.com/kyleshevlin/status/1253460305885016065?s=20">I've stated this before</a>.} /> demonstrating some common advanced techniques we use at Webflow. One of the techniques I showed them was memoization. <Marker content="Not a typo." /> Let's learn what memoization is, why you might use it, and how do we write it from scratch.

Memoization is a technique that enhances a function by creating and using a cache to store and retrieve results of that function. Memoization uses the arguments of a function to create a key for the cache. The first time a memoized function is called with a set of arguments, those arguments are turned into a key and the result of the function is stored as the value for that key in the cache. Then, on subsequent calls of the function with the same arguments, we can retrieve that previously calculated value from the cache and return it before we ever do the work of calculating the result. This improves the performance of our function, since hitting the cache is a constant time operation (O(1) in big O notation).

We can use memoization on any pure function and it's not too difficult to implement either. Let's create a higher order function that will allow us to create a memoized version of a pure function.

Typically, we want to use memoization on functions with expensive calculations and we'll talk about why later, but for the sake of writing our memoize function, I'm going to use a very simple pure function.

function add(x, y) {
  return x + y
}

Can't get much simpler than an add function! Since it's a pure function, we can guarantee that the same inputs always lead to the same output. So if we're able to create a cache that will use the function arguments as a key and store the results of the function as a value, we can retrieve that value from the cache knowing it's the same as the result of running the function.

function memoize(fn) {
  // We create a cache inside the closure of the `memoize` function
  // This creates a new cache for each function we pass
  // to `memoize`. We'll discuss other cache strategies later
  const cache = {}

  // The goal is to return a function with an identical
  // signature as the one passed in
  return (...args) => {
    // We need to create a key for our cache. A simple way to do this is
    // to join the args with a delimiter that clearly separates arguments
    // This way the arguments (12, 3) don't create the same key as (1, 23)
    const key = args.map(JSON.stringify).join('---')

    if (cache[key] !== undefined) {
      // Just for our example, let's make it clear we returned a value
      // from the cache
      console.log('from cache')
      return cache[key]
    }

    const result = fn(...args)
    cache[key] = result

    return result
  }
}

Let's break that down. memoize receives a function as an argument. It then creates a cache in closure. This will store the results of our function in memory to be retrieved later.

Next, we return a function that can receive whatever args the original function receives. Inside of the function we are returning, we create a key for our cache. In this case, I chose to stringify and join the arguments with a delimiter. This delimiter prevents similar arguments from accidentally being the same key. Without a delimiter, calling add(2, 34) and add(23, 4) would result in the key 234. We would end up with a mistaken cache hit for the second call, and even worse, our result would be incorrect.

Next, if there is a defined value at the cache[key], we return it and skip calculating the result. Otherwise, we calculate the result, store it in the cache, and then return it.

Now, let's create a memoized add function and use it.

const memoizedAdd = memoize(add)

Seriously. Adding memoization to a pure function is that simple. <Marker content="There are exceptions. Functions that receive arrays and objects as arguments may want to employ a different caching strategy. I'll discuss this further later in the post" />

Let's try it out. I've made a component below that allows you to give it two numbers to add together and it will tell you every time the result comes from the cache instead of being calculated. Try swapping the X and Y values and see that it doesn't hit the cache because the keys generated are different.

Why Use Memoization?

Memoization is a tradeoff exchanging space (memory) for time. The purpose of this tradeoff is to gain a performance benefit by skipping the calculation of the function's result, i.e. save time. Thus, it only makes sense to use memoization where memory is not a concern and the original calculation is both expensive and often called with the same arguments. Our add function was a bad example. It's not an expensive calculation at all. Let's create a slightly better example.

I've used this example before in my writing, but a factorial function might be a good candidate for memoization. It's recursive, which means that factorial will be called with the same argument frequently. In fact, if it's ever been called with a number greater than the current argument, it will simply return the value from the cache, since it's already been calculated before. Let's write the factorial function.

const factorial = memoize(n => {
  if (n === 0) {
    return 1
  }

  return n * factorial(n - 1)
})

Below, I've added a component that demonstrates how this works. With this component, every result of factorial is cached and I display the cache as it grows. Notice the cache doesn't change when you call a number less than a previous argument because no new values were added to the cache and the value was immediately retrieved and returned.

Memoization and React

I recognized a few years ago <Marker content={And even mentioned it in a talk <a href="https://www.youtube.com/watch?t=2910&v=0QdUsOSt60s">here</a>.} /> that React function components could be memoized. Of course, I wasn't forward thinking enough to recognize that this was a feature coming to React in the future. That said, memoizing in React is quite a bit different than memoizing a function like we have thus far. Rather than creating a large cache of many results, we can think of the caches in React's memoization as a cache of a single result.

React now ships with two memoization mechanisms. The first, React.memo, is for memoizing function components as I just described. If the props don't change, the component won't rerender. This is the function equivalent of using the PureComponent class or implementing a shallow props check of this.props === prevProps in the shouldComponentUpdate lifecycle. I'd like to discuss React.memo further in a future post, so I'll save that conversation for there.

React.useMemo, the hook, is the other memoizing function. We give React.useMemo a "create" function <Marker content={Their words, <a href="https://reactjs.org/docs/hooks-reference.html#usememo">in the docs</a>.} /> that it will call and cache the returned value. However, we don't give this function any arguments. Instead, we use values within the scope of the component, various props and state to derive our value. Then, our useMemo hook only recalculates the value if any of these dependencies change.

Both of these memoization mechanisms are quite different than the technique I presented earlier. Think of them the differences this way. Our memoize function is designed to have a cache that continues to grow as more results are generated. We haven't limited our cache in anyway (though we could). React, on the other hand, has given you a cache, but it's precisely the size of one result. When the values that achieved that result are changed, then the function is run again and the cache of one is set with a new value. This is perfect for preventing extraneous rerenders and it's good to understand these differences.

Memoization and Other Caches

In my memoize function, I used a plain old JavaScript object to create key/value pairs. This required that I turn the arguments into a string to act as a key. There might be occasions where this is impractical or unnecessary. It might be useful to make your cache using a Map or a WeakMap instead.

A Map can essentially use any value as a key, including a function. A WeakMap can only use objects as keys, but allows for garbage collection of those objects. Both can be useful in the right situation.

We use a memoizing function at Webflow that makes use of a WeakMap cache. The gist of it <Marker content="Since I don't want to give away too many secrets" /> is that because we make updates to objects immutably, we can guarantee that two objects that are referentially equal are also deeply equal. We use these objects as keys in a WeakMap cache, and use their reference to retrieve the value. This requires understanding mutations and immutability, but greatly improves performance in some of the areas of our app. I encourage you to do some further research on your own to understand different caching strategies for memoization.

Conclusion

Memoization is a trade off of space for time. It's used to cache the result of a function so that the next time it's called with the same arguments, we can just return the answer. We don't need to calculate it again. This technique is useful when we have an expensive calculation that will be called frequently with the same arguments. It's used more often than you might realize and is a useful tool to have in your tool belt.

The Three Kinds of React State

Fri, 29 May 2020 00:00:00 GMT

import LocalCounter from './_LocalCounter' import ParentalCounter from './_ParentalCounter' import { CounterProvider, RemoteCounter, Single, TwoInOne, } from './_RemoteCounter'

No matter what it is you're building with React, when you boil it down, there are only three ways you can manage data <Marker content={More often called "state", but I don't want to conflate React "state" with "states" in state machines which I write about often. They aren't exactly the same thing.} /> in a React app: locally, parentally, and remotely.

Locally

The local management of data happens within the component itself. This is most commonly done with useState, useReducer, or if using a class component, this.state. The data and its updaters are encapsulated within the scope of the component. It's simple and overplayed, but a Counter component can be a useful example here.

function Counter({ initialValue = 0 }) {
  const [count, setCount] = React.useState(initialValue)

  const increment = () => setCount(c => c + 1)
  const decrement = () => setCount(c => c - 1)
  const reset = () => setCount(initialValue)

  return (
    <div>
      <div>Count: {count}</div>
      <div>
        <button type="button" onClick={increment}>
          +1
        </button>
        <button type="button" onClick={decrement}>
          -1
        </button>
        <button type="button" onClick={reset}>
          reset
        </button>
      </div>
    </div>
  )
}

Parentally

The parental management of data happens when the data and its updaters are passed in as props from somewhere higher in the component tree. In the case of our counter, it is as simple as moving the data and updating functions to a parent controlling component, and passing them in as props to a controlled child component.

function CounterController({ initialValue = 0 }) {
  const [count, setCount] = React.useState(initialValue)

  const increment = () => setCount(c => c + 1)
  const decrement = () => setCount(c => c - 1)
  const reset = () => setCount(initialValue)

  return (
    <Counter
      count={count}
      increment={increment}
      decrement={decrement}
      reset={reset}
    />
  )
}

function Counter({ count, increment, decrement, reset }) {
  return (
    <div>
      <div>Count: {count}</div>
      <div>
        <button type="button" onClick={increment}>
          +1
        </button>
        <button type="button" onClick={decrement}>
          -1
        </button>
        <button type="button" onClick={reset}>
          reset
        </button>
      </div>
    </div>
  )
}

This component behaves exactly the same as the other one, but there might be a good reason to store the data in a parent component. Perhaps it needs to be accessed by other children, or it's easier to test the child component by being able to pass props into it rather than assert on its internal behavior. The reason for the separation of the data and its management from its presentation isn't terribly important at this moment. Understanding the concepts of this pattern is what matters.

Remotely

The remote management of data happens when we store and update data outside of the ancestry of a component tree. This is a very broad area of data management with many solutions. Common ones are Redux or the React Context API. The important part of this concept is that the data and its updaters are at a distance from the consuming component and require some mechanism for supplying the data to the consumer.

I'm going to use React's Context API to demonstrate. We're going to create a CounterContext and consume it with our Counter component.

const CounterContext = React.createContext()

function CounterProvider({ children, initialValue = 0 }) {
  const [count, setCount] = React.useState(initialValue)

  const increment = () => setCount(c => c + 1)
  const decrement = () => setCount(c => c - 1)
  const reset = () => setCount(initialValue)

  return (
    <CounterContext.Provider
      value={{
        count,
        decrement,
        increment,
        reset,
      }}
    >
      {children}
    </CounterContext.Provider>
  )
}

const useCounterContext = () => React.useContext(CounterContext)

function RemoteCounter() {
  const { count, decrement, increment, reset } = useCounterContext()

  return (
    <div>
      <div>Count: {count}</div>
      <div>
        <button type="button" onClick={increment}>
          +1
        </button>
        <button type="button" onClick={decrement}>
          -1
        </button>
        <button type="button" onClick={reset}>
          reset
        </button>
      </div>
    </div>
  )
}

function App() {
  return (
    <CounterProvider>
      <RemoteCounter />
    </CounterProvider>
  )
}

What is interesting about our RemoteCounter example is that because it consumes data managed remotely, instances of RemoteCounter within the same CounterProvider read and update the same data. Here are two RemoteCounters within a single CounterProvider:

We could accomplish something similar having components read and write to a global store in our application. Again, how data is managed remotely is not what's important here, understanding the pattern is what matters.

Conclusion

It doesn't matter how complicated an application you are building. There are still only three patterns for data management in a React application. Master these patterns. You will use them over and over and over again.

Adding Guards to a `useReducer` Finite State Machine

Wed, 27 May 2020 00:00:00 GMT

import LightBulbWithFuse from './_LightBulbWithFuse' import IndestructableBulb from './_IndestructableBulb'

The next part in our useReducer finite state machine journey is adding "guards". If you haven't read the previous posts in this collection, I encourage you to do so before reading ahead. Those posts are:

A "guard" is a predicate function <Marker content="A function that returns a boolean." /> used to conditionally determine if a state transition should happen. In simpler terms, if the guard function returns true, take the transition, otherwise do not.

Guards can be used to prevent any transition from taking place. For example, a trying to push open a locked door won't do anything at all. Or they can be used to take one transition instead of another. The "happy path" leads to one state, the "sad path" to another.

In order to support guards, we're going to need to be able to indicate that a transition has a guard. This means that we're going to have to make a change to the state an event is targeting.

Thus far, we've only had simple transitions. For example, the event BREAK has the value broken, indicating that this event transitions to the broken state. I would like this string to be a shorthand for an object, where the string points to the event's target.

// This...
const BREAK_EVENT = { BREAK: 'broken' }

// is equivalent to this
const BREAK_EVENT = { BREAK: { target: 'broken' } }

To accomplish this, we need another function, similar to toEventObject in the previous post. We can call this one toTransitionObject. It'll basically be the same.

const toTransitionObject = transition =>
  typeof transition === 'string' ? { target: transition } : transition

This normalizes the shape of our transitions. Let's make use of this inside of our stateReducer. There will be bigger changes later, but it'll be good to start with this one while it's a simple change.

const stateReducer = (state, event) => {
  const nextState = NEXT_STATE_GRAPH[state.current][event.type]

  // We don't want to use `toTransitionObject` on undefined, so guard & early
  // return here if there's no transition
  if (!nextState) return

  const { target } = toTransitionObject(nextState)

  return target
}

Now that our finite state machine utilizes target, we can add new properties to this object and utilize them in determining if a transition should be taken. This is how we're going to start utilizing guards.

Let's add a cond property whose value is a predicate function. When the predicate returns true, we'll return the target, otherwise no transition will be taken.

To implement this, let's imagine briefly that our light bulb is indestructable. We're going to give our BREAK event a transition whose cond property always returns false, and therefore is never taken.

const BREAK_EVENT = {
  BREAK: {
    target: 'broken',
    cond: () => false,
  },
}

Now, let's write the code necessary to respect this condition and not take this transition. This will involve modifying the stateReducer further.

const stateReducer = (state, event) => {
  const nextState = NEXT_STATE_GRAPH[state.current][event.type]

  if (!nextState) return

  const possibleTransition = toTransitionObject(nextState)
  // Use default assignment to guarantee that `cond`
  // is a function and returns true if it's undefined
  const { target, cond = () => true } = possibleTransition

  if (cond()) {
    return target
  }

  return
}

With that in place, our light bulb should be currently indestructable. Try it out here.

No matter how many times you click that BREAK button, it's not going to break. While an indestructable bulb is awesome, <Marker content="There's a bulb that's been on practically non-stop for over 100 years. Check it out <a href='https://99percentinvisible.org/episode/there-is-a-light-that-never-goes-out/'>There Is a Light That Never Goes Out</a>." /> it's pretty unlikely. One thing we can do is add a fuse before our light bulb that might prevent it from breaking.

In this case, we can add a hasFuse value to our data and check it's value as our cond predicate function. If our light bulb happens to have a fuse, we're going to transition to a new state, brokenFuse, instead of broken. Also, we'll rename broken to brokenBulb to be slightly more accurate.

const initialState = {
  current: 'unlit',
  data: {
    color: 'white',
    hasFuse: true,
  },
}

const BREAK_EVENT = {
  BREAK: {
    target: 'brokenFuse',
    cond: data => data.hasFuse,
  },
}

But wait! Didn't I say we want to transition to brokenBulb in the case where there isn't a fuse? <Marker content="I did." /> We need a way to have multiple targets for an event.

The most obvious data structure for this is an array of transition objects. Let's write that, and make our code use it next.

const BREAK_EVENT = {
  BREAK: [{ target: 'brokenFuse', cond: data => data.hasFuse }, 'brokenBulb'],
}

Now our BREAK_EVENT has two targets. If our bulb has a fuse, the machine will transition to brokenFuse, otherwise it'll transition to brokenBulb. But our machine doesn't know how to handle an array of transition objects yet. How do we adjust our code so that it can handle either an array or an object?

We could write the code with a condition that checks for the type and acts accordingly, but a simpler solution is to normalize all of our transitions into an array of transition objects. This means that we want these two structures to essentially be equivalent:

// This
const RESET_EVENT = {
  RESET: 'unlit',
}

// is equivalent to this
const RESET_EVENT = {
  RESET: ['unlit'],
}

// which is equivalent to this
const RESET_EVENT = {
  RESET: [{ target: 'unlit' }],
}

In order to achieve this, we're going to make yet another normalizing function, toArray:

const toArray = value => (Array.isArray(value) ? value : [value])

This simple function ensures that we're always dealing with an array of transitions. Now we need to add it to our stateReducer

// Notice we now need to pass our data into the reducer
const stateReducer = (state, event, data) => {
  const transitionValue = NEXT_STATE_GRAPH[state.current][event.type]

  // There is no transition to make
  if (!transitionValue) return

  const possibleTransitions = toArray(transitionValue).map(toTransitionObject)

  // We're going to use for..of so we can return as
  // early as possible
  for (const transition of possibleTransitions) {
    const { target, cond = () => true } = transition

    // We know we need the `data` for our predicate function
    // We also may want information on the event object as well
    if (cond(data, event)) {
      return target
    }
  }

  // No `cond` succeeded
  return
}

We're not quite done, we need to update our parent reducer function to pass data into our stateReducer function.

const reducer = (state, event) => {
  const eventObj = toEventObject(event)
  const nextData = dataReducer(state.data, eventObj)
  const nextState = stateReducer(state, eventObj, nextData)

  if (!nextState) return state

  return {
    current: nextState,
    data: nextData,
  }
}

We moved the calculation of any new data up in the reducer so that we can use the latest data in our nextState calculation and pass it in to be used by our guards.

We can do one more "optimization" if we'd like. Just like we have a DATA_UPDATERS map, we can make one for our guards as well. Then we can use a string identifier and retrieve our guard. This will make guards reusable in multiple states.

const GUARDS = {
  hasFuse: data => data.hasFuse,
}

//... our break event

const BREAK_EVENT = {
  BREAK: [
    {
      target: 'brokenFuse',
      cond: 'hasFuse',
    },
    'brokenBulb',
  ],
}

//... and in our stateReducer
for (const transition of possibleTransitions) {
  const { target, cond = () => true } = transition
  const condFn = typeof cond === 'string' ? GUARDS[cond] : cond

  if (condFn(data, event)) {
    return target
  }
}

And with that, we've successfully added guards to our useReducer finite state machine. Pretty impressive what we can do with a little effort. You can try out our light bulb with a fuse in the component below.

Summary

Adding guards allows us to conditionally transition states. This enables us to create powerful state machines that handle logic flows for us with the structure of the data, not with a bunch of conditionals in our event handling code. This is one of the key insights of state machines. The structure is the logic, and we don't have to accommodate further for it.

In order to enable guards, we had to do the following:

Normalize transition objects
Introduce the cond property, a predicate function for conditional transitions
Normalize possibleTransitions as an array to simplify our reducer

In the next post in this collection, we'll either try and clean this up a bit so we can make a package of it to pass around our application, or we'll swap out useReducer for useEffectReducer so that we can properly have actions. I haven't decided yet.

Break Out Your Component Logic with Hooks

Tue, 19 May 2020 00:00:00 GMT

import TogglingItem from './_TogglingItem' import ExplicitItem from './_ExplicitItem' import ItemsUsingCustomHook from './_ItemsUsingCustomHook'

Lately, I have had the opportunity to work on some new features at Webflow. It's exciting to build new things for your customers. It's also exciting because I've had the opportunity to finally dive head-first into React Hooks and learn and explore some new patterns. Some have been winners, some have been losers, but the education has been a lot of fun, regardless.

One pattern I've come to appreciate is breaking out the logic of a component into a custom hook, and then, only destructuring the parts of the hook's API my component needs. This decoupling allows my hook to be useful in multiple situations, while ensuring my component has no extraneous functionality. I want to teach you how I approach this.

Our Example

Let's start with an example where the logic and the UI that's rendered are coupled, that is, the logic that drives the UI is contained in the component itself. My recent work has involved a lot of "item selection", so we'll make an item that isSelected or isn't. <Marker content="I am avoiding using states and state machines on purpose. I want to explicitly use a binary, in this case a boolean, for my example." />

function Item() {
  const [isSelected, setSelected] = React.useState(false)

  const toggleSelection = () => {
    setSelected(x => !x)
  }

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <button type="button" onClick={toggleSelection}>
        Toggle
      </button>
    </div>
  )
}

Great, our component works as expected.

Now, imagine you have been asked to make a similar component, but with explicit select and unselect buttons. Let's write that component, too. <Marker content="I am being purposefully verbose for didactic purposes" />

function SimilarItem() {
  const [isSelected, setSelected] = React.useState(false)

  const select = () => {
    setSelected(true)
  }

  const unselect = () => {
    setSelected(false)
  }

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <div>
        <button type="button" onClick={select}>
          Select
        </button>
        <button type="button" onClick={unselect}>
          Unselect
        </button>
      </div>
    </div>
  )
}

That component works as well, but we've repeated quite a bit of code. In both examples, we're using essentially the same logic, deriving a different API from that logic, and exposing it to our UI. This seems like a great opportunity to abstract the logic away from our component to reduce duplication.

Creating a Custom Hook

We want to pull the logic out of our component and into a custom hook that our component can then consume. When I do a refactor like this, I attempt to do it step-by-step, keeping the code working the entire time. Let's try and do that here with our first Item. The first step in this refactor is to pull some of the logic into a custom hook.

// I'll give this a better name soon, but for now, this works
function useItemLogic() {
  const [isSelected, setSelected] = React.useState(false)

  const toggleSelection = () => {
    setSelected(state => !state)
  }

  return {
    isSelected,
    toggleSelection,
  }
}

function Item() {
  const { isSelected, toggleSelection } = useItemLogic()

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <button type="button" onClick={toggleSelection}>
        Toggle
      </button>
    </div>
  )
}

This is a good start, but it's not abstract enough yet and can't be used in our SimilarItem as it is. What's different between our two items?

The state setting functions.

Let's add these explicit functions to our useItemLogic hook.

function useItemLogic() {
  const [isSelected, setSelected] = React.useState(false)

  const select = () => {
    setSelected(true)
  }

  const unselect = () => {
    setSelected(false)
  }

  const toggleSelection = () => {
    setSelected(state => !state)
  }

  return {
    isSelected,
    select,
    toggleSelection,
    unselect,
  }
}

function Item() {
  const { isSelected, toggleSelection } = useItemLogic()

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <button type="button" onClick={toggleSelection}>
        Toggle
      </button>
    </div>
  )
}

function SimilarItem() {
  const { isSelected, select, unselect } = useItemLogic()

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <div>
        <button type="button" onClick={select}>
          Select
        </button>
        <button type="button" onClick={unselect}>
          Unselect
        </button>
      </div>
    </div>
  )
}

Great, now our logic is separated and working in both our components, but it really isn't named well at all. For starters, useItemLogic doesn't convey anything about the API, which is fine if this were not intended for reuse, but it is. Also, names like isSelected and toggleSelection imply more about the actual state maintained in our hook than is true. Our hook merely contains a binary, in this case, a boolean. So let's rename parts of our abstraction to reflect this information.

// We parameterize the initialState and provide a default value of false
function useBooleanAPI(initialState = false) {
  // Using the Boolean constructor ensures that the hook cannot be
  // given an initial state of the wrong type
  const [state, setState] = React.useState(Boolean(initialState))

  const setTrue = () => {
    setState(true)
  }

  const setFalse = () => {
    setState(false)
  }

  const toggle = () => {
    setState(x => !x)
  }

  return {
    setFalse,
    setTrue,
    state,
    toggle,
  }
}

Now, that we have a generalized abstraction for our hook, we can use only the parts of the interface that are important to our component and rename the APIs so they provide more context to our component's use case.

function Item() {
  const { state: isSelected, toggle: toggleSelection } = useBooleanAPI()

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <button type="button" onClick={toggleSelection}>
        Toggle
      </button>
    </div>
  )
}

function SimilarItem() {
  const {
    state: isSelected,
    setFalse: unselect,
    setTrue: select,
  } = useBooleanAPI()

  return (
    <div>
      <div>Is selected? {String(isSelected)}</div>
      <div>
        <button type="button" onClick={select}>
          On
        </button>
        <button type="button" onClick={unselect}>
          Off
        </button>
      </div>
    </div>
  )
}

Now, both our components consume the same interface, but have the freedom to use only the parts of that interface it requires and to rename parts of that functionality to reflect the context in which they are used. Not only that, but our individual components became smaller and a bit simpler to understand. We no longer have our logic tightly coupled to our component.

Conclusion

React Hooks are an excellent way to practice decoupling our user interface from the logic driving it. We can create abstractions that can be consumed and contextualized by other components. This allows us to encapsulate concerns, enable reuse, and keep the surface area of our components small. I hope you can see the benefits of this pattern and how you might use it to refactor and decouple your own components.

Adding Infinite States to a `useReducer` Finite State Machine

Fri, 15 May 2020 00:00:00 GMT

import HueLightBulb from './_HueLightBulb'

Before reading this post, I encourage you to read How to Use useReducer as a Finite State Machine if you haven't already. In that post, I demonstrate how to make the React Hook useReducer behave like a finite state machine using a statechart-like graph. I'm going to expand upon that work today.

The next thing we need to add to our useReducer-based finite state machine is contextual data. Not all data can be modeled as a set of finite states (nor should it). Consider the humble <input />. A user can provide an infinite number of strings as a value to the input. By definition, we cannot model the infinite with the finite, and thus we need a way to store infinite contextual data in our machine. It will be very useful to us when we add guards and conditions in a future post.

In XState, infinite state data is stored on the context object of the state machine. Because React also has a concept of context and I do not wish to conflate the two concepts, so I will simply call this data. This means that our state machine's state is not the only thing being returned by our reducer anymore, and so we need a name for that as well. In this post, I will call this current, as in the "current state". Let's make these our first changes to our state machine. We'll continue to use the LightBulb from the previous post as the object that we are modeling.

const initial = {
  current: 'unlit',
  data: {},
}

//...

const reducer = (state, event) => {
  const { current } = state
  const nextState = NEXT_STATE_GRAPH[current][event]

  return nextState !== undefined ? nextState : state
}

//...

function LightBulb() {
  const [state, send] = useReducer(reducer, initial)
  const { current } = state

  return (
    <div>
      State: {current}
      <button type="button" onClick={() => send('TOGGLE')}>
        Toggle
      </button>
      <button type="button" onClick={() => send('BREAK')}>
        Break
      </button>
    </div>
  )
}

Our light bulb continues to work as it did before, so now let's modify it so that we need to store some data and make use of it. Here is the specification we're going to build into our reducer:

If the nextState is undefined, do not update the current state or data
Otherwise, update the state and update the data if necessary

Let's modify our reducer to accommodate this:

const reducer = (state, event) => {
  const { current, data } = state
  const nextState = NEXT_STATE_GRAPH[current][event]

  if (!nextState) return state

  const nextData = data // we need to write the code that will update this still

  return {
    current: nextState,
    data: nextData,
  }
}

We've laid the foundation for updating data in response to an event, but our code does not support passing data along with an event yet. At the moment, an event is merely a string. We need to be able to pass more information along with the event. How can we support being able to use a string for an event, and also pass data with it?

By making every event an object under the hood.

This is one of my favorite features of XState and a pattern that's easy to borrow. All we need to do is turn an event like TOGGLE into an object like { type: 'TOGGLE' } under the hood. This will allow the user to supply simple strings if no data needs to be on the event, or an object with the additional data. We accomplish this by normalizing the events into the same shape.

const toEventObject = event =>
  typeof event === 'string' ? { type: event } : event

We now use toEventObject in our reducer to normalize the event before using it to determine the nextState.

const reducer = (state, event) => {
  event = toEventObject(event)
  const { current, data } = state
  const nextState = NEXT_STATE_GRAPH[current][event.type]

  if (!nextState) return state

  const nextData = data

  return {
    current: nextState,
    data: nextData,
  }
}

Now that we've normalized the event into an object, we'll be able to pass along extra data on that object when we send events to our machine. Let's modify our example so that our LightBulb needs some contextual data. Let's add color to our light bulb so that when it's lit, we can change the color with a CHANGE_COLOR event.

This is where I'm going to introduce several things and start to make some deviations from XState, so bear with me.

We now have an event that will not change the state of the light bulb. Sending a CHANGE_COLOR event should keep us in a lit state. Since our state graph depends on having a defined value for an event, we need to add the CHANGE_COLOR event to our NEXT_STATE_GRAPH object. I'm going to add a RESET event while we're at it, and use object spreading to dry up some events that are used in multiple states.

const BREAK_EVENT = { BREAK: 'broken' }
const RESET_EVENT = { RESET: initialState.current }

const NEXT_STATE_GRAPH = {
  lit: {
    ...BREAK_EVENT,
    ...RESET_EVENT,
    CHANGE_COLOR: 'lit', // Notice we stay in the same state
    TOGGLE: 'unlit',
  },
  unlit: {
    ...BREAK_EVENT,
    ...RESET_EVENT,
    TOGGLE: 'lit',
  },
  broken: {
    ...RESET_EVENT,
  },
}

We also need a way for CHANGE_COLOR to trigger an update to our data. The way I'm choosing to do this is with an object called DATA_UPDATERS. Each updater function will receive the current data and the event that triggered the updater call.

const DATA_UPDATERS = {
  CHANGE_COLOR: (data, event) => ({ ...data, color: event.color }),
  RESET: () => initial.data,
}

Now, we need to update our reducer to actually use our DATA_UPDATERS. I'm going to make a slight refactor here as I do it where I will "split the loops" of our state reduction and our data reduction into two separate reducers.

const stateReducer = (state, event) =>
  NEXT_STATE_GRAPH[state.current][event.type]

const dataReducer = (data, event) => {
  const updater = DATA_UPDATERS[event.type]
  return updater ? updater(data, event) : data
}

const reducer = (state, event) => {
  event = toEventObject(event)
  const nextState = stateReducer(state, event)

  if (!nextState) return state

  const nextData = dataReducer(state.data, event)

  return {
    current: nextState,
    data: nextData,
  }
}

Now we can add some UI to our HueLightBulb that supports changing colors.

const EVENTS = ['TOGGLE', 'BREAK', 'RESET']
const COLORS = [
  { name: 'white', value: '#feffeb' },
  { name: 'red', value: '#ff674f' },
  { name: 'blue', value: '#5cb6ff' },
  { name: 'green', value: '#8ff244' },
]

function HueLightBulb() {
  const [state, send] = useReducer(reducer, initial)
  const { current, data } = state

  return (
    <div>
      <span>State: {current}</span> <span>Color: {data.color}</span>
      <div>
        <span>Events</span>
        <div>
          {EVENTS.map(event => (
            <button key={event} type="button" onClick={() => send(event)}>
              {event}
            </button>
          ))}
        </div>
      </div>
      <div>
        <span>Change colors</span>
        <div>
          {COLORS.map(({ name, value }) => (
            <button
              key={name}
              type="button"
              onClick={() => send({ type: 'CHANGE_COLOR', color: value })}
            >
              {name}
            </button>
          ))}
        </div>
      </div>
    </div>
  )
}

Now we're able to change the colors of our bulb, but only when we are in the lit state. We have a useReducer-based state machine that can handle infinite state data!

I made a component for you to play with that contains a few extra bells and whistles, including some SVGs that I made <Marker content="Be kind. I don't really have any vector art skills whatsoever" /> to show all the states of our bulb.

If you prefer to tinker with the code itself, an iteration of this example exists on Codesandbox for you to fork: https://codesandbox.io/s/usereducer-fsm-with-infinite-states-v2b1g

Conclusion

Infinite data cannot be modeled as a finite set of states, but we still want to have the control and guarantees a state machine gives us about our program. We can achieve this by storing this extra data in our state. We can make updates to this data through event objects. We only make updates to our data when our state graph allows it, and we guarantee the deterministic output of our state through reducers for our current state and our data.

In a future post, we'll add the concept of guards to our state machine that will require some modifications to how we think of our contextual data, but I hope this continues to inspire your imagination on how to write more robust programs in the mean time.

Can a State Machine be a String?

Thu, 07 May 2020 00:00:00 GMT

import LightBulb from './_LightBulb'

Near the end of last year, I was doing prep work for my first workshop on state machines. In my research, I came across this simple, but effective graph editor: https://csacademy.com/app/graph_editor/.

I was impressed with how simple it was to represent a graph with just a few lines of text. On the left side of the web page, under "Graph Data", is a simple text input. You generate the graph by writing nodes next to each other. The light bulb example I used in the previous post is written like this:

lit unlit
unlit lit
lit broken
unlit broken

Which generates this graph image:

I was blown away. A graph can be represented simply as a string if you followed a few rules. This got me thinking, "Can I do the same for a state machine?" Turns out you can.

In order to represent a state machine as a string, we only need to make a couple adjustments.

We need to be able to derive an id from our string
We need to be able to indicate the initial state
We need to be able to indicate what events will trigger transitions

Accomplishing the first two criteria was pretty simple: dedicate the first two lines of our string to id and initial respectively. With our light bulb example, it would look like this:

lightBulb
unlit

Adding the events required having a way to define an edge as an event type. I chose to accomplish the same way a weighted graph is represented as a string.

lit unlit TOGGLE
unlit lit TOGGLE
lit broken BREAK
unlit broken BREAK

Now, we need a function that will parse this text into a valid state machine. Let's setup the skeleton of that function.

function statechart(string) {
  return {} // We'll eventually return a valid statechart here.
}

Next, we should maybe write a couple tests to validate what we're accomplishing. Let's start with deriving the id.

describe('statechart', () => {
  it('should derive an `id` from the first line', () => {
    const chart = statechart(`
      lightBulb
    `)
    expect(chart.id).toEqual('lightBulb')
  })
})

This, of course, fails because we haven't made any changes to the code to accomplish this. Let's write the simplest thing we can to get the test passing.

function statechart(string) {
  const id = string.trim()

  return {
    id,
  }
}

That passes. Now we can add a second test for the initial state.

describe('statechart', () => {
  // ...
  it('should derive an `initial` state from the second line', () => {
    const chart = statechart(`
      lightBulb
      unlit
    `)
    expect(chart.initial).toEqual('unlit')
  })
})

In order to get this test passing, we need to do something a bit more interesting. We need to split our string on new lines in order to separate the two items: id and initial state. We also need to trim those lines and get rid of the whitespace. Lastly, we want to filter out any empty strings.

function statechart(string) {
  const parsedString = string
    .split(/\n/)
    .map(s => s.trim())
    .filter(Boolean)
  const [id, initial] = parsedString

  return {
    id,
    initial,
  }
}

That passes, too. Now let's go for it and add a test for handling our states.

describe('statechart', () => {
  //...
  it('should derive the `states` from the rest of the lines', () => {
    const chart = statechart(`
      lightBulb
      unlit
      lit unlit TOGGLE
      unlit lit TOGGLE
      lit broken BREAK
      unlit break BREAK
    `)

    expect(chart.states).toEqual({
      lit: {
        on: {
          TOGGLE: 'unlit',
          BREAK: 'broken',
        },
      },
      unlit: {
        on: {
          TOGGLE: 'lit',
          BREAK: 'broken',
        },
      },
      broken: {},
    })
  })
})

This is where the crux of the work takes place. We'll start by collecting all the rest of the string into an array of stateStrings.

const [id, initial, ...stateStrings] = parsedString

From here, we need to turn these into stateNodes. We're going to turn these into an array of objects with a start, end and event property. It'll make things easier down the road.

const stateNodes = stateStrings
  .map(s => s.split(' '))
  .map(([start, end, event]) => ({
    start,
    end,
    event,
  }))

Now we have a map of these nodes, we need to reduce that down to a single states object.

function statechart(string) {
  // ...
  const states = stateNodes.reduce((acc, cur) => {
    const { start, end, event } = cur

    // check if this starting node is in `acc` yet
    if (!acc[start]) {
      acc[start] = {
        on: {},
      }
    }

    // check if the `end` is a state yet
    if (!acc[end]) {
      acc[end] = {}
    }

    // Add the event and transition here, spread any previous
    // [event]: end key/value pairs
    acc[start].on = {
      ...acc[start].on,
      [event]: end,
    }

    return acc
  }, {})

  return {
    id,
    initial,
    states,
  }
}

Sweet, this gets our tests all passing! Now we can try it out in a component.

import React from 'react'
import { Machine } from 'xstate'
import { useMachine } from '@xstate/react'
import statechart from './statechart'

const chart = statechart(`
lightBulb
unlit
lit unlit TOGGLE
unlit lit TOGGLE
lit broken BREAK
unlit broken BREAK
lit unlit RESET
broken unlit RESET
`)

const lightBulbMachine = Machine(chart)

function LightBulb() {
  const [state, send] = useMachine(lightBulbMachine)

  return (
    <div>
      State: {state}
      <div>
        <Button onClick={() => send('TOGGLE')}>Toggle</Button>
        <Button onClick={() => send('BREAK')}>Break</Button>
        <Button onClick={() => send('RESET')}>Reset</Button>
      </div>
    </div>
  )
}

And let's check it out here:

If you want to see this code and play around with it, you can check out this Codesandbox: https://codesandbox.io/s/fsm-as-a-string-g3rcp

Drawbacks to This Approach

I hope it's clear that this is simply an experiment. I don't see this as a long-term useful solution. That said, I want to admit the many drawbacks that would happen from adopting this.

No type safety with TypeScript or Flow
No guards for conditional logic
No hierarchical or parallel states
No actions for side effects
No ability to add top-level events <Marker content="Like adding a RESET event to all states in our LightBulb machine by adding a top level <code>on</code> object" />

Conclusion

I think this approach would really only be useful to someone who wanted to save a few keystrokes in building their machines. I wouldn't recommend it to anyone!

But, I do recommend experimenting and seeing what you learn. My first iterations on this function involved using tagged templates and I learned a few things about writing those. It never hurts to spend some time trying something in a different way, and I hope this inspires you to try a few more experiments yourself.

How to Use `useReducer` as a Finite State Machine

Mon, 04 May 2020 00:00:00 GMT

import LightBulb from './_LightBulb'

I recently attempted to get XState into the Webflow codebase to manage some challenging and complex UIs but was met with resistance. No big deal, this is a part of work, consensus driving, disagreeing and committing, etc. If it hasn't happened to you yet, it will.

One of the things you need when that happens is a good imagination. How do we make the tools we already have do the things we want in a reasonable way? I'm going to help you with that today by showing you a way to make useReducer behave like a simple finite state machine in React.

I've started using the following pattern in some of my work and I think it will help you. <Marker content="A few caveats up front. You won't have access to hierarchical state machines with this approach. You also will not have the ability to trigger side effects from state changes. I will discuss this briefly here, but plan to cover it in another blog post." /> If we look at the reducer of useReducer and a state machine, we can see that they are quite similar. They both take a current state and an event (Redux calls this an action, but I will use event throughout this post), and return the next state. The differences are:

A reducer does not restrict itself to a set of finite states
A reducer has no mechanism for calling side effects from state transitions

We can't do anything about the second point, and I will cover that in a future post on useEffectReducer, but we can do something about the first. We can create a graph of states that our reducer will use to transition to the next state. I'll demonstrate how I approach this.

I'm going to use the example of a light bulb like I do in my XState course. A bulb has three states: lit, unlit, and broken. Let's make a NEXT_STATE_GRAPH object starting with these states.

const NEXT_STATE_GRAPH = {
  lit: {},
  unlit: {},
  broken: {},
}

Next, let's define the events that will transition each state to their next state.

const NEXT_STATE_GRAPH = {
  lit: {
    TOGGLE: 'unlit',
    BREAK: 'broken',
  },
  unlit: {
    TOGGLE: 'lit',
    BREAK: 'broken',
  },
  broken: {},
}

Now, we're going to use this in the reducer we will pass to useReducer to get our next state.

const reducer = (state, event) => {
  const nextState = NEXT_STATE_GRAPH[state][event]
  return nextState !== undefined ? nextState : state
}

That's it! A reducer doesn't need to be complicated or use a switch statement. It just has to deterministically give you the next state. Let's apply this to a simple component.

function LightBulb() {
  // we can change `dispatch` to `send` to look more like using XState
  const [state, send] = useReducer(reducer, 'unlit')

  return (
    <div>
      State: {state}
      <button type="button" onClick={() => send('TOGGLE')}>
        Toggle
      </button>
      <button type="button" onClick={() => send('BREAK')}>
        Break
      </button>
    </div>
  )
}

You can see it in action right here. Be sure to click buttons a state shouldn't respond to as well! <Marker content="You can check out my blog repo for more details on how I implemented <code>reset</code> in my reducer here." />

Types

One small issue I ran into while implementing this was that our type system, Flow, was not happy that I was using the failure of finding a key on an object to return undefined on purpose. Type systems hate when you use a language feature like that. No problem, I made a simple fix by adjusting our NEXT_STATE_GRAPH slightly.

// Let's make an object of all our events with an undefined next state
const NON_RESPONSIVE_EVENTS = {
  BREAK: undefined,
  TOGGLE: undefined,
}

// Now let's spread that object into all our states
const NEXT_STATE_GRAPH = {
  lit: {
    ...NON_RESPONSIVE_EVENTS,
    BREAK: 'broken',
    TOGGLE: 'unlit',
  },
  unlit: {
    ...NON_RESPONSIVE_EVENTS,
    BREAK: 'broken',
    TOGGLE: 'lit',
  },
  broken: {
    ...NON_RESPONSIVE_EVENTS,
  },
}

Now each state node will have a key for any event and explicitly returns undefined in those situations where we do not want to make a state transition. We simply override the non-responsive events with responsive ones below, taking advantage of how object spreading works. <Marker content="Key/value pairs that have the same key as a previous one will overwrite the previous value with the new one." /> This will appease any exhaustive check a type system demands.

Conclusion

There you have it, a simple finite state machine using useReducer. I'll make another post soon on how to handle infinite state data alongside finite states with useReducer, but this should be enough to get your brain juices flowing and experimenting with this approach.

Guidelines for State Machines and XState

Fri, 03 Apr 2020 00:00:00 GMT

Intro
What is a State Machine?
Why Booleans are a Misguided Approach
Side Effects with State Machines
Context in State Machines
Guards and Conditions
Function Components & Hooks
Class Components
Complex Machines
1. Hierarchical Machines
2. Parallel Machines
Visualizing State Machines
How to Approach Creating a State Machine
Testing
Resources

Intro

This exists as a living document to define some guidelines regarding state machines and their usage. These guidelines are by no means exhaustive, but hopefully set you on the right path. It is highly recommended that you read the XState docs for more information.

What is a State Machine?

A state machine, more specifically a finite state machine, is a means of representing all the possible enumerated states of a system and the possible enumerated transitions between states in that system. That was a bit jargon heavy, so let's use a brief example to illuminate what this means.

Consider a light bulb. A light bulb typically has two states: lit and unlit. When we have two states, we are often tempted to represent this state with a boolean, true or false, but often this is a misguided approach to state management. We will explore why in the next section. Instead, let's define these two states as objects.

const lit = {}
const unlit = {}

const states = {
  lit,
  unlit,
}

Next, let's define the possible transitions for each state to the other states. I will follow the conventions of the XState library, in order to introduce the API to you.

const lit = {
  on: { TURN_OFF: 'unlit' },
}
const unlit = {
  on: { TURN_ON: 'lit' },
}

We define "events" on the on property of a state node in XState (and by convention, they are in scream case 😱). Machines respond to these events, but only when the current state has an enumerated event of the same type. In the context of this example, if an event of type: 'TURN_OFF' is sent to the machine, it will respond and transitions states only when we are in the lit state. Sending the TURN_OFF event to a light bulb that's in the unlit state will have no effect.

In this example, our events use the common shorthand of EVENT_NAME: 'nextStateName' In long form, this is equivalent to EVENT_NAME: { target: 'nextStateName' }. Use the shorthand if you do not need to add any "actions" or "conditions", the longhand otherwise. "Actions" and "conditions" will be covered later in these guidelines.

Let's combine what we've written so far into an actual XState machine. Machines receive an id, an initial state, and a states object of the enumerated state nodes.

import { Machine } from 'xstate'

const lit = {
  on: { TURN_OFF: 'unlit' },
}

const unlit = {
  on: { TURN_ON: 'lit' },
}

const states = {
  lit,
  unlit,
}

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states,
})

Let's move our lit and unlit states directly into the Machine config object to tidy this up:

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      on: { TURN_OFF: 'unlit' },
    },
    unlit: {
      on: { TURN_ON: 'lit' },
    },
  },
})

Every machine has a transition method, which receives a state and an event and returns the next state. This is very similar to a reducer for Flux or Redux.

lightBulbMachine.transition('lit', 'TURN_OFF').value // 'unlit'
lightBulbMachine.transition('unlit', 'TURN_OFF').value // 'unlit'
lightBulbMachine.transition('unlit', 'TURN_ON').value // 'lit'

Using the transition method explicitly is not common for most state machine usage with XState. Instead, a service is used to maintain the current state of the machine and send events to the machine. This will be discussed further, specifically in the section on Class Components

Why Booleans are a Misguided Approach

Looking more closely at our light bulb, one might realize that there is actually a third state that a light bulb can be in: broken.

A broken light bulb is different than an unlit light bulb and deserves its own state. If we were attempting to model a light bulb with these three states using booleans, we'll discover a problem right away.

Most likely we would use two booleans to cover the possible states: isLit and isBroken. Since we are representing these states with booleans, each state has two possible outcomes. We can calculate the possible state permutations with the equation 2^n, where n is the number of states (2 because the enumerated states of a boolean is 2: true and false). Thus, trying to cover our light bulb with two booleans reveals that we've actually created four states.

isLit	isBroken
false	false
false	true
true	false
true	true

But we only have three states in our model? Where did this fourth state come from? This fourth state is an "impossible state", a state our system should not be capable of getting to. It occurs when we have isLit && isBroken.

Now, we're decent programmers and can typically code around this with guards and conditional logic, but as we start to add booleans to manage state, that explosion of possible permutations continues at a rapid pace. In just a few iterations, the permutations grow: 2, 4, 8, 16, 32, 64, 128, etc.

State machines avoid this problem by forcing us to enumerate only the possible states and transitions, which more accurately models what we are trying to achieve anyways. Making an accurate light bulb devoid of impossible states is as simple as adding a new state node and some events to respond to.

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken',
      },
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken',
      },
    },
    broken: {
      type: 'final',
    },
  },
})

For a bonus touch, we add the type: 'final to the broken state. It is encouraged that you add this to any final state in your machine, though it is not necessary. It is useful in more complex situations where machines invoke other machines. That will not be covered in this guideline. Please refer to the XState docs about Invoking Services.

Side Effects with State Machines

State machines respond to events. Events may or may not trigger a transition. As a result of transitions, we have the opportunity to produce side effects. These side effects are called "actions".

We can call actions at three moments in the state transition cycle, and they happen in this order.

on exit from a state
on the transition to a state
on entry to a state

Let's fire actions of each kind in our light bulb example.

import { Machine } from 'xstate'

// We can break pieces of our chart out and compose them together
// just as we would any other object
const breakEvent = {
  BREAK: {
    // BREAK: 'broken' is a shorthand for BREAK: { target: 'broken' }
    target: 'broken',
    actions: ['informUserOfBrokeLightBulb'],
  },
}

const lightBulbMachine = Machine(
  {
    id: 'lightBulb',
    initial: 'unlit',
    states: {
      lit: {
        entry: 'enterLit', // If only a single action is taken, a string will suffice
        on: {
          TURN_OFF: 'unlit',
          ...breakEvent,
        },
      },
      unlit: {
        exit: ['leaveUnlit'],
        on: {
          TURN_ON: 'lit',
          ...breakEvent,
        },
      },
      broken: {
        type: 'final',
      },
    },
  },
  {
    actions: {
      // all actions receive the machine's `context` and the `event` that triggered the action.
      // More on context later
      enterLit: (context, event) => {
        console.log(`Light bulb lit from ${JSON.stringify(event)}`)
      },
      leaveUnlit: () => {
        console.log('We can do more than log stuff, this is just an example')
      },
      informUserOfBrokeLightBulb: (_, event) => {
        // we can put more information on an event object, such as
        // { type: 'BREAK', bulbId: 'someUUIDOrSomething' }
        contactUserAboutBrokenBulb(event.bulbId)
      },
    },
  },
)

We have defined all our actions as strings and made matching methods in the second argument to Machine(). This is the preferred way to add actions to machines. You can write functions inline in actions or entry or exit, however, following the guideline of using strings will be especially useful when we start combining XState and React.

Context in State Machines

The concept of context has a different meaning in state machines than it does in React. In React, context is a state held in closure to be referenced by many components via a providing and consuming component architecture. It is used to avoid excessive "prop drilling" among other things.

In state machines, context is used to store data that cannot be easily represented by finite states. In fact, it is most often used to keep track of infinite states.

Consider a text input. There exists an infinite number of strings that could be used as the value of that input. It therefore would require an infinite number of states to model that system. This is simply impossible.

That said, occasionally we need values that result in infinite states in order to accomplish a variety of tasks. Thus, context in state machines.

Think of context in a state machine similar to how you think of state in React. It is localized to the machine. It can be updated when necessary and can be referenced by the machine.

context is added as a context object on the config object of a machine. Let's take our light bulb example and add a color to it in context.

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  // We'll add `context` here
  context: {
    color: '#fff',
  },
  states: {
    lit: {
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken',
      },
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken',
      },
    },
    broken: {
      type: 'final',
    },
  },
})

We've added color to context. Now, let's create an event to update the color.

import { assign, Machine } from 'xstate'

const lightBulbMachine = Machine(
  {
    id: 'lightBulb',
    initial: 'unlit',
    // We'll add `context` here
    context: {
      color: '#fff',
    },
    states: {
      lit: {
        on: {
          CHANGE_COLOR: {
            actions: ['updateColor'],
          },
          TURN_OFF: 'unlit',
          BREAK: 'broken',
        },
      },
      unlit: {
        on: {
          CHANGE_COLOR: {
            actions: ['updateColor'],
          },
          TURN_ON: 'lit',
          BREAK: 'broken',
        },
      },
      broken: {
        type: 'final',
      },
    },
  },
  {
    actions: {
      updateColor: assign((context, event) => ({
        color: event.color,
      })),
    },
  },
)

We've added a CHANGE_COLOR event to the lit and unlit states. We can send a color value on an event object. The machine responds to the event, calling the actions for that event. The action in this case is updateColor, which is a special action known as an assign.

assign is a action creator function for XState used specifically to update context. It works very similar to React's setState. It has two APIs that will be familiar to React developers:

assign can take an object as an argument, merging it with the current context to get the nextContext

assign({
  color: '#f00',
})

It can receive an updater function that returns an object to be merged with the current context to get the nextContext. This updater function receives the current context and the event as arguments.

assign((context, event) => ({
  color: event.color,
}))

A third API exists that is different from React.setState, an object whose values are function updaters

assign({
  color: (context, event) => event.color,
})

Any of these APIs is fine to use. In some ways, it is simpler than React.setState as there are no async issues to concern yourself with. There is one "gotcha" to understand about assigns though. All assigns are run before other actions. This is simple to understand when you consider that Machine.transition is a pure function that receives a state, event and context to derive the nextState. In order to give it the correct context, assigns must be run to determine the next state. Read more about this in the XState docs under Context - Action Order.

Now that we understand assign actions, let's use it on our light bulb machine to change the color.

const nextState = lightBulbMachine.transition('lit', {
  type: 'CHANGE_COLOR',
  color: '#f00',
}) // { value: 'lit', context: { color: '#f00' } }

Take notice that we have an event that only triggers actions. It does not have a target state. This is useful when we want to respond to events in a state without making a state transition.

Guards and Conditions

It won't be long before you come to a point where you would like to make a transition to a state conditional. This is accomplished through the use of a guard function on the cond property of a state node.

Let's consider a fancier light bulb, one with a "locking mechanism" that prevents a user from turning it on. Perhaps it's a child's bedside lamp and we'd like to prevent them from reading during the night. We can create a condition that prevents the transition to the lit state to model this.

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken'
      }
    },
    unlit: {
      on: {
        TURN_ON: {
          target: 'lit',
          cond: 'isDaylightHours'
        ],
        BREAK: 'broken'
      }
    },
    broken: {
      type: 'final'
    }
  }
}, {
  guards: {
    isDaylightHours: (context, event) => {
      return event.time.getHours() > 7 || event.time.getHours() < 21
    }
  }
})

We've created a guard function named isDaylightHours. It's a predicate function (a function that returns a boolean). We've referenced that function on the cond property of the TURN_ON event in the unlit state. If the guard returns true, the transition is taken to lit, otherwise it will remain unlit.

Guards are a simple, yet effective way to model conditional state transitions. Be wary if your guard is really a child state of a parent state in disguise. This refers to hierarchical states, which will be covered in the Hierarchical Machines section.

Function Components & Hooks

The @xstate/react package ships a very useful hook, useMachine, that can be used in function components to easily instantiate a service for a machine. useMachine accepts a Machine as its first argument and an options object as its second object. In this way, we're able to create a machine that defines our component's enumerated states and transitions outside the scope of the function, but use any props or functions in the scope of the component within the options object.

import React from 'react'
import {Machine} from 'xstate'
import {useMachine} from '@xstate/react'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken'
      }
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken'
      }
    },
    broken: {
      type: 'final'
      entry: ['logBroken']
    }
  }
})

const TEXTS_BY_STATE = {
  lit: 'LIGHT!',
  unlit: 'not light',
  broken: 'so borked'
}

function LightBulb({ id }) {
  const [state, send] = useMachine(lightBulbMachine, {
    actions: {
      logBroken: () => {
        console.log(`Light bulb with id: ${id} has broken`)
      }
    }
  })

  return (
    <div>
      {TEXTS_BY_STATE[state.value]}
      <div>
        <button onClick={() => send('TURN_ON')} type="button">Turn On</button>
        <button onClick={() => send('TURN_OFF')} type="button">Turn Off</button>
        <button onClick={() => send('BREAK')} type="button">Break</button>
      </div>
    </div>
  )
}

In the above example, we render all of the buttons regardless of what state.value is. We can disable buttons based on the current state with state.matches().

state.matches() accepts a string or object representing a state and returns a boolean regarding if it matches or not. We can use it like this:

return (
  <div>
    {TEXTS_BY_STATE[state.value]}
    <div>
      <button
        disabled={state.matches('lit')}
        onClick={() => send('TURN_ON')}
        type="button"
      >
        Turn On
      </button>
      <button
        disabled={state.matches('unlit')}
        onClick={() => send('TURN_OFF')}
        type="button"
      >
        Turn Off
      </button>
      <button
        disabled={state.matches('broken')}
        onClick={() => send('BREAK')}
        type="button"
      >
        Break
      </button>
    </div>
  </div>
)

We can extrapolate this API, the use of state.value and state.matches() to handle all condition based rendering and functionality in our components and more.

Class Components

It is possible to use XState with class components as well, but this will require a few extra steps and a new concept. The concept first.

A state machine, specifically the transition method on a machine, is a pure function. We give it a state and an event (and we can supply a context as the third argument) and we should get the same next state every time. Being pure means that the machine itself does not store the current state. Instead, we are responsible for that. We can accomplish this through using a service.

A service is used to maintain the current state. We also send events to the service (hence where send comes from with the useMachine hook) which are passed along the machine's transition method internally. We can start a service by using the interpret function from XState. Let's write our light bulb component as a class component.

import React from 'react'
import {Machine, interpret} from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken'
      }
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken'
      }
    },
    broken: {
      type: 'final'
      entry: ['logBroken']
    }
  }
})

const TEXTS_BY_STATE = {
  lit: 'LIGHT!',
  unlit: 'not light',
  broken: 'so borked'
}

class LightBulb extends React.Component {
  state = {
    current: lightBulbMachine.initialState
  }

  config = {
    actions: {
      logBroken: () => {
        const { id } = this.props
        console.log(`Light bulb with id: ${id} has broken`)
      }
    }
  }

  service = interpret(lightBulbMachine.withConfig(this.config))
    .onTransition(current => {
      this.setState({ current })
    })

  componentDidMount() {
    this.service.start()
  }

  componentWillUnmount() {
    this.service.stop()
  }

  render() {
    const { current } = this.state
    const { send } = this.service

    return (
      <div>
        {TEXTS_BY_STATE[current.value]}
        <div>
          <button onClick={() => send('TURN_ON')} type="button">Turn On</button>
          <button onClick={() => send('TURN_OFF')} type="button">Turn Off</button>
          <button onClick={() => send('BREAK')} type="button">Break</button>
        </div>
      </div>
    )
  }
}

I want you to take notice of a few key things:

We need to start and stop our service. This is because in complex state machines, there activities and long running side effects that depend on these methods being called.
We can configure our state machine with local props and methods, but we must do so by extending the machine using the withConfig method. This is different than the useMachine hook, where we could supply a second argument to the function instead.
We store the current state in local React state. We use the service's onTransition method to keep state in sync in our component.

While it is more code, it does mean that state machines can be introduced to legacy components without the need to update them to function components that can use the useMachine hook.

Complex Machines

So far, our state machines have been relatively simple. They have been one level of states and one single system of states. At some point, it is likely you'll need something more complex. It is highly recommended you read the XState docs for a deep dive on more complex machines, but two common ones will be covered here: Hierarchical and Parallel machines.

Hierarchical Machines

As you're developing a machine, you may realize that some of your enumerated states are really child states of a parent state. Let's extend our light bulb example further.

Our light bulb has a new feature, it can shine at three different levels of brightness: low, normal, and high. These states are child states (or "substates") of our lit state. Let's write a hierarchical state machine to convey this.

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      // Child states start here
      initial: 'normal',
      states: {
        low: {
          on: {
            INCREASE_BRIGHTNESS: 'normal',
          },
        },
        normal: {
          on: {
            DECREASE_BRIGHTNESS: 'low',
            INCREASE_BRIGHTNESS: 'high',
          },
        },
        high: {
          on: {
            DECREASE_BRIGHTNESS: 'normal',
          },
        },
      },
      // Child states end here
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken',
      },
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken',
      },
    },
    broken: {
      type: 'final',
    },
  },
})

To create a hierarchical machine, we essentially create the same structure as a normal state machine, but nest it in the parent state. We add an initial state and enumerate the child states under the states property.

Now if our light bulb is in the lit state, it will initially start in the { lit: 'normal' } state. We can send events to our machine to change the brightness.

lightBulbMachine({ lit: 'normal' }, 'INCREASE_BRIGHTNESS').value // { lit: 'high' }
lightBulbMachine({ lit: 'high' }, 'DECREASE_BRIGHTNESS').value // { lit: 'normal' }

Hierarchical states are an excellent way to model states that should only exist as a child state of another state. This allows us to avoid a lot of conditional logic since our machine won't respond to events unless it is in the correct state.

Parallel Machines

Occasionally, you'll find your model requires a machine be in multiple states simultaneously. This is what a parallel machine is for. A parallel machine allows a machine to be in multiple states simultaneously and independently. Let's extend our light bulb further and turn it into one for the dance floor. Lights on the dance floor flash in various patterns, and they can oscillate in different ways. We'll focus on just those two parallel states in our example (which will also include a hierarchical state since these can only occur in the lit state).

import { Machine } from 'xstate'

const lightBulbMachine = Machine({
  id: 'lightBulb',
  initial: 'unlit',
  states: {
    lit: {
      // parallel child states start here
      type: 'parallel', // no initial state, requires `type: 'parallel'` be set
      states: {
        // 1st parallel state
        pattern: {
          // We can easily have hierarchical child states inside our parent parallel state
          initial: 'steady',
          states: {
            steady: {
              on: {
                PULSE: 'pulsing',
                FLASH: 'flashing',
              },
            },
            pulsing: {
              on: {
                STEADY: 'steady',
                FLASH: 'flashing',
              },
            },
            flashing: {
              on: {
                STEADY: 'steady',
                PULSE: 'pulsing',
              },
            },
          },
        },
        // 2nd parallel state
        movement: {
          initial: 'stationary',
          states: {
            stationary: {
              on: { OSCILLATE: 'oscillating' },
            },
            oscillating: {
              on: { STOP: 'stationary' },
            },
          },
        },
      },
      // parallel child states end here
      on: {
        TURN_OFF: 'unlit',
        BREAK: 'broken',
      },
    },
    unlit: {
      on: {
        TURN_ON: 'lit',
        BREAK: 'broken',
      },
    },
    broken: {
      type: 'final',
    },
  },
})

We added quite a bit of complexity here, but it's just the combination of parallel and hierarchical states that make it happen. Let's break it down.

Under the lit state, we add a couple parallel states: one for the light pattern and one for the movement of the bulb. The bulb is in both states simultaneously and independently. We can send events that affect one without affecting the other.

Next, inside of each parallel state, we've added a hierarchical state chart to govern the states held within each parallel state. This is precisely what we've seen thus far. We have a subchart that controls the pattern states, and one that governs the movement states.

If we were to examine the value returned by the lit state, it would initially look like this:

lightBulbMachine.transition('unlit', 'TURN_ON')
// {
//   value: {
//     lit: {
//       pattern: 'steady',
//       movement: 'stationary',
//     }
//   }
// }

Notice that the lit state is an object with the states of all our parallel states contained within.

Visualizing State Machines

XState has a very handy visualizer at xstate.js.org/viz. You can save machines as gists from the visualizer as well.

How to Approach Creating a State Machine

Here is a general heuristic of how to approach creating a state machine.

Enumerate the states of your program
Enumerate the transitions between those states
Examine if any of the states can only exist as a substate of another state. If so, know you can use a hierarchical state machine.
Examine if any of the states can exist simultaneously and independently. If so, know you can use a parallel state machine.
Create objects for all of your states
Add the transitions to the on property of those states
Combine these into the states property of your machine
Add the initial state to your machine
Add an id to your machine
Start the service of your machine through either interpret or useMachine depending on your situation.
Profit.

Testing

Tests can be written just as any other test would be written regarding UI interactions to verify expected behavior.

There is also the @xstate/test library that can automatically generate all possible branches of your state machine. More will be added to this section in the future.

Resources

XState Docs
XState Viz
Introduction to State Machines and XState on egghead.io (if you have an egghead account. Access for Webflow engineers will come soon.)

Managing Cyclomatic Complexity

Mon, 02 Mar 2020 00:00:00 GMT

I'm not sure when I first learned about "cyclomatic complexity". It's such an academic term that you can practically smell a classroom or library when you read or hear it. If I had understood the concept earlier in my career, I don't think I would have given it much thought.

"I've got buttons to put on these web pages. Who cares about cycles? What the heck is a cycle anyways?!" a younger, more naive Kyle may have exclaimed.

I don't think that way anymore. In fact, I have been thinking about cyclomatic complexity almost daily for a little over six months. Over this time, I've developed some thoughts and ideas on the topic that I want to share with you in this post. By the end, I hope I will have convinced you of the importance of cyclomatic complexity in writing maintainable applications.

To get started, I have a simple question for you. How many logical paths are there through the following function? I assure you, it's not a trick question.

function double(num) {
  return num * 2
}

I hope you came up with the answer one. There is only one logical path through the function. We give it an input, we get an output.

What if we add a conditional inside of the function? Let's use a well known function in mathematics for this example. How many logical paths are there in this function?

function collatz(num) {
  if (num % 2 === 0) {
    return num / 2
  }

  return 3 * num + 1
}

Again, not a trick question, the answer is two. There are two paths through this function. Either a number is an even number and we return the first branch, or a number is odd and we return the second branch.

Another way to describe this function is that it takes 2 cycles through it to touch every logical branch of the program. These cycles are how we get the term "cyclomatic". The more cycles, the greater the complexity.

Let's take a look at a far more complex example. This is known as the "Gilded Rose" kata <Marker content="A "kata" is a martial arts training exercise. It has been co-opted to describe coding exercises. It's probably why we can't get rid of the term "coding ninjas."" />. You can Google it and find solutions to it all over <Marker content="And I recommend you do. I think it would be a good use of your time" />. I was once given a take home exercise that was basically this kata adjusted for items the company worked with. It looks like this:

class Item {
  constructor(name, sellIn, quality) {
    this.name = name
    this.sellIn = sellIn
    this.quality = quality
  }
}

class GildedRose {
  constructor() {
    this.items = []
  }

  addItem(item) {
    this.items.push(item)
  }

  updateQuality() {
    const { items } = this

    for (var i = 0; i < items.length; i++) {
      if (
        'Aged Brie' != items[i].name &&
        'Backstage passes to a TAFKAL80ETC concert' != items[i].name
      ) {
        if (items[i].quality > 0) {
          if ('Sulfuras, Hand of Ragnaros' != items[i].name) {
            items[i].quality = items[i].quality - 1
          }
        }
      } else {
        if (items[i].quality < 50) {
          items[i].quality = items[i].quality + 1
          if ('Aged Brie' == items[i].name) {
            if (items[i].sellIn < 6) {
              items[i].quality = items[i].quality + 1
            }
          }
          if ('Aged Brie' == items[i].name) {
            if (items[i].sellIn < 11) {
              items[i].quality = items[i].quality + 1
            }
          }
          if ('Backstage passes to a TAFKAL80ETC concert' == items[i].name) {
            if (items[i].sellIn < 11) {
              if (items[i].quality < 50) {
                items[i].quality = items[i].quality + 1
              }
            }
            if (items[i].sellIn < 6) {
              if (items[i].quality < 50) {
                items[i].quality = items[i].quality + 1
              }
            }
          }
        }
      }
      if ('Sulfuras, Hand of Ragnaros' != items[i].name) {
        items[i].sellIn = items[i].sellIn - 1
      }
      if (items[i].sellIn < 0) {
        if ('Aged Brie' != items[i].name) {
          if ('Backstage passes to a TAFKAL80ETC concert' != items[i].name) {
            if (items[i].quality > 0) {
              if ('Sulfuras, Hand of Ragnaros' != items[i].name) {
                items[i].quality = items[i].quality - 1
              }
            }
          } else {
            items[i].quality = items[i].quality - items[i].quality
          }
        } else {
          if (items[i].quality < 50) {
            items[i].quality = items[i].quality + 1
          }
          if ('Aged Brie' == items[i].name && items[i].sellIn <= 0)
            items[i].quality = 0
        }
      }
      if ('Sulfuras, Hand of Ragnaros' != items[i].name)
        if (items[i].quality > 50) items[i].quality = 50
    }
    return items
  }
}

const rose = new GildedRose()

rose.addItem(new Item('+5 Dexterity Vest', 10, 20))
rose.addItem(new Item('Aged Brie', 2, 0))
rose.addItem(new Item('Elixir of the Mongoose', 5, 7))
rose.addItem(new Item('Sulfuras, Hand of Ragnaros', 0, 80))
rose.addItem(new Item('Backstage passes to a TAFKAL80ETC concert', 15, 20))
rose.addItem(new Item('Conjured Mana Cake', 3, 6))

rose.updateQuality()

Want to hazard a guess how many cycles the updateQuality method has?

I'll wait.

Got it yet?

It's 25! It takes 25 cycles to cover every branch of this function.

For the record, it wasn't my amazing brain <Marker content="It's not that amazing." /> that could read that code and know the answer was 25. I used JSHint in the browser to check it out. Another good option would be to use the complexity rule from ESLint.

I hope it just dawned on you that this also means you have to write 25 tests to have confident coverage regarding updateQuality. A method this complex demands good tests.

Now, I don't plan to solve this problem for you in the rest of this post. In fact, I recommend watching this video from Sandi Metz that covers the subject. Rather, I want to explore how I think about handling complexity in situations like these.

How Complexity Exists in A Program

Before we learn how to deal with complexity, we must first learn some truths about complexity. I'm going to work through a bit of a metaphor here. I'm not sure it will land with everyone, but I hope it helps some of you understand "complexity" in a new way.

First, I want to be clear, that I am not describing subjective complexity. This is not about what programming style you prefer, or your preference for for loops instead of forEach. This is about an objective measurement of complexity in an application. <Marker content="The formula for calculating cyclomatic complexity is <code>E - N + 2P</code>, where <code>E</code> represents the edges of a control flow graph, <code>N</code> the nodes of the graph, and <code>P</code> the number of connected components of the graph. I don't want people to fixate on the formula in this conversation, so I encourage you to Google it and read more on your own. There is plenty of material out there." />

Every program has a minimum level of overall complexity that is required to exist. That is, without removing features from the program, it will have an aggregate complexity score of X, where X represents the minimum complexity required to accomplish that program. Let's imagine a program, as a collection of nodes.

Now, we cannot reduce X without changing the observable behavior of the program. If our program has even X - 1 nodes, it will not be the same program anymore. However, we are allowed to group the nodes of X (these would typically be functions, classes, modules, etc.). How we group them matters.

We might group them in two big groups where the average complexity of our groups is very high.

We also might group our nodes in many small groups, where the average complexity of those groups is very low.

Regardless of how we group the nodes of our program, the overall number of nodes, and therefore the overall complexity of the system, remains as the value X. What does change is the average complexity per group. Understanding this is the starting point to managing complexity more purposefully in our programs.

In General, Aim for Low Complexity Per Group

The first thing we can recognize when managing complexity is that, in general, code with low complexity is easier to understand than code with high complexity. The first few examples I shared, the double and collatz functions are quite easy to understand. The Gilded Rose, however, is an almost impenetrable bit of code. I imagine some of the functions in your codebases look even worse (admit it).

Functions with a low score are not only easy to understand, but are easier to test. Sometimes, they are so easy to understand you may not bother with a test at all (not that I advocate for that, but I understand the impulse). These low complexity scores also mean that whenever we need to make an adjustment to one of the groups, it is relatively easy to do so. Update a test, make some changes, and you're good to go. This gives us a lot of confidence in our programs.

But I say "in general" on purpose. There are a few scenarios where it may make sense to allow a high level of complexity to exist in a particular group.

The Exception: Encapsulated Complexity

Since we cannot change the overall complexity of a program, we need to be aware of how we manage complexity in "groups" of our program. There will come times where it may make sense to allow a particular "group" a high level of complexity.

So what makes a good candidate for making an exception?

I think the most common reason to allow a part of a program to have a high level of complexity is when there is a single conditional that has many results. Most often, this is a switch case or something similar. The structure of that part of the program might look like this:

The reason this makes sense is that the condition and mapping to appropriate results has to happen somewhere in our program. It might as well be in an isolated and encapsulated place. That place should often be a well named (and tested) function that only handles a single part of our program.

The encapsulation of the complexity is key here. Remember, we cannot change X (the overall complexity) and have the same program. We know we must have this complexity somewhere, but by grouping it like this, we reduce exposure of the internal complexity to rest of our program. We essentially make a contract with ourselves and anyone who may work on this code in the future, "We have contained the complexity, do not let it leak out."

The most common example I can think of in modern web development would be a state reducer, a la Redux or the useReducer hook. For those who are not sure what a state reducer is, a state reducer is a function that accepts a state and an action argument and returns the nextState. The actions passed to this reducer might be of many different types, and each must be accounted for. This results in a function that has a single condition (what type of action is this?), but many possible results. Breaking this apart might only make the program more difficult to use or reason about. Capturing it in a single function makes the most sense, even if the complexity score might be very high.

An Example From My Work

A few months ago, I came across a bit of code that had a high level of complexity for a single group. I'm going to share the change I made, and hopefully you'll agree that it was the right way to manage the complexity.

The code that follows is adapted from the Webflow codebase. Webflow's architecture involves a lot of "nodes" and these nodes contain various types of information that need to be validated, cleaned up, and transformed. At one particular point during those transformations, I found code that looks somewhat like this: <Marker content="This is not the exact code. It is similar to what it was. It no longer exists in the Webflow codebase so there's no need to snoop around the clientside bundle for it." />

// This code uses ImmutableJS Maps, not standard JS Maps
// hence the method `update()` and more.
nodes.update('dynamicData', Immutable.Map(), dynamicData => {
  const bindableData = dynamicData
    .get('bindable', Immutable.Map())
    .update(cleanUpBindings(bindingDep1, bindingDep2))

  if (bindableData.size > 0) {
    dynamicData = dynamicData.set('bindable', bindableData)
  } else {
    const originalBindings = dynamicData.get('bindable')

    dynamicData =
      originalBindings && originalBindings.size === 0
        ? dynamicData
        : dynamicData.delete('bindable')
  }

  const conditionalData = dynamicData
    .get('conditions', Immutable.Map())
    .update(cleanUpConditions(conditionalDep1, conditionalDep2))

  dynamicData =
    conditionalData.size > 0
      ? dynamicData.set('conditions', conditionalData)
      : dynamicData.delete('conditions')

  const filterableData = dynamicData
    .get('filterable', Immutable.Map())
    .update(cleanUpFilters(filterDep1, filterDep2))

  if (filterableData.size > 0) {
    dynamicData = dynamicData.set('filterable', filterableData)
  } else {
    const originalFilter = dynamicData.get('filterable')
    dynamicData =
      originalFilter && originalFilter.size === 0
        ? dynamicData
        : dynamicData.delete('filterable')
  }

  const sortableData = List()
    .concat(dynamicData.get('sortable', List()))
    .update(cleanUpSort(sortableDep1, sortableDep2))

  if (sortableData.size > 0) {
    dynamicData = dynamicData.set('sortable', sortableData)
  } else {
    dynamicData = dynamicData.delete('sortable')
  }

  return dynamicData
})

There's a lot going on in this function, and I don't expect it to make a ton of sense right away. Let me try and break it down a little bit. This function receives a piece of data, dynamicData, and mutates it as necessary based on which conditionals are met along the way. That's pretty standard for programming.

The complexity score isn't terribly high, it's only a 7, but the code is still more difficult to reason about than necessary and has too many responsibilities. We can make this better. With some changes, this bit of code will be easier to understand and update in the future, while also reducing the average complexity per group.

First, we need to identify what the groups are in this code. It turns out there are four distinct groups in this bit of code: one that updates the bindings, one that updates the conditions, one that updates the filters, and finally one that updates the sorts. Here they are as separate code blocks:

// Bindings
const bindableData = dynamicData
  .get('bindable', Immutable.Map())
  .update(cleanUpBindings(bindingDep1, bindingDep2))

if (bindableData.size > 0) {
  dynamicData = dynamicData.set('bindable', bindableData)
} else {
  const originalBindings = dynamicData.get('bindable')

  dynamicData =
    originalBindings && originalBindings.size === 0
      ? dynamicData
      : dynamicData.delete('bindable')
}

// Conditions
const conditionalData = dynamicData
  .get('conditions', Immutable.Map())
  .update(cleanUpConditions(conditionalDep1, conditionalDep2))

dynamicData =
  conditionalData.size > 0
    ? dynamicData.set('conditions', conditionalData)
    : dynamicData.delete('conditions')

// Filters
const filterableData = dynamicData
  .get('filterable', Immutable.Map())
  .update(cleanUpFilters(filterableDep1, filterableDep2))

if (filterableData.size > 0) {
  dynamicData = dynamicData.set('filterable', filterableData)
} else {
  const originalFilter = dynamicData.get('filterable')

  dynamicData =
    originalFilter && originalFilter.size === 0
      ? dynamicData
      : dynamicData.delete('filterable')
}

// Sorts
const sortableData = List()
  .concat(dynamicData.get('sortable', Immutable.List()))
  .update(cleanUpSort(sortableDep1, sortableDep2))

if (sortableData.size > 0) {
  dynamicData = dynamicData.set('sortable', sortableData)
} else {
  dynamicData = dynamicData.delete('sortable')
}

If we pay attention, we can see that each of these groups takes dynamicData and conditionally updates it. We can turn each of these groups into their own function that receives dynamicData as an argument, and returns the transformed data. We need to gather all the other data necessary for each function, but that isn't too hard. Those functions look like this:

const updateBindings =
  ({ bindingDep1, bindingDep2 }) =>
  dynamicData => {
    const bindableData = dynamicData
      .get('bindable', Immutable.Map())
      .update(cleanUpBindings(bindingDep1, bindingDep2))

    if (bindableData.size > 0) {
      return dynamicData.set('bindable', bindableData)
    } else {
      const originalData = dynamicData.get('bindable')

      return originalData && originalData.size === 0
        ? dynamicData
        : dynamicData.delete('bindable')
    }
  }

const updateConditions =
  ({ conditionalDep1, conditionalDep2 }) =>
  dynamicData => {
    const conditionalData = dynamicData
      .get('conditions', Immutable.Map())
      .update(cleanUpConditions(conditionalDep1, conditionalDep2))

    return conditionalData.size > 0
      ? dynamicData.set('conditions', conditionalData)
      : dynamicData.delete('conditions')
  }

const updateFilters =
  ({ filterableDep1, filterableDep2 }) =>
  dynamicData => {
    const filterableData = dynamicData
      .get('filterable', Immutable.Map())
      .update(cleanUpFilters(filterableDep1, filterableDep2))

    if (filterableData.length) {
      return dynamicData.set('filterable', filterableData)
    } else {
      const originalData = dynamicData.get('filterable')

      return originalData && originalData.size === 0
        ? dynamicData
        : dynamicData.delete('filterable')
    }
  }

const updateSorts =
  ({ sortableDep1, sortableDep2 }) =>
  dynamicData => {
    const sortableData = dynamicData
      .get('sortable')
      .update(cleanUpSort(sortableDep1, sortableDep2))

    return sortableData.size > 0
      ? dynamicData.set('sortable', sortableData)
      : dynamicData.delete('sortable')
  }

Now each function is an isolated bit of complexity. You might be wondering why each of these functions is a curried function (You can learn more about curried functions here). Currying these functions allows me to do two things.

First, it allows me to supply all the extra arguments necessary to do the computation ahead of time. These are held in closure for the next function accepting dynamicData as an argument.

Second, it allows me to create a composition of these functions. Because the returned function from each updater here has the same signature (and returns the same signature), I can compose them together. I've written about composition here and I encourage you to read that post. I will actually use the pipe function for this example, so that we maintain left-to-right, top-to-bottom data flow through our composition. Our new update looks like this:

nodes.update('dynamicData', Immutable.Map(), dynamicData => {
  // These aren't the real arguments, just useful for the examples
  return pipe(
    updateBindings({
      bindingDep1,
      bindingDep2,
    }),
    updateConditions({
      conditionalDep1,
      conditionalDep2,
    }),
    updateFilters({
      filterableDep1,
      filterableDep2,
    }),
    updateSorts({
      sortableDep1,
      sortableDep2,
    }),
  )(dynamicData)
})

How much simpler is that bit of code? It even reads more like English because of how we've named our functions. I need to make an update to the data. It will be piped through these four functions, each of which has a fairly low level of complexity, and return the result.

We have not changed the overall complexity. It remained constant as it must, but we have changed the average complexity per function to 1.5. That is significantly lower than a complexity score of 7. I'm biased because I wrote the code, but I think this is objectively better to work with as well. What do you think?

Takeaway

Paying attention to cyclomatic complexity can be a game changer in your programming career. It can take you from being the kind of person that writes code that works (which is awesome), to writing code that is easier for you and others to make changes to (which is awesomer). Recognizing complexity and developing strategies for managing it are important for creating maintainable and reasonable programs.

Remember, we can't change the overall complexity of a program without changing what the program is. <Marker content="Sometimes removing code <em>is</em> the answer to complexity; just know it won't be the same program." /> Try to keep average complexity per group low. Many functions, classes, modules with low complexity is often (but not always) easier to manage. Encapsulate high levels of complexity where necessary as an exception.

Recursive React Components

Thu, 20 Feb 2020 00:00:00 GMT

import BetterStyledTree from './_BetterStyledTree' import StyledTree from './_StyledTree' import UnstyledTree from './_UnstyledTree'

It can be easy to forget that React components are just functions. They receive inputs, they give us an output, and they might trigger some side effects in the process. Because they are simply functions, we can use patterns with them that we use with other functions. Like recursion.

What is recursion?

Recursion is the pattern of a function calling itself. A very common example of a recursive function is calculating a factorial of a number. <Marker content="A factorial is a positive number multiplied by every number between itself and 1. So <code>6!</code> is <code>6 * 5 * 4 * 3 * 2 * 1</code>." /> Consider the following function:

function factorial(number) {
  // This is the base case. I'll explain this shortly
  if (number <= 1) {
    return 1
  }

  return number * factorial(number - 1)
}

Our function receives a number to factorialize, but rather than use an iterative loop, such as a for or while loop, we take advantage of the fact that we can calculate the final result by utilizing the results of calling factorial on smaller numbers. That is, we recognize the pattern:

factorial(4) === 4 * factorial(3)
factorial(3) === 3 * factorial(2)
factorial(2) === 2 * factorial(1)
factorial(1) === 1

If we take this list of equal values and reverse the order of the functions we see called, we can derive the function call stack of factorial(4).

factorial(4) leads to factorial(3) getting called, which leads to factorial(2) getting called, which leads to factorial(1) getting called, which returns the value of 1, which is fed back into factorial(2) which returns the value of 2, which is fed back into factorial(3) which returns the value of 6, which is fed back into factorial(4), which returns the value of 24.

Easy, right?! <Marker content="It is. It just takes practice." />

Base Cases

Consider for a moment if we commented out the following bit of code from our factorial function:

function factorial(number) {
  // if (number <= 1) {
  //   return 1
  // }

  return number * factorial(number - 1)
}

What would happen? Well, we'd never get an answer. We'd never get a call to factorial that returned a value. We would continue to add factorial calls to the call stack until we exceeded the maximum number of calls allowed on the stack. We would have a "stack overflow" (and yes, that is where the name comes from).

Every recursive function needs to have a base case that ends the recursion. In the case of factorial, it's when we have a number less than or equal to 1 passed in for number. This base case ends the chain of recursive calls, and starts the process of returning values up the stack to get the final result.

Recursion applied to components

Now that we understand recursive functions, let's apply this knowledge to components. A recursive component is a component that renders itself as one of its children. Let me give you an example.

Consider a directory of folders. It might look something like this:

src
  |- css
  |- js
    |- utils
    |- components
public
  |- images

How can we represent this as data to pass to a recursive component? Pretty simply actually, we can use a tree. A tree is a graph data structure where each child node has a single parent. For example, the HTML structure of a website is a tree. No element on a page has more than one parent (all they way up to the <html> tag). We can make a tree structure for our folders like this:

const folders = [
  { name: 'src', children: [
    { name: 'css', children: [] }
    { name: 'js', children: [
      { name: 'utils', children: [] },
      { name: 'components', children: [] }
    ]}
  ]},
  { name: 'public', children: [
    { name: 'images', children: [] }
  ]}
]

We have a top level of folders, and folders nested up those are on a children property. Now that we have our data, how do we make use of it in a recursive component?

Similar to how we recognized that factorial can be solved by using the result of factorial called on smaller numbers, we can recognize that a tree is the result of combining smaller trees. <Marker content="One might think of it as a fractal." /> Understanding this, we can make a Tree component that will call itself to render smaller Trees.

function Tree({ items }) {
  // our base case, if we have no items, render nothing.
  if (!items || !items.length) {
    return null
  }

  return items.map(item => (
    <React.Fragment key={item.name}>
      <div>{item.name}</div>
      {/* And here's the recursion! */}
      <Tree items={item.children} />
    </React.Fragment>
  ))
}

If we were to pass the folder data we created earlier to the component, that will look like this:

Wait! That's not what we want to represent. That's just a flat list. What happened?

Well, we forgot to style it. Let's track the depth of the folder with each level and update the padding-left CSS property accordingly.

// We add a `depth` property with a default value of 0
// That way we don't have to pass it to the top level of the tree
function Tree({ items, depth = 0 }) {
  if (!items || !items.length) {
    return null
  }

  return items.map(item => (
    <React.Fragment key={item.name}>
      {/* Multiply the depth by a constant to create consistent spacing */}
      <div style={{ paddingLeft: depth * 15 }}>{item.name}</div>
      <Tree items={item.children} depth={depth + 1} />
    </React.Fragment>
  ))
}

Notice how simple it is to increment the depth prop with recursion. Each layer deeper we go in the tree, the value is increased by 1. Let's take a look at our recursive component now:

That looks a bit more like the folder structure we all know and love. Let's add a few more touches to make it a bit nicer.

That's starting to look like something you could use in a real UI. A little interactivity, displaying of files, and we'd really have something.

Conclusion

I encourage you to get comfortable with recursion. It doesn't have to be scary. Often, it's the simplest and most elegant solution to a problem. Who knows, it might even help you pass a job interview one day. Don't be afraid to experiment with it in your React work, you may discover some interesting UIs because of it.

Enumerate, Don't Booleanate

Sat, 25 Jan 2020 00:00:00 GMT

I want to teach you something that's taken me a few years to learn and a lot of trial and error. I could teach it to you in a couple tweets, but I want to take you on a bit of a journey instead. I want to show a problem, and show you different ways I would attempt to solve it as I go from "naive Kyle" (who am I kidding, I'm probably still naive Kyle) to "knows better Kyle".

Let's imagine me just a few years back. I show up to work one morning and my project manager has a request for me.

"Kyle, our customers want donuts and they want them fast. They want a simple form that'll deliver them directly to their door. We already have their address. We only need them to select how many they want. Can you build this?"

"Of course I can!"

I would head off to my work station and start building a form just as fast as I could and probably come up with something like this:

import React from 'react'

export default function DonutForm() {
  const [quantity, setQuantity] = React.useState(0)
  const [isSuccess, setSuccess] = React.useState(false)

  const handleSubmit = e => {
    e.preventDefault()

    sendOrder({ quantity }).then(response => {
      console.log(response)
      setSuccess(true)
    })
  }

  const handleChange = e => {
    setQuantity(Number(e.target.value))
  }

  const reset = () => {
    setQuantity(0)
    setSuccess(false)
  }

  return (
    <div className="donut_form-wrap">
      {isSuccess ? (
        <>
          <div>Donuts are on their way!</div>
          <button type="button" onClick={reset}>
            Reset
          </button>
        </>
      ) : (
        <form onSubmit={handleSubmit}>
          <h4>Get Yummy Donuts!</h4>

          <div>
            <label htmlFor="donutFormQuantity">Quantity</label>
            <input
              id="donutFormQuantity"
              min={0}
              name="donutFormQuantity"
              onChange={handleChange}
              step={1}
              type="number"
              value={quantity}
            />
          </div>

          <button type="submit">Order</button>
        </form>
      )}
    </div>
  )
}

function inflect(singular, plural, value) {
  return value === 1 ? singular : plural
}

// Pretend this is an API call that orders the donuts
function sendOrder({ quantity }) {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve(`Ordered ${quantity} ${inflect('donut', 'donuts', quantity)}!`)
    }, 2000)
  })
}

You can see a running example of this code at: https://codesandbox.io/s/hopeful-ritchie-lk7cs.

Disregarding the anachronism that React existed when I started my career (let alone Hooks), this form is pretty decent. Naive Kyle even managed to think of isSuccess, a bit of state that will tell the user that they successfully ordered their donuts. However, as often happens with projects, the scope wasn't fully defined or something important was forgotten. The project manager comes back to me,

"Kyle, that's great, but you forgot that sometimes the API is going to fail. As scary as it might be to tell people who want donuts that their donuts aren't on the way just yet, we gotta do it. We had one customer, Dinah, who tried to order some donuts, but didn't know that the order had failed. She just sat there, waiting for them to be delivered, until she shriveled up and died of donut starvation. Tragic, I know. We can't lose customers like that. Can you handle errors for us?"

"Woah! Of course, I can!"

So back to the code we go to add some error handling. What's the first thing we do? Well, we add another bit of state to the component, of course:

const [quantity, setQuantity] = React.useState(0)
const [isSuccess, setSuccess] = React.useState(false)
const [error, setError] = React.useState(null)
//...

Ok, we've added a way to track the error. Great, now we need a way to set it:

//...
const handleSubmit = e => {
  e.preventDefault()

  if (error) {
    setError(null)
  }

  sendOrder({ quantity })
    .then(response => {
      console.log(response)
      setSuccess(true)
    })
    .catch(err => {
      setError(err)
      setSuccess(false) // just to be sure!
    })
}
//...

Great, we're setting the error when the sendOrder promise rejects and we were thoughtful enough to clear any existing error when we try to submit the form. Just one last thing we have to add:

error ? <div className="error_wrap">{error}</div> : null

Perfect, now we display the error to the user and we only had to add one bit of state (that even though it's not technically a boolean, we actually coerce into a boolean twice). Slightly less naive Kyle is proud. You can see a running example of this code at: https://codesandbox.io/s/vibrant-kirch-w67vx

Slightly less naive Kyle's project manager sees our progress and comes back with, "Kyle, that's amazing! But you forgot that the API call takes some actual time. Because you forgot to disable the submit button while an order is pending, Methuselah over there was so impatient for some donuts that he smashed the submit button 18 times before the order went through. That's right! 18 baker's dozens showed up at his door! Being the donut fiend he is, Methuselah ate all of them. He's in a coma now, poor guy. May never wake up from his body handling all those donuts. We've lost one of our best customers. You need to fix this."

"Oh damn! I'll fix it right away"

So back to the code we go to disable the submit button while an order is pending. Let's add another bit of state to track whether we are submitting or not.

const [quantity, setQuantity] = React.useState(0)
const [isSuccess, setSuccess] = React.useState(false)
const [error, setError] = React.useState(null)
const [isSubmitting, setSubmitting] = React.useState(false)

Alright, so we need to couple this to the submit button, like so:

<button disabled={isSubmitting} type="submit">
  Submit
</button>

And lastly, we need to update when we are or aren't submitting:

const handleSubmit = e => {
  e.preventDefault()
  setSubmitting(true)

  if (error) {
    setError(null)
  }

  sendOrder({ quantity })
    .then(response => {
      console.log(response)
      setSuccess(true)
      setSubmitting(false) // Do we really need this here? We'll be on the success screen. ¯\_(ツ)_/¯
    })
    .catch(err => {
      setError(err)
      setSuccess(false) // just to be sure!
      setSubmitting(false)
    })
}

Awesome. Our form now tracks when it's submitting and prevents the user from ordering more donuts than intended. Huzzah! It works. You can see a running example of this code at: https://codesandbox.io/s/lucid-noyce-832f0.

But, at this point, we need to ask ourselves a question: would you really want to be the next developer to work on this form?

I don't think I'd want to be. The code is convoluted. We're setting states left and right. We even have some setters in places where we aren't even sure if we need them. Why? Because we're "good" programmers and we're trying to avoid a problem that we haven't even give a name to yet. We're trying to avoid getting our component into impossible states.

It should be impossible to order donuts while we're ordering donuts already. It should be impossible that we show an error while we are showing the user that they have been successful. We've done so by using a bunch of booleans (and treated other values like booleans) in order to achieve this, but our component has undergone a bit of boolean explosion.

Boolean explosion is when, through the use of booleans, we have introduced more states than are actually possible in our program. For every boolean we add to a program, we are adding 2^n states (where n is the number of booleans). Let's just iterate on that a few times.

1 boolean === 2 states
2 booleans === 4 states
3 booleans === 8 states
4 booleans === 16 states
5 booleans === 32 states...

You can see that the number of states starts to grow very quickly. But do you actually have that many states in your program? Our form currently uses three booleans, but does it really have eight states? No, most of those states are impossible. For example, we cannot be in a state where isSuccess, error, and isSubmitting all coerce to true. It's impossible.

So why do we even give our programs the opportunity to be in states that are impossible?

Because we don't enumerate.

Enumeration, the act of identifying a set of things one by one, is simple, but effective way to make our programs a bit more robust. Slightly more experienced Kyle can show you how.

Given the same requirements, slightly more experienced Kyle realizes that there are really only a handful full of states that our form can ever be in. Let's enumerate those:

const DONUT_FORM_STATES = {
  idle: 'idle',
  submitting: 'submitting',
  success: 'success',
  failure: 'failure',
}

Turns out, our form can only be in 4 states, not the 8 possible states suggested by our previous use of booleans. Now, let's track this state in our component.

function DonutForm() {
  const [quantity, setQuantity] = React.useState(0)
  const [current, setCurrent] = React.useState(DONUT_FORM_STATES.idle)
  //...
}

The next thing slightly more experienced Kyle realizes is that we can only transition to certain states from particular other states. For example, we can never go straight from idle to success. We need to be in submitting to go to success. So not only have we enumerated the possible states, but we need to enumerate the possible transitions between those states, too.

const DONUT_FORM_TRANSITIONS = {
  [DONUT_FORM_STATES.idle]: {
    SUBMIT: DONUT_FORM_STATES.submitting,
  },
  [DONUT_FORM_STATES.submitting]: {
    SUCCEED: DONUT_FORM_STATES.success,
    FAIL: DONUT_FORM_STATES.failure,
  },
  [DONUT_FORM_STATES.success]: {
    RESET: DONUT_FORM_STATES.idle,
  },
  [DONUT_FORM_STATES.failure]: {
    SUBMIT: DONUT_FORM_STATES.submitting,
  },
}

At first this might seem a bit confusing, but don't worry. We are using computed property names to guarantee the values in our states enum are the keys of our transitions enum. We also want to ensure that our next state target is one of enumerated states. Lastly, we've added objects with "events" (the uppercased key) to each state which strictly defines what events a state will even respond to. That means we can create a function that guarantees we correctly get the next state, given the current state and an event. Like so:

const transition = (state, event) => {
  const nextState = DONUT_FORM_TRANSITIONS[state][event]
  return nextState ? nextState : state
}

We need to add one last thing to make all these pieces come into place. We need a way of sending events to our enumerated transitions and updating to the next state. We need to define a send function inside our component that makes use of our transition function, and updates the current state.

const send = event => {
  setCurrent(currentState => transition(currentState, event))
}

With all of this in place, we're ready to make the most robust donut form you've seen (so far in this blog post). We're going to add the important parts to the functions and markup inside this component.

//...
const handleSubmit = e => {
  e.preventDefault()

  send('SUBMIT')

  sendOrder({ quantity })
    .then(response => {
      console.log(response)
      send('SUCCEED')
    })
    .catch(err => {
      send('FAIL')
    })
}
//...
const reset = () => {
  send('RESET')
}
//..
return (
  <div className="donut_form-wrap">
    {current === DONUT_FORM_STATES.success ? (
      <>
        <div>Donuts are on their way!</div>
        <button type="button" onClick={reset}>
          Reset
        </button>
      </>
    ) : (
      <form onSubmit={handleSubmit}>
        <h4>Get Yummy Donuts!</h4>

        {current === DONUT_FORM_STATES.failure ? (
          <div className="error_wrap">Failed to order donuts</div>
        ) : null}

        <div>
          <label htmlFor="donutFormQuantity">Quantity</label>
          <input
            id="donutFormQuantity"
            min={0}
            name="donutFormQuantity"
            onChange={handleChange}
            step={1}
            type="number"
            value={quantity}
          />
        </div>

        <button
          disabled={current === DONUT_FORM_STATES.submitting}
          type="submit"
        >
          Order
        </button>
      </form>
    )}
  </div>
)
//...

You can see a running example of this code at: https://codesandbox.io/s/vibrant-jackson-vy7qi.

Notice how simple it is to send events and trust that our component is in the correct state. We also have far fewer checks and guards than we did before. By eliminating the existence of impossible states, we've created a program we can have a lot of confidence in.

But, at this point, we need to ask ourselves a question: would you really want to be the next developer to work on this form?

If I'm honest, I'd be alright if this was where we stopped, but I do see some maintenance challenges. While we've made a huge step forward by enumerating, not booleanating, we have two enums to keep in sync, and had to create several functions that could probably be gathered together into a nice library with a friendly API.

What we've created through the enums and a few functions is create an ad hoc finite state machine. We have all the possible states of the system, all the possible transitions, and a way to safely transition from state to state. These are all the components of a good state machine library. So for one final step in this article, let's implement this same form with a popular state machine library, XState.

With XState, knows-even-a-little-bit-better Kyle can create a state chart that combines our enums together, making it easier to keep them in sync. Let's start by making a new variable we will call chart. chart will only have 3 properties, id, initial and states.

const chart = {
  id: 'donutForm',
  initial: '',
  states: {},
}

initial is the initial state of our machine. In our case, our form starts in the initial state of idle.

const chart = {
  id: 'donutForm',
  initial: 'idle',
  states: {},
}

Next, the states object will be an enum that combines our previous states and transitions enums together. Let's start by adding just our individual states to this object.

const chart = {
  id: 'donutForm',
  initial: 'idle',
  states: {
    idle: {},
    submitting: {},
    success: {},
    failure: {},
  },
}

Next, we're going to add our events and transitions on the object values of their corresponding state, underneath the on property. This way our code reads "When idle, on the SUBMIT event, transition to submitting".

const chart = {
  id: 'donutForm',
  initial: 'idle',
  states: {
    idle: {
      on: { SUBMIT: 'submitting' },
    },
    submitting: {
      on: {
        SUCCEED: 'success',
        FAIL: 'failure',
      },
    },
    success: {
      on: { RESET: 'idle' },
    },
    failure: {
      on: { SUBMIT: 'submitting' },
    },
  },
}

Next, we're going to add a few libraries to our code that will let us use XState in our React component easily.

import React from 'react'
import { Machine } from 'xstate'
import { useMachine } from '@xstate/react'
//...

Now that we've imported the Machine factory function, let's pass our state chart to it.

const donutFormMachine = Machine(chart)

Now, let's bring that machine into our component with the useMachine hook.

export default function DonutForm() {
  const [value, setValue] = React.useState('')
  const [current, send] = useMachine(donutFormMachine)
}

We no longer need the transition function. It still exists, since it is a method on every XState.Machine, but the useMachine hook manages it for us. We also can get rid of our send function and replace it directly with the send function given to us by the custom hook.

We only have one update left to make. current now points to a state object, not simply a string. We need to replace all of our uses of current === 'some value' with current.matches('some value'). matches is a method on state objects that takes a string or object that represents a state in the machine, and returns true or false if it matches. Our component ends up looking like this:

return (
  <div className="donut_form-wrap">
    {current.matches('success') ? (
      <>
        <div>Donuts are on their way!</div>
        <button type="button" onClick={reset}>
          Reset
        </button>
      </>
    ) : (
      <form onSubmit={handleSubmit}>
        <h4>Get Yummy Donuts!</h4>

        {current.matches('failure') ? (
          <div className="error_wrap">Failed to order donuts</div>
        ) : null}

        <div>
          <label htmlFor="donutFormQuantity">Quantity</label>
          <input
            id="donutFormQuantity"
            min={0}
            name="donutFormQuantity"
            onChange={handleChange}
            step={1}
            type="number"
            value={quantity}
          />
        </div>

        <button disabled={current.matches('submitting')} type="submit">
          Order
        </button>
      </form>
    )}
  </div>
)

You can see a running example of this code at: https://codesandbox.io/s/quirky-shtern-ef40n.

Now, this is a form I'd be happy to come back to six months later and work on. Need to add some inputs? No problem. Need to add some states? No problem.

By enumerating instead of booleanating, we were able to create a program that grows in complexity linearly, not exponentially. Each additional state only adds the complexity of one more state, rather than the boolean explosion of 2^n states. This alone, is enough to reduce vast amounts of complexity in our applications today.

My hope is that you'll start to think differently about booleans. Really evaluate if they are the right tool for the job you are trying to accomplish. You might find creating a simple object enum is a better tool for the task at hand. Learn to reach for it more often. I'm sure you'll find many uses of it. I know I have.

The Future of Second Career Devs

Sat, 04 Jan 2020 00:00:00 GMT

At the time of this post, it has been roughly seven and a half months since I released an episode of Second Career Devs. I thought it was time to try and write down my thoughts regarding the future of SCD. I warn you, this is mostly a brain dump. It won't be very orderly. I'm not going to spend a lot of time editing this post. I'm just gonna spew words at my text editor and see what comes out.

Before I started SCD, I knew I wanted to do something that both got me some recognition and was useful to others. Vain, I know, but my father never said he was proud of me or that he loved me so I constantly seek the approval of others, yada yada yada. I don't have a lot of great app or OSS ideas that accomplish that need/goal, but I knew I could talk to people well and knew I had an angle to share with others. So I started SCD with no real plan, kind of like most of the things I do.

In the beginning, running a podcast was new and interesting. I like new and shiny things (as I imagine many with ADHD do). It was so new and interesting that I wasn't really aware of what it was costing me in time, money and energy. As time went on, this would become painfully obvious.

I think the first time it dawned on me that a podcast was more than I bargained for was when people asked for swag. I had no budget for swag.

The next time was when people complained I didn't have an episode out when I said I would. I couldn't tell them that a guest flaked on me not once, not twice, not even thrice, but four times. That was really shitty.

The next time was when someone more or less yelled at me publicly demanding to know when they would be a guest on the podcast. There was no sense of "guests are invited", it was total entitlement, "I added myself to your guestlist, so I demand to be on your podcast". Felt pretty shitty on that one, too.

Then another time was when it dawned on me just how much time goes into making a single episode. The act of finding a guest, scheduling the guest, recording the episode, editing, doing the admin to load the episode, update the website, etc, it amounts from 4-8 hours per episode, depending on how inefficient the process went. You can't shrink the time of recording, it takes what it takes. Editing takes at minimum the time it took to record. Scheduling is a nightmare. Everyone's always busy (including myself). If I were to try and put out an episode every week, we're talking between 200-400 hours of work in a year. That's 10-20% more work in my week. For what? Nothing. I make absolutely nothing from making a podcast.

Ok, so I can remedy that with ads and sponsors, right? Except they're just as flaky as guests. Now I have to get real contracts together, come up with rates and invoices and budgets and on and on and on. And if I do that I might want to start an LLC and all of a sudden I'm running a business I never planned on and that's more time and more energy being taken from me.

But the money is good, right? Kind of. It was nice to ask for some money and get it, but I used most of the sponsor money I made to pay for transcripts. Every episode with a transcript costs $1/minute to get transcribed by the most affordable service I can find. I was very happy with their work, but now each episode costs me $45-$60. I'm not complaining that accessibility costs money. I believe that making the podcast available to people is a good thing. It's simply a cost I never considered and didn't have a strategy to afford.

"What about Patreon, Kyle? What about donations to keep this going?" Still more work, plus I'm now begging for help and now I'm obligated to other people in a way I wasn't before. If someone makes a donation and I can't come up with a guest or the time or energy to finish a new episode, I've now let them down, too.

All of this, all of the crap around just trying to have a conversation with someone with an interesting story, the part of the whole project I was actually interested in, was a huge drain to me.

You can ask my wife, I've had very little energy for the last few years. I don't really want to hash out why my energy is low here, that's for another blog, but when you don't have a lot of excess energy and something isn't giving you any back, you're just not inclined to work on it. And so, here we are, me not working on SCD.

There was a time where I considered expanding SCD. I still think this is a good idea, but an SCD themed job board could be a real revenue maker. I even started the project once, but I found myself realizing that I don't want to beholden myself to this. I don't want it to be my job and that's what all this was becoming. I'm not sure what I want to be my job in the long run of my career, but I saw a future where I was trying to scrape a living out of running a podcast and a job board and I was not convinced that is what I wanted to do.

So this is where my head is at. SCD is loved by a bunch of people. It's useful and is a good thing for the world. Awesome. All the work around it. Completely not awesome. People want more. I'd love to give it to them, but the only part that interests me is the interviews and making the music for the ad spots and intro (yes, I made those all from scratch). I'm also interested in making the job board, but only if I knew it wouldn't have to be a full-time job. It could sustain itself after an initial effort. But I would rather not waste a second of my life on the other stuff at this rate.

I can't afford to hire someone to do all the scheduling, do all the editing, and do all the administrative work around SCD and I don't have the plans to remedy this situation. I'm not looking to add a part-time job to my life, and I'm not looking to put in the work to secure ads, sponsors, and/or donations to get to a place to afford to hire the other help I need to keep SCD going forward.

Which kind of leads me to an empasse. I would love for more stories to be out there, but I'm not willing to make the time, energy and monetary commitment to make it happen (especially when other uses of those commitments reap much better financial rewards, like my egghead courses). I just don't really know what to do at this empasse. I don't want to let it just die, but it kind of already has. I've honestly started to wonder what's the cheapest way I can keep the podcast hosted so at least the episodes remain available to everyone.

I'm going to stop spewing there. I know I'm not being very linear, and possibly incoherent, but I needed to share what was on my heart. I still love what I was trying to do, I wish it could stay simple and cost nothing to do. It's hard to do something that costs you when you don't feel like you have ample resources to be generous in that way. I'm sorry if I've let you down, but at least now you might know where I am.

If you want to respond to this post, feel free to send a tweet to @2ndCareerDevs. I would love to hear your responses. I do read them all, even if I'm a bit slow to respond to them.

How to Render an Object in React

Fri, 27 Dec 2019 00:00:00 GMT

import Log from './_Log'

The trick I'm about to show you I learned so early on in my days of learning React that it didn't dawn on me that others still don't know it. My apologies, let's fix that right now.

Have you ever made the mistake of trying to display an object in a React component?

const Component = ({ obj }) => <div>{obj}</div>

And been met with this?

Classic mistake. Don't worry, we've all made it a time or two. We can't render an object, but we can render strings. What if we turn the object into a string and render it then?

We can do that with JSON.stringify (docs). JSON.stringify takes an object and turns it into a JSON string. We can make a component that does this for us.

// I encourage you to look at the JSON.stringify docs to understand the
// `replacer` and `space` arguments
const Log = ({ value, replacer = null, space = 2 }) => (
  <pre>
    <code>{JSON.stringify(value, replacer, space)}</code>
  </pre>
)

We can now use this component anywhere we would like to display an object in our app. This is very useful for debugging apps.

Use this whenever you'd like to display your object in the browser instead of looking at the object value in the console or the devtools.

How to Add Algolia Search to a Gatsby Site

Sun, 22 Sep 2019 00:00:00 GMT

Update: In the time since writing this post, I have removed the search feature for my blog. Simply put, it was difficult to keep the number of searches below the free tier threshold every month. Instead, I now have a page with all posts that I'm working on developing filtering and search for. Thanks.

This weekend I shipped a new feature for my blog--search! Just have a look up and to the right. You should see it up there.

Adding search was easier than I expected. I had almost no understanding of the work involved in making this happen, but between the Algolia service, their react-instantsearch library, and a little help from Twitter, this was pretty simple to do. This post will walk you through all the steps it took to make that happen.

Before I do, quick shout out to Scott Enock for sending me an email requesting this feature. <Marker content="He said some nice things, too!" /> I legit didn't know enough people were reading this blog to make it worth adding this feature. Thanks!

Step One - Algolia Setup

First things first, you need to create an Algolia account to use their service. Head over to https://www.algolia.com/users/sign_up and sign up. There are a few forms to fill out. Here's the break down of what you need to do for each form step.

Fill out your information
Pick the data center closest to you geographically
You probably want to choose "Media - Content" and "As soon as possible"

After signing up, you get a 14 day free trial, but don't worry about that running out. You can upgrade your plan to their "Community" level, and it'll stay free (with some restrictions I'll talk about later).

You'll be taken to a screen with a few options, but head to the "Dashboard" first. Once you do, you'll be prompted to "Create an Index". Click that button and give it a good name. <Marker content="This form will inform you how to name indices for particular environments if that is something you require." /> You'll be prompted to "Upload Records", but we are actually going to let Gatsby create those records for us in a later step. At this point, you need to grab 4 pieces of information to take to the next step.

The name you just gave your index
Click "API Keys" in the left menu and get the following strings
- Your App ID
- Your Search-Only API Key
- Your Admin API Key

Step Two - `gatsby-plugin-algolia`

The next step in adding search to the blog is setting up the Algolia plugin for Gatsby. You can check out the repository here. Get started by installing the package.

npm install gatsby-plugin-algolia

Once installed, we need to do a few things to get the plugin fully configured. To start, we need to add some keys to our .env files. It is likely that you have both an .env.development and an .env.production file in your Gatsby application. For the sake of this tutorial, I will have you copy your keys identically into both files, but for your particular situation, it might make sense to setup separate Algolia indices for your development and production environments.

Take the four strings I had you save from the previous step, and add them to both .env.* files like so:

// .env.*

GATSBY_ALGOLIA_APP_ID=YOUR_ALGOLIA_APP_ID
GATSBY_ALGOLIA_INDEX_NAME=YOUR_INDEX_NAME
GATSBY_ALGOLIA_SEARCH_KEY=YOUR_ALGOLIA_SEARCH_KEY
GATSBY_ALGOLIA_ADMIN_KEY=YOUR_ALGOLIA_ADMIN_KEY

Now that we have our environment variables setup, we are going to need to be able to access them in gatsby-config.js. Gatsby has a few special rules around how it injects various environment variables into your Gatsby builds. One of the rules requires that we inject our own variables into the gatsby-config.js file, and this will require using the dotenv package. Install this package.

npm install dotenv

Now, we're going to require dotenv in our gatsby-config.js file to have access to our environment variables. Put the following code above your plugin setup in gatsby-config.js.

// gatsby-config.js

require('dotenv').config({
  path: `.env.${process.env.NODE_ENV}`,
})

Now that we have access to our environment variables, let's setup the plugin. In your plugins array, add a config object for gatsby-plugin-algolia, like so:

// We will define and import `queries` in the next step
// replacing this empty array.
const queries = []

module.exports = {
  plugins: [
    // You likely have other plugins here
    {
      resolve: 'gatsby-plugin-algolia',
      options: {
        appId: process.env.GATSBY_ALGOLIA_APP_ID,
        apiKey: process.env.GATSBY_ALGOLIA_ADMIN_KEY,
        indexName: process.env.GATSBY_ALGOLIA_INDEX_NAME,
        queries,
        chunkSize: 10000,
      },
    },
  ],
}

At this point, our plugin is configured. However, we still need to create some queries to be used by the plugin to create the Algolia index records (and UI to follow after that). So let's work on our queries next.

Step Three - Creating our Record Queries

An Algolia index is made up of records. In Gatsby, we create query objects that utilize GraphQL to get the data we send to Algolia to create these records. At this time, my blog only requires one query object, so I'll show you how I wrote that. Your specific needs might vary at this step in the process.

I want to create a record for each one of my posts. To do this, I need to write a GraphQL query that returns an object of data for each post. I'm going to do this in a separate file I've named algolia.js.

This file will export the queries array to be used by our configuration in gatsby-config.js, so I like to start my file with that, and then go back and fill in the rest of the logic.

// algolia.js
const queries = []

module.exports = queries

And in gatsby-config.js:

// gatsby-config.js

// replace the line `const queries = []` with the following,
// Make sure the path matches where you've put your file
const queries = require('./src/utils/algolia')

Now that our files are wired up, we need to provide at least one query object to our queries array. This object will likely take at minimum two properties (though, you should read the documentation for your own specific needs). Those properties are the query and transformer. The value provided for the query property is a GraphQL query string. The transformer is a function that takes the data retrieved by the query and transforms it into the array of objects that will become your Algolia index records.

My particular needs here are likely a bit different than yours. My blog explicitly uses Markdown and MDX files, but I can get all of the necessary files with one query to the allMdx property in my GraphQL schema. Let me show you the pieces I wrote for my initial query:

// algolia.js

const mdxQuery = `
  allMdx(filter: {fileAbsolutePath: {regex: "/posts/"}}) {
    edges {
      node {
        excerpt
        frontmatter {
          description
          slug
          subtitle
          tags
          title
          keywords
        }
        rawBody
      }
    }
  }
}
`

const unnestFrontmatter = node => {
  const { frontmatter, ...rest } = node

  return {
    ...frontmatter,
    ...rest,
  }
}

const queries = [
  {
    query: mdxQuery,
    transformer: ({ data }) =>
      data.allMdx.edges.map(edge => edge.node).map(unnestFrontmatter),
  },
]

module.exports = queries

My mdxQuery retrieves all the published posts. <Marker content="I may add queries for my courses in the future." /> Then my transformer method takes the data received and massages it into a shape I can use for my Algolia records by lifting the keys of the frontmatter object up to the same level as the rest of the node.

Again, your exact query will probably look different than mine. You can tweak your query using the Graphiql explorer that Gatsby has integrated.

As of right now, we are at a place where we can get some records into your Algolia index. The way I managed to do this was to run a production build of my Gatsby site, which triggered the plugin to generate the records.

npm run build

If everything worked, you should see in the build output evidence indicating that records were added to your Algolia index. You can now head to your Algolia dashboard, click the "Indices" link in the menu, and see that your index now has records.

We're going to revisit this file later on in the tutorial to improve our query.

Step Four - Create a Search UI

To create the UI for our search, we're going to make use of two more packages from Algolia: the algoliasearch SDK and the react-instantsearch-dom set of components that go with it. As you might expect by now, let's install them both:

npm install algoliasearch react-instantsearch-dom

Now, before we dive into the UI, please note that you might make very different decisions than I did when making your UI. I chose to put my search in a modal that takes up the full screen. I did this because it allowed the user to always have access to search regardless of what page they were on, without needing to navigate else where. It is possible that in the future, my UI might change. Since our UIs might be very different, I want to first show you the minimum example that you need, and then explain what I did with my UI.

I have made a new component file, Search.js, and the minimal example would look like this:

// Search.js

import React from 'react'
import algoliasearch from 'algoliasearch/lite'
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch-dom'

const searchClient = algoliasearch(
  process.env.GATSBY_ALGOLIA_APP_ID,
  process.env.GATSBY_ALGOLIA_SEARCH_KEY
)

export default function Search() {
  return (
    <InstantSearch
      indexName={process.env.GATSBY_ALGOLIA_INDEX_NAME}
      searchClient={searchClient}
    >
      <SearchBox />
      <Hits />
    </InstantSearch>
  )
}

This minimal example follows the documentation of the package, but also makes use of our env variables to wire things up correctly. If you import this somewhere in your app, you should be able to do searches on your Algolia index now.

All the components in react-instantsearch work together as "compound components". That is, used in the right way, each component receives the data it needs to render properly under the hood. You don't have to do any wiring yourself. However, you might not be completely satisfied with the UI this gives you. I wasn't. That's ok, there are options.

If you are using traditional CSS, you might be able to make all the customizations you need just by updating a stylesheet. Use the inspector (or look at the docs) to find the class names Algolia provides each of these components, and then write styles accordingly.

In my case, I'm using emotion for my styles, specifically the wonderful css prop (which I should totally blog about sometime). Lucky for me react-instantsearch also provides higher order components that allow you to create your own UI, which means combining it with emotion is no big deal.

In my case, I specifically customized the Searchbox, Hits and Pagination components of my UI. I'm going to focus on the customized Hits in this article, you can view the other customizations at https://github.com/kyleshevlin/blog/blob/master/src/components/Search.js.

The Hits are the individual results of your query. In my case, I just want a simple list of results running down the page, but with my styles. To do this, I'll use the connectHits higher order component provided, and then provide it a component that makes use of the hits prop it provides.

// Search.js

import React from 'react'
import algoliasearch from 'algoliasearch/lite'
import { connectHits, InstantSearch, SearchBox } from 'react-instantsearch-dom'
import { FONTS } from '../constants' // an object of the font family strings in my app
import { bs } from '../shevy' // a helper function for spacing from my vertical rhythm library

const searchClient = algoliasearch(
  process.env.GATSBY_ALGOLIA_APP_ID,
  process.env.GATSBY_ALGOLIA_SEARCH_KEY
)

// Please note, that to get the `css` prop to work, you'll either
// need to add a jsx pragma or use a babel plugin. Consult the
// Emotion documentation for setting that up for your project.
const Hits = connectHits(({ hits }) => (
  <div css={{ display: 'flex', flexWrap: 'wrap' }}>
    {/* Always use a ternary when coercing an array length */}
    {/* otherwise you might print out "0" to your UI */}
    {hits.length ? (
      <>
        {/* I wanted to give a little explanation of the search here */}
        <div
          css={{
            fontFamily: FONTS.catamaran,
            fontSize: '.85rem',
            fontStyle: 'italic',
            marginBottom: bs(1),
            maxWidth: '30rem',
          }}
        >
          These are the results of your search. The title and excerpt are
          displayed, though your search may have been found in the content of
          the post as well.
        </div>

        {/* Here is the crux of the component */}
        {hits.map(hit => {
          return (
            <div css={{ marginBottom: bs(1) }} key={hit.objectID}>
              <Link
                css={{ display: 'block', marginBottom: bs(0.5) }}
                to={hit.slug}
              >
                <h4 css={{ marginBottom: 0 }}>
                  <Highlight attribute="title" hit={hit} tagName="strong" />
                </h4>
                {hit.subtitle ? (
                  <h5 css={{ marginBottom: 0 }}>
                    <Highlight
                      attribute="subtitle"
                      hit={hit}
                      tagName="strong"
                    />
                  </h5>
                ) : null}
              </Link>
              <div>
                <Highlight attribute="excerpt" hit={hit} tagName="strong" />
              </div>
            </div>
          )
        })}
      </>
    ) : (
      <p>There were no results for your query. Please try again.</p>
    )}
  </div>
))

export default function Search() {
  return (
    <InstantSearch
      indexName={process.env.GATSBY_ALGOLIA_INDEX_NAME}
      searchClient={searchClient}
    >
      <SearchBox />
      <Hits />
    </InstantSearch>
  )
}

With the higher order component, I've been able to use the markup I prefer and style it in a way that fits my blog. Explore the docs and the other higher order components to get the results you're looking for.

Optional Step Five - Optimize Your Record Size

At this point, you should have fully functioning search working on your Gatsby site. Congratulations!

That said, if you're like me and adding search to a blog with many long posts, you may have run into an issue while creating your index--some of your records are too big.

I have a few lengthy posts that were breaking the allowable size limit for Algolia's "Community" plan. Luckily, the people over at Algolia have already thought about this and have written this handy post about handling long documents: https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/indexing-long-documents/.

Here's the TL;DR; If your records are too big, we need to divide the content of those records into smaller pieces and index those instead. How you do this is up to you and your specific data, but for a blog, a good place to start might be every paragraph (seriously). We aren't concerned with how big the index is, just the size of the records. At the start of this process I only had 77 records. By the end, I had over 1.7K records! Let me show you how I did it.

Reopen the algolia.js file from before, we're going to make some modifications to it. The culprit of my large records is the rawBody data I'm getting from my query. This contains all the text in the body of my blog post. Thus, a long post means a big record. We need to manipulate this data in a way to reduce its size.

// algolia.js

// `mdxQuery` and `unnestfrontmatter` are the same as before
// so scroll up to take a look at them

// I'm defining a function that will map over our data nodes
// We're going to return an array of record objects
const handleRawBody = node => {
  // We want to split `rawBody` from the node
  const { rawBody, ...rest } = node

  // To improve search with smaller record sizes, we will divide all
  // blog posts into sections (essentially by paragraph).

  // Since the body of my posts is markdown, we will split
  // whereever there are two adjacent new lines, this is a
  // reasonable proxy for paragraphs
  const sections = rawBody.split('\n\n')

  // Now, we're goint to map over each section, returning
  // an object that contains all the frontmatter and excerpt,
  // but only has the specific content on that key.
  // This way the results are still associated with the
  // correct post.
  const records = sections.map(section => ({
    ...rest,
    content: section,
  }))

  return records
}

const queries = [
  {
    query: mdxQuery,
    transformer: ({ data }) =>
      data.allMdx.edges
        .map(edge => edge.node)
        .map(unnestFrontmatter)
        // Now we take rawBody and manipulate it into many more records
        .map(handleRawBody)
        // And we flatten those records into a single array
        // alternatively, flatMap is available wherever ES2019 is implemented
        .reduce((acc, cur) => [...acc, ...cur], []),
  },
]

module.exports = queries

Now, our index has lots of tiny records which is exactly what Algolia wants. Also, each record still contains all the necessary data for our search UI to render. There is one final problem though.

If I were to do a search at this moment, say for the word 'React', I'll get results that show the same article over and over again because I use the tag React for my record objects. This isn't good. We need a way to dedupe the records. Luckily again, Algolia has thought of this.

We just need to update two places in our app to make this happen. First, we'll make a small update to the query object in algolia.js.

// algolia.js

// mdxQuery, unnestFrontmatter and handleRawBody are all the same as before

const queries = [
  {
    query: mdxQuery,
    // Here's the change
    settings: {
      attributeForDistinct: 'slug',
      distinct: true,
    },
    transformer: ({ data }) =>
      data.allMdx.edges
        .map(edge => edge.node)
        .map(unnestFrontmatter)
        .map(handleRawBody)
        .reduce((acc, cur) => [...acc, ...cur], []),
  },
]

module.exports = queries

In the settings object of our query, we are telling Algolia that we want distinct results and that they should be recognized as distinct by their slug property (which is unique to each post).

Now, we need to inform our UI that we only want distinct results. In our Search component, we need to add the Configure component. Since I don't want to show all my customizations (the code block would be quite long), I'll take the minimal version and add the Configure component to that. Make adjustments as you need to for your situation.

// Search.js

import React from 'react'
import algoliasearch from 'algoliasearch/lite'
import {
  Configure,
  InstantSearch,
  SearchBox,
  Hits,
} from 'react-instantsearch-dom'

const searchClient = algoliasearch(
  process.env.GATSBY_ALGOLIA_APP_ID,
  process.env.GATSBY_ALGOLIA_SEARCH_KEY
)

export default function Search() {
  return (
    <InstantSearch
      indexName={process.env.GATSBY_ALGOLIA_INDEX_NAME}
      searchClient={searchClient}
    >
      {/* Here's the change */}
      <Configure distinct />
      <SearchBox />
      <Hits />
    </InstantSearch>
  )
}

Seriously, that is all it took. Adding the distinct prop to our Configure component, and now my results return only one hit instead of many duplicates. I owe some props to Haroen who helped me out over the weekend to figure this last bit out.

Conclusion

And that's it! We're done. We got search working on a Gatsby blog (and you can apply this to any Gatsby site). To recap, the steps are:

Setup Algolia
Configure gatsby-plugin-algolia
Create queries to get and set your records
Create a UI with react-instantsearch-dom
And optionally, optimize your records

I hope you find this process as relatively painless as I did. If you're confused, be sure to check the documentation. If you're looking for additional resources, I recommend checking out this video from my friend Jason Lengstorf on his YouTube channel about this very same topic: Add Algolia search to your Gatsby site (with Bram Adams) — Learn With Jason. I know I found parts of the video helpful in this process.

This tutorial is still not exhaustive, but I hope it's a big help to what you're trying to accomplish. Hit me up on Twitter if you have any questions I can help with regarding the post!

Graphs Are Everywhere

Fri, 06 Sep 2019 00:00:00 GMT

import DirectedGraph from './_DirectedGraph'

A few years ago, I was interviewing for a new job and it was the first time I was asked to whiteboard algorithms. It did not go well. In fact, I got my ass handed to me.

I was not prepared. With no formal education in computer science, and just a couple years of writing mostly HTML templating and CSS, I didn't have the skills to pass those tests. Motivated by that failure, I began learning some some basic computer science knowledge in the forms of data structures and algorithms. That education lead to my Intro to Data Structures and Algorithms course on egghead.io. Gaining this knowledge, it changed the way I see things in the world.

One of the data structures I find most interesting is the graph. A graph is a collection of nodes (also known as vertices) and edges (also known as links or lines) that connect those nodes. One specific type of graph is the directed graph. The edges of a directed graph convey direction; that is, it is not enough to show nodes are connected, but (and not to personify nodes too much) from who to whom. Each connection has a source and a target.

When I gained an understanding of directed graphs, I began to realize that graphs are everywhere. The world is full of them. I experience real life graphs the most when observing the relationships of people. I want to share some of those observations with you. Consider this an incomplete, haphazard online art exhibition of directed graphs in the real world.

The first graph in this gallery I title Mutuality. It is the graph that forms when two nodes are connected to each other in a reciprocating fashion. A cycle formed back and forth between the two. I want to point out that the graph implies no connotation of positive or negative relationship. A mutual relationship can be one of respect, love, or attraction, but it can easily be one of resentment, disdain, and hatred as well.

The next graph in this gallery I title Admiration. I find that I typically admire others for something I find lacking in myself. For example, I admire people with the courage to start their own businesses, as I find that I'm more risk-averse than I would like to be. But the ones I admire also admire others for traits they are lacking in, and so on and so forth. A cycle of admiration forms where everyone is looking at someone else for something they don't currently have.

Admiration is an admittedly positive take on this graph. It could just as easily devolve into Envy.

It should also be noted that there can exist mutual admiration, and there can be cycles much greater than three people, but I hope the concept has been conveyed effectively.

The third piece in the gallery is something I've always struggled with, Loneliness. Without going into too many details here, I was always on the outside growing up. Even as a pretty successful adult, who's on the in for many circles, I still often feel lonely. I've come to learn more about myself over the years, to understand the reasons why I feel this way, but knowing why doesn't eliminate experiencing the feeling. If you've ever felt lonely, you've experienced this graph first hand.

The fourth installment in the graph gallery I have titled Interest. This one is also something I've experienced personally and continue to do as I gain new friends and grow my network. I imagine others have experienced it as well.

My specific depiction of "interest" is one of imbalance. There is a central node whose interest is directed at several other nodes, but all the other nodes are directed at them. There is no reciprocity.

As I mentioned, I've experienced this imbalance personally. What strikes me most about this graph is the wasted energy. Energy flows in one direction, no one ends up replenished or satiated.

To really get a picture of this, try dragging the nodes around the screen to organize them. Try making all the arrows point in roughly the same direction.

This one just sprang to me this morning as I was finishing this post, but I call it The Modern Coffee Shop. A few years ago, my wife and I binged through the show Friends, and what struck me as anachronistic was that the characters would hit on strangers in the coffee shop every few episodes. Cell phones had not proliferated, WiFi didn't exist, smart phones weren't even a figment of the imagination yet. People had fewer "personal technological barriers" that they could put between themselves and others.

I'm not saying this is a good thing or a bad thing. I'm not trying to place a judgment on it. I think we've made a trade off. There are fewer chances for spontaneous interactions and meeting new people, but for some people there is an increased sense of safety from the ability to put up these "barriers".

I know I could be romanticizing something that didn't really exist, but as an extrovert who loves talking to new people, the modern coffee shop where no one interacts, save for a few people, bums me out.

Conclusion

I could come up with many, many more directed graphs I find in the world, but I'm going to stop there. My only desire with this post was to share an interesting way of looking at the world through the lens of computer science.

You can find the component I used for this post on my blog's Github page at https://github.com/kyleshevlin/blog/blob/master/src/posts/published/graphs-are-everywhere/DirectedGraph.js and play around with it. Put it in a sandbox and have some fun.

Also, 1000 internet points to the people who figure out how I managed to get these svg graphs to stay centered despite the width of the screen and tweets at me. It's hacky AF.

When `else`s Make Your Code Worse

Wed, 17 Jul 2019 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

Prefer a video lesson? Watch it instead.

Recently, I wrote a tweet that got some attention about not needing elses in your code. Some people got a bit upset about that. Here's that tweet.

I still stand by what I said, and I recently came across some code that was a good example of what I was talking about. The code looked like this (more or less):

function unimportantName(options) {
  const { value, value2, value3, type } = options

  if (type === 'Date') {
    if (value !== 0) {
      return {
        lte: [String(value), value2, 'from now', 'starting end of today'].join(
          ' ',
        ),
        gte: !value3 ? 'today' : 'tomorrow',
      }
    } else {
      return { gte: 'today', lte: 'end of today' }
    }
  } else {
    return { lte: value }
  }
}

We have an if/else nested in the if block of an outer if/else. I can only guess, but I'd say most people can reason about this level of complexity fairly easily. But just because people can, doesn't mean they should have to. This code is needlessly more complex than necessary, and I want to show you how just making a few small changes can really simplify this block of code.

The primary thing I'm going to change is the order of the conditionals. This will make the code much simpler and here's how I would (actually, did) do it.

The first thing I notice is the outer if/else. The condition is if (type === 'Date'). Thus, I can conclude the else block is the negation of this condition, which means it is if (type !== 'Date'). By using the negation, we can refactor the else away and create a guard statement that early returns with the object we have in the final return currently. Let's start with this refactor.

function unimportantName(options) {
  const { value, value2, value3, type } = options

  if (type !== 'Date') {
    return { lte: value }
  }

  if (value !== 0) {
    return {
      lte: [String(value), value2, 'from now', 'starting end of today'].join(
        ' ',
      ),
      gte: !value3 ? 'today' : 'tomorrow',
    }
  } else {
    return { gte: 'today', lte: 'end of today' }
  }
}

By doing this, we've unnested one level of if/else blocks. We've removed the else statement, early returned, and because we now know that if we have passed that first if guard, we are in the territory where logically type === 'Date', we no longer need to check for it.

Now, we have one if/else remaining, is anything gained from refactoring this? I believe so. Our conditional is if (value !== 0), followed by a somewhat interesting object literal being created. Our else block, on the other hand, returns a very simple object. I'd prefer to switch the condition with the negation again, and move this part up as another guard statement and early return as well. Like so:

function unimportantName(options) {
  const { value, value2, value3, type } = options

  if (type !== 'Date') {
    return { lte: value }
  }

  if (value === 0) {
    return { gte: 'today', lte: 'end of today' }
  }

  return {
    lte: [String(value), value2, 'from now', 'starting end of today'].join(' '),
    gte: !value3 ? 'today' : 'tomorrow',
  }
}

Great, we've now gotten rid of any elses in our code, made it very clear which scenarios lead to early returns and have a final return if none of those conditions are met. Is there anything left to refactor? Yes!

I think using an array and calling join when we can use a template string doesn't make sense. I'll refactor this as a template string.

function unimportantName(options) {
  const { value, value2, value3, type } = options

  if (type !== 'Date') {
    return { lte: value }
  }

  if (value === 0) {
    return { gte: 'today', lte: 'end of today' }
  }

  return {
    lte: `${String(value)} ${value2} from now starting end of today`,
    gte: !value3 ? 'today' : 'tomorrow',
  }
}

And there it is, the final code. With just a handful of simple refactors, we have simpler code that is easier to reason about (and, frankly, maintain). I hope you can see some of the value in this kind of refactor, and that it helps you when writing your own code.

A Plea for Imagination

Wed, 29 May 2019 00:00:00 GMT

Some of you reading this know that I occasionally dust off the old microphone, fire up a text editor and make some educational material that I put on the interwebs. Mostly on egghead. You might even be aware of this very blog post as a direct result of watching one of my lessons. If so, that's awesome and I thank you. But fair warning, not all students are the same, and I might be speaking directly to you in the next few paragraphs.

For the most part, I've received overwhelming praise for my courses. I'm not bragging. Y'all are just incredibly grateful students and I really appreciate it. Receiving praise is a nice side effect of making the educational material.

That doesn't mean my courses aren't without their flaws or shortcomings, though. I am only human after all. <Marker content="And not always the brightest one at that!" /> The number one complaint I get about my lessons can be boiled down to, "How does this concept apply to real software?" <Marker content="Or better still, how does this apply to <em>my</em> particular situation?" /> Allow me to address this.

First, if you've never made educational material, than you might not realize that coming up with a good example is some of the hardest shit to do. It's one thing to have a problem you're trying to solve in the real world. The constraints reveal themselves and it doesn't matter how easy or complex it is, you just have to do the work you have to do.

It's another thing entirely to try and come up with an example that's simple enough for any student to approach while being similar enough to their work that they can imagine how to use it. Pay attention to that line, we'll come back to it.

You have to understand something, and it's something I think is lost on a lot of people who watch egghead videos. One thing people fail to really grasp about egghead is that there is a style to an egghead lesson. There's no fluff, nothing frivolous or extraneous at all. It is direct and to the point. <Marker content="Unlike my writing." /> Demonstration in favor of explanation. Thus, for all of you who have asked me to go further and explain when or why you would use a technique and have been disappointed that I didn't, can you understand why there simply isn't room for that within that context?

An egghead lesson is not the time to philosophize or enumerate all the possibilities for a technique. No, it is the time to get to the meat and potatoes of what you're teaching in the most succinct way possible. To that end, my examples are often contrived and lacking in depth or nuance. It's not that I'm not capable, it's that it doesn't suit the goals we're going for.

I don't actually see a problem with this mode of teaching, because, and here's the crux of my thesis, it is the responsibility of the developer or engineer <Marker content="or any human being for that matter." /> to be able to take the materials they are given and cultivate their imagination such that they can use the information in new ways, applied to new contexts. In other words, it's your job to learn how to remix what you learn into something more. Key words: your job. Not my job. Your job.

It is not my job as an educator to try and figure out a way to teach you all the ways in which you can use a technique or API. That would be insane! Almost everything has an infinite number of applications, it would be terribly difficult to cover even a moderate number of use cases. However, if I teach you concepts and give you the skills to apply that knowledge to other situations, then we can actually achieve something useful.

Think of it like this, to a small degree, a math teacher forces you to brute force memorize some maths. Like multiplication and division tables. This is done to simplify some of the more abstract work you'll have to handle soon enough. In web development, you can liken this to memorizing certain fundamental APIs, like certain HTML tags and how to nest elements. But after that, they teach you the concept of multiplication or division. Literally, they teach you an algorithm for solving those kinds of problems generally. They then ask you to imagine how to apply those algorithms in all sorts of ways. A math instructor provides you with tools and enough intuition to use them, but ultimately it is your responsibility to learn how to apply them in whatever situation you're in.

The same goes for when I teach a lesson. It doesn't matter if the example is contrived or all encompassing, it's your job to figure out how to take the concept and apply it elsewhere.

The reason this irks me so much is that when I hear those criticisms, they are aimed at me, but in reality, they aren't about me. No, those criticisms, they say more about the student than about me. Occasionally, they tell me I need to do a better job. Point taken if that's the case. But more often, they tell me that this person hasn't learned how to use their imagination. Haven't learned how to remix shit yet. Or even worse, and this is the one that really gets me, it tells me that person is lazy.

I want to give y'all the benefit of the doubt. Software is hard. Sometimes really fucking hard. I have time and patience for people who try hard and struggle much. I've been there, we all have. Shit, I've just spent six weeks on the struggle bus on a project and the ride ain't over yet. It happens to everyone I know at some point. We all need patience and understanding in those situations.

That being said, I have no patience for someone who is acting lazy. I ain't got time to hold someone's hand who doesn't want to work hard with me. I don't have the energy to carry you all the way to your epiphany or realization. You gotta work with me! Failing to exercise that gift of a brain you have, failing to even try to imagine other uses and scenarios for a lesson or technique, that's lazy, and it's not cool.

Look, I fundamentally believe we all have laziness in us. For hundreds of thousands of years, our hunter-gatherer ancestors worked far fewer hours than we do and socialized and leisured a whole lot more. <Marker content="I've read that some anthropologists hypothesize that the average person only needed to work 10 hours in a week to supply all their needs. Can you imagine only working 10 hours? I mean you'd also have to imagine wild animals possibly attacking you, but it might be worth it for only working 10 hours. Just saying." /> I think it's in our DNA to take things easy from time to time. But learning something new probably isn't the time to do that. This is the time to be active, to be alert, to be imaginative.

You need to cultivate your imagination. You need to improve your ability to think divergently. That skill, more so than any engineering/dev technique itself, is what will unlock potential in your career, and maybe in your life. So I'm pleading with you, before you criticize me, or another person with something like the complaint above, be sure to take a minute and try to use your imagination. Try and remix that shit.

Epilogue

I'd be remiss if I made a post on imagination and remixing shit and didn't mention this awesome documentary I watched a few years ago called Everything is a Remix. It's a short 4 part documentary that is well worth your time. Check it out, tell me what you think about it by tweeting me. Peace! ☮

Just Enough FP: Composition

Fri, 17 May 2019 00:00:00 GMT

Composition is the culmination of all the previous "Just Enough FP" blog posts. <Marker content="Don't worry, there are still more posts to come." /> It's where we combine our knowledge of higher order functions, currying, partial application, and pointfree programming into a new concept that can really unlock our functional potential.

Before I get into explaining this concept, I want you to think back to your high school math classes. <Marker content="I hope this isn't <em>too</em> traumatic a thought for you." /> You might recall somewhere around the time of Algebra 1 or 2 learning about mathematical functions, like this simple one: f(x) = x + 1. This function takes any x and always returns x + 1. You might recognize this as a pure function (all mathematical functions are pure functions).

Now, let's add a second function: g(x) = x * 3. This is also a pure function. What if I wanted to take the output of one function and feed it as the input of another function? It would look like this: f(g(x)). Now, x will first be mulitplied by 3, and then 1 will be added to it. If I provide an argument of 4 for x, the result will be 13.

This is functional composition.

It is the act of taking the output of one function and passing it directly as the input to the next function. In its most primitive form, it occurs through nesting functions like you see above. Let's make a practical-ish example of this.

An example I like to use involves manipulating a string through a series of functions. Let's start by defining those functions.

const scream = str => str.toUpperCase()
const exclaim = str => `${str}!`
const repeat = str => `${str} ${str}`

The scream function uppercases a string, exclaim adds an exclamation point, and repeat, well repeats the string (with a space inbetween). You'll notice that each function has the same arity. If you've forgotten what arity is, check out the currying post before going further. Each one is a curried, unary function. Also, notice that the argument type for each function is the same. They all expect a string. Our composition wouldn't work properly if we were mixing types, but I'll save that discussion for another time. Because all of our functions expect only one more argument and have the same type signature, we can nest them together, passing the output of one as the input of the next without any worries.

repeat(exclaim(scream('Just Enough FP is great')))
// JUST ENOUGH FP IS GREAT! JUST ENOUGH FP IS GREAT!
repeat(exclaim(scream('i luv learning')))
// I LUV LEARNING! I LUV LEARNING!

That's pretty cool! But imagine you had even more things you wanted to nest, or that your function names were longer than one word. That nesting would get very verbose and difficult to read. Is there a way we can tidy this up? Of course there is.

If you recall from the currying and partial application posts, curried functions do not evaluate completely until they receive their final argument. You'll also recall that they hold their previously partially applied arguments in closure awaiting that final argument. If we were able to programmatically combine all our functions into one new higher order function that awaited its final argument, we'd have ourselves a cool way of generating compositions.

Well, here's that cool way. The compose function:

const compose =
  (...fns) =>
  x =>
    fns.reduceRight((acc, fn) => fn(acc), x)

The compose function accepts any number of functions as arguments and returns a new function that awaits any value x. When x is received, we take our array of functions and call reduceRight (the same as Array.prototype.reduce, but we start from the end and work towards the beginning of the array), passing in the accumulated result as the input to the next function, starting with our value x. compose can be used like this:

const withExuberance = compose(repeat, exclaim, scream)

withExuberance('this is a-maz-ing')
// THIS IS A-MAZ-ING! THIS IS A-MAZ-ING!

You see, we were able to generate a composition by passing in the functions from before as arguments to the compose function, which gave us a brand new function awaiting our string. This string was passed first to scream, then to exclaim, and then to repeat.

"Wait! What?!" No, I can't read your mind, it's just the response I get every time I teach this.

In our mathematical compositions, the innermost function is always called first. When we nested our functions, they read from right-to-left: repeat(exclaim(scream(x))). So compose is designed to order its functions the same way, from right-to-left (or bottom-to-top if you have so many they don't fit on one line). This takes some time to get used to, but with a little practice, becomes fairly easy to read. <Marker content="<strong>Remember</strong>: reading top-to-bottom, left-to-right is not <em>natural</em>, it's <em>cultural</em>." />

We can actually break our composition down into smaller compositions and compose them together. Since we only have three functions, I'll only compose scream and exclaim.

const withExcitement = compose(exclaim, scream)
const withExuberance = compose(repeat, withExcitement)

withExuberance('composition is blowing my mind')
// COMPOSITION IS BLOWING MY MIND! COMPOSITION IS BLOWING MY MIND!

You can start to imagine how the ability to make small compositions and use them in larger ones can add some useful functionality to a program or application. So long as the arity and types match up, you should be able to compose at will without fear.

Bonus: `pipe`

If you ever work in a purely functional language, you'll likely become very accustomed to using compose and its right-to-left signature. However, to ease you into functional programming. There is an alternative: the pipe function.

It's exactly the same as compose, but instead of reduceRight, we use reduce.

const pipe =
  (...fns) =>
  x =>
    fns.reduce((acc, fn) => fn(acc), x)

Our compositions now read left-to-right, top-to-bottom. <Marker content="This is also how the pipeline operator <code>|></code> works in other languages" /> Forgive me, I had to teach you composition the mathematical way first. Our pipe compositions now would look like this:

const withExcitement = pipe(scream, exclaim)
const withExuberance = pipe(withExcitement, repeat)

withExuberance("I can't think of an interesting string")
// I CAN'T THINK OF AN INTERESTING STRING! I CAN'T THINK OF AN INTERESTING STRING!

Conclusion

Composition is the act of passing the result of one function directly as the input of another function. With our knowledge of higher order functions, we are able to generate useful compositions with a compose or pipe function that await any data to operate on. It provides a mechanism for building up complex functionality through combining simpler and smaller functions.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Build Up Complex Functionality by Composing Simple Functions in JavaScript.

Just Enough FP: Pointfree

Wed, 01 May 2019 00:00:00 GMT

Pointfree programming is a style of programming free of points. Great, you got it. Blog post over.

Just kidding!

While my first sentence is true, it's pretty unhelpful, so let me explain what pointfree programming is a little bit better.

In order to explain pointfree, we first need to understand what a "point" is. I'm going to teach you by showing you, and I'll use the Array.prototype.map method to demonstrate that.

The map method is a higher order function (because it takes a function as an argument). You can read the docs here. Let's create a simple example:

const arr = [1, 2, 3, 4, 5]

const doubles = arr.map(x => x * 2)

console.log(doubles) // [2, 4, 6, 8, 10]

Alright, really simple example. We pass a function to the map method that multiplies the number by 2 and we get a new array with doubled numbers.

I'd like to draw your attention to the function passed to map, x => x * 2. What is x? Maybe a better question, why x? Why not foo, or num, or potato? Each would work equally well. What is it that x signifies?

Another way of putting that is, what does x point to?

The function we passed to map is called a lambda, a single-use anonymous function. We use an arbitrary, interim variable to point to a value abstractly. Sure, we could follow "clean code" principles and name our interim variable better, but that would make it dependent upon the array, not the operation we're doing to the array.

Another way to put this is that using lambdas in this way puts more focus on the data, and less on the functions transforming the data. We want to flip this, and as we'll see when we get into composition, it's necessary that we make this change.

There's a way to use higher order functions that avoids lambdas, and increase legibility and reusability in our programs in the process. Let's walk through that process.

The first thing we need to understand is that we can pass in the name of a function to map, we don't need to use a lambda. Our code can look like this:

const arr = [1, 2, 3, 4, 5]
const double = x => x * 2

const doubles = arr.map(double)

We have pulled our lambda out of the map call and saved it in a variable as a function expression. We can now pass this variable directly to map. This is pointfree programming. We no longer concern ourselves with the point in our higher order functions. Instead we make a simple, easily unit-tested (though you probably don't need to) function, and pass that in by name.

Now, let's take it a step further. Let's combine currying and partial application to make this a little more functional.

const arr = [1, 2, 3, 4, 5]
const multiply = x => y => x * y
const multiplyBy2 = multiply(2)

const doubles = arr.map(multiplyBy2)

This time, we made a generic curried multiply function. We apply the first argument to multiply to create our multiplyBy2 function which is identical to our double function from before. But this time, I can pass multiplyBy2 around my application for reusability.

"But Kyle, multiplying by 2 is really easy. Give me something with some more substance."

I hear you. Let's take a more complicated example and show why pulling the function out might be helpful. What if I want to slug-ify a list of strings? We can do that kinda functionally and using pointfree programming.

The steps in this algorithm are pretty simple: lower case the string and replace spaces with hyphens. Let's create a bunch of random strings and give it a try.

const strings = [
  'Portland summers are amazing',
  'I like big beards and I cannot lie',
  'I am out of ideas for strings', // ha
]

const slugs = strings.map(str => str.toLowerCase().split(' ').join('-'))

console.log(slugs)
// [
//  "portland-summers-are-amazing",
//  "i-like-big-beards-and-i-cannot-lie",
//  "i-am-out-of-ideas-for-strings"
// ]

Let's make this pointfree and break up the steps of our algorithm.

// Same strings as before

const lowerCase = str => str.toLowerCase()
const split = separator => str => str.split(separator)
const join = separator => arr => arr.join(separator)

const splitAtSpace = split(' ')
const joinWithHyphen = join('-')

// Bit of a crazy way to do it, but should still make sense
const slugs = strings.map(lowerCase).map(splitAtSpace).map(joinWithHyphen)

Now, I can read in plain English what's going on in the final part of my program. Admittedly, it's pretty verbose this way, so let me give you a sneak peek to the next blog post and do this magically with composition:

const slugify = compose(joinWithHyphen, splitAtSpace, lowerCase)
const slugs = strings.map(slugify)

Boom! 💥 We're using pointfree all over the place and creating a brand new slugify function in the process. I'll explain this in greater detail in the next post, so stay tuned.

Conclusion

Pointfree programming gives us a few advantages. It encourages us to write small, easily tested, reusable functions to use throughout our applications. It encourages us to create well named functions so our programs become legible combinations of functions. And lastly, it reduces the surface area of bugs by eliminating lambdas and interim variables.

It will take some time to get used to, but with practice, reading pointfree programming will become as natural as reading the imperative pointful programming you're probably doing today. Give it a try in practice, see if there are places you find it useful!

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Eliminate Anonymous JavaScript Functions with Pointfree Programming.

Just Enough FP: Argument Order

Mon, 29 Apr 2019 00:00:00 GMT

In a previous post on currying, I used a filter function in a way that may have left you scratching your head. Not because you were still learning currying, but for other reasons. Let me quickly write that function again for reference in this post:

const filter = predicate => array => array.filter(predicate)

Our curried filter function receives a predicate argument (a predicate is a function that returns a boolean) first, partially applies that to the new function returned, and then awaits an array to operate upon. What might of had you scratching your head is the order of these arguments. Why did the predicate come before the array?

That's a good question and the easiest way to find the answer is just to try it. Let's write a badFilter function with the argument order swapped:

const badFilter = array => predicate => array.filter(predicate)

Now, the array is the first argument. This might seem more natural to many of you (and looks exactly like Lodash's _.filter method). With this order, your brain models it as, "I have an array, this is what I want to do to it." But what's the more reusable piece of that mental model? It's not the data. The data can change at any time. It's ephemeral, but what we want to do with our data, that is worth storing and reusing.

With the data argument first, we gain no advantage in partially applying it. We'd be better off just using the built in methods for that data type. And with the data first, we'll never be able to pipe the result of another function into this one. As we'll see in a future post on composition, having our data as the final argument is the key to being able to build up functional complexity with composition.

Let's just let the bad example play out a bit:

const arr1 = [1, 2, 3, 4, 5]

const badFilterWithArr1 = badFilter(arr1) // returns a function awaiting a predicate

badFilterWithArr1(n => n % 2 === 0) // [2, 4]
badFilterWithArr1(n => n % 2 !== 0) // [1, 3, 5]

That's no more useful than just calling the predicate functions on the the filter method of the array.

arr1.filter(n => n % 2 === 0) // [2, 4]

The wrong argument order immediately negates any benefit we gained through currying and partial application, so it's important that we have our data as our final argument in our functions.

Rules of Thumb for Argument Order

Here are my general rules for determining argument order. The first "rule", as I just stated, is data comes last. You can bake in a lot of reusable functionality with partial application and pass new data into it over and over with this order.

But what if I have a function that doesn't operate on data, but benefits from partial application and proper argument order?

In that case, the second "rule", and this is really my way of thinking about it, is to order arguments from most stable to least stable argument. What does that mean?

In my previous post on partial application, I used the example of building up a function to fetch data from an API. That function looked like this:

const getFromAPI = baseURL => endpoint => callback =>
  fetch(`${baseURL}${endpoint}`)
    .then(res => res.json())
    .then(data => callback(data))
    .catch(err => {
      console.log(err)
    })

If we examine a REST APIs URLs (so many acronyms, sorry), the part of the URL that changes the least (and in a good API, never) is the baseURL. If I want to fetch data from Github, I can make a partially applied function like this one:

const getFromGithub = getFromAPI('https://api.github.com')

This function is really useful! I can build up many endpoints from this one function.

const getUsersFromGithub = getFromGithub('/users')
const getReposFromGithub = getFromGithub('/repositories')
const getPublicGistsFromGithub = getFromGithub('/gists/public')

The endpoint is less stable than the baseURL, it changes frequently, but still less frequently than what we want to do with the data once we fetch it. We can do any number of things once we have our users. Thus, the callback argument is last because it is the least stable of our arguments.

I'd give you a few examples, but literally you can do almost anything you want with the data once you have it. Use your imagination.

Conclusion

Argument order in curried functions makes a big difference in how useful and reusable a function is. It's also paramount for enabling composition, as we will see in a future post.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Improve JavaScript Function Usability with Proper Argument Order in Functional Programming.

Just Enough FP: Partial Application

Sat, 27 Apr 2019 00:00:00 GMT

I mentioned partial application several times in my previous post on currying with the promise of going in more detail about it in the future. I'm fulfilling that promise now. Or resolving. There's an easy pun or two there if you look for them.

Partial application is the act of applying some, but not all, of the arguments to a function and returning a new function awaiting the rest of the arguments. These applied arguments are stored in closure and remain available to any of the partially applied returned functions in the future. For those of you who are unfamiliar with closures, let me break that down for you.

In JavaScript, we can use scopes in a way that allow us to supply state to a function or object, without exposing that state directly to the outside world. This process is called a closure. Let me give you an example.

function withCallCount(fn) {
  let count = 0

  return (...args) => {
    console.log(`This function has been called ${count++} times`)
    fn(...args)
  }
}

const add = (x, y) => x + y
const addWithCount = withCallCount(add)

addWithCount(2, 4) // This function has been called 1 times
addWithCount(7, 5) // This function has been called 2 times
addWithCount(2, 4) // This function has been called 3 times

So what's going on here? The withCallCount function creates a variable count that is restricted to the scope of that function body. I cannot access it from outside that function. However, the anonymous function I return makes use of count, so that value will remain available to the returned function for as long as it exists. Thus, the new function addWithCount is able to log out the state of the count with each call.

Closures can get much more complex than this, but essentially it boils down to creating state within one scope and not exposing it, but using it, in another.

With this in mind, partial application should start to click. Let's take our curried add function from the previous lesson and point out the closure over the x argument. I find it easier to point out the closure using the function keyword, so I'll do that here, but know that the same thing occurs when using arrow functions.

function add(x) {
  // `x` is held in closure here, it remains available to the returned function
  // because it is used in the final return of `x + y`
  return function (y) {
    return x + y
  }
}

Now, if I take this function and only give it one argument, we can see how that value is stored in the new function and able to be reused over and over

const add6 = add(6)

console.log(add6(4)) // 10
console.log(add6(20)) // 26
console.log(add6(-14)) // -8

The same x value, in this case 6, is held in closure for each call we make of the add6 function. If we use our imaginations a bit, we can find a lot of great examples where this is useful.

For example, let's imagine I need to fetch different resources from the same API. I can generate different endpoints quickly with partial application. Let's create an example with the Github API

const getFromAPI = baseURL => endpoint => cb =>
  fetch(`${baseURL}${endpoint}`)
    .then(res => res.json())
    .then(data => cb(data))
    .catch(err => {
      console.log(err)
    })

const getFromGithub = getFromAPI('https://api.github.com')

// Now we have a partially applied getFromGithub function we can apply
// different endpoints to
const getUsersFromGithub = getFromGithub('/users')
const getReposFromGithub = getFromGithub('/repositories')

// Now I have two new partially applied functions. I can use
// different callbacks with each, and do something with the data

// Log out their logins
getUsersFromGithub(data => {
  data.map(user => {
    console.log(user.login)
  })
})
// ["mojombo", "defunkt", "pjhyett", "wycatz", ...]

// Log out their avatar urls
getUsersFromGithub(data => {
  data.map(user => {
    console.log(user.avatar_url)
  })
})
// [
//  "https://avatars0.githubusercontent.com/u/1?v=4",
//  "https://avatars0.githubusercontent.com/u/2?v=4",
//  "https://avatars0.githubusercontent.com/u/3?v=4",
//  "https://avatars0.githubusercontent.com/u/4?v=4",
// ]

// Or I can get some repos and logout their names
getReposFromGithub(data => {
  data.map(repo => {
    console.log(repo.name)
  })
})
// ['grit', 'merb-core', 'rubinius', 'god', 'jsawesome']

You can see how partial application gives us a lot of useful, reusable functions we can pass around our app and reduces how much code we need to write in later uses.

Bonus

Partial application can be done without currying (though I've never had a reason to do so). The bind method on functions allows you to supply arguments to the function that are applied to the new returned function (docs here).

The first argument of bind is the thisArg. This argument will be bound to this for the new function. We're going to pass in null, because we don't want anything bound to this.

Any argument passed to bind after the the thisArg is partially applied as an argument to the function. We can pass any number of arguments, and if we pass in fewer than the function expects, we'll get a partially applied function.

const multiply = (x, y) => x * y

const multiply7 = multiply.bind(null, 7)

console.log(multiply7(3)) // 21
console.log(multiply7(4)) // 28
console.log(multiply7(5)) // 35

So if writing curried functions isn't available to you for some reason (breaking change to API, frightened coworkers, etc) and you still want to create partially applied functions, here's an option for you.

Conclusion

Partial application is just the natural combination of curried functions and closures. Arguments previously applied are stored and available to the new functions returned. This process could lead to easier to write and understand code, though you'll have to decide what's useful for you (and your team).

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Create Reusable Functions with Partial Application in JavaScript.

Just Enough FP: Currying

Fri, 26 Apr 2019 00:00:00 GMT

Currying is, by far, one of the coolest things I've learned in the last few years. When it clicked in my brain, it was such an intense epiphany that I literally ran to the other room and begged my wife to join me in the office so I could explain it to her on the whiteboard. She doesn't know a thing about programming, but she listened to me. "Yeah, Kyle, that kinda makes sense." Ha. I just had to share it with the first person I could find. Bless her for putting up with me.

Anecdote over, on with the blog post!

What is Currying?

My least jargon filled way of answering that question is this: Currying is the act of refactoring a function that normally receives all its arguments at once into a series of functions that only take one argument at a time.

In JavaScript, functions can receive any number of arguments. The number of arguments a function expects to receive is known as its arity. Normally, we do not worry too much about how many arguments a function receives. If it needs more than one argument, we write it so that it receives all its arguments at one time. I believe this makes a lot of intuitive sense and maps to how our brains model and understand functions. Give the function all the arguments, do something with them, give me back the result. Easy peasy. But it's not the only way.

In functional programming, all functions only receive one argument at a time. A function with an arity of one is known as a unary function. All curried functions are unary functions. A curried function that requires more than one argument to fulfill its operation, returns a new unary function with each argument until it has all the arguments it needs to finally evaluate.

Let me demonstrate the currying process with the canonical example, an add function.

// A common add function
function add(x, y) {
  return x + y
}

add(2, 3) // 5

This function has an arity of two, aka a binary function. It expects both arguments at the same time, adds them together, and gives the result back to you. To make this a curried function, we are going to refactor it so it receives the x and y arguments one at a time.

// A curried add function
function add(x) {
  return function (y) {
    return x + y
  }
}

// Or its arrow function equivalent
const add = x => y => x + y

// If we only have our `x` argument, we can apply it and return a
// function awaiting the `y` argument with the `x` in closure
const add2 = add(2)

// We can then supply the 'y' argument
add2(3) // 5

// For good measure, if you had both arguments at the same time,
// You can supply both by immediately invoking the returned function
add(4)(6) // 10

Our curried function receives the x and y arguments one at a time. When we receive the x argument, we return a new function awaiting the y. This new function has our x value stored in closure. This is known as partial application. Partial application is a very powerful feature of currying that I'll explore in more detail in the next post, but for now just keep following along and try to grok it through context. It'll be ok.

If you're following with me, you now understand what currying is, but are probably still confused as to why this is an important technique. I'm going to give you an example that admittedly will skip ahead a bit, but should show you some of what gets unlocked when functions are curried.

Let's consider the array method filter. filter receives a predicate function (a function that returns a boolean) that operates on each item in an array and returns a new array with only the items that return true. You can check out the docs here. What if we could use the same filter on multiple arrays more easily? Let's create our own filter function that's curried.

const filter = predicate => array => array.filter(predicate)

Our function receives the predicate argument first, returns a new function that awaits the array and then evaluates and returns the result. Let's create a predicate and pass it to filter.

const filter = predicate => array => array.filter(predicate)
const filterForEvens = filter(x => x % 2 === 0)

We have now created a new function, filterForEvens which has the predicate partially applied. This predicate returns true if dividing by two returns a remainder of 0. The filterForEvens function awaits an an array argument. So let's give it some arrays.

const filter = predicate => array => array.filter(predicate)
const filterForEvens = filter(x => x % 2 === 0)

const arr1 = [1, 2, 3, 4, 5, 6, 7]
const arr2 = [1, 4, 9, 16, 25, 36, 49]
const arr3 = [1, 8, 27, 64, 125, 216, 343]

filterForEvens(arr1) // [2, 4, 6]
filterForEvens(arr2) // [4, 16, 36]
filterForEvens(arr3) // [8, 64, 216]

By currying our filter function, we've given ourselves the opportunity to delay supplying the array argument. This allows us to supply as many different arrays to our filterForEvens function as we want and we never have to resupply the predicate argument.

As we'll see in the next post, currying and partial application is a powerful combination. We can DRY up code in our application through it's use. We'll also explore two other topics related to currying: argument order and function composition.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Refactor a Function to Use Currying in JavaScript.

Just Enough FP: Immutability

Sun, 21 Apr 2019 00:00:00 GMT

Alright, I know that the title of this post already contains some technical jargon that's potentially intimidating. But if you've made it this far, I assure you, you can understand this concept.

Let's define "immutability". The fastest way to do that is to start with its antonym--"mutability". Mutability comes from "mutable". Something that is mutable can be changed. Thus, something that is immutable cannot be changed.

Mutable data structures can be changed after creation, aka mutated. Immutable data structures cannot.

You might be asking yourself, how do you make changes to data that can't be changed? Good question.

In functional programming, instead of mutating the data directly, we make changes to our data by returning a new data structure with the correct values to reflect that change. Let me give you some examples involving an object. In this first example, I'll mutate the data.

const me = { name: 'Kyle', age: 33 }

// I recently had a birthday, let's increase my age mutably
me.age++
console.log(me) // { name: 'Kyle', age: 34 }

We have directly modified the value at me.age with a mutation. While we still have the same object (the reference hasn't changed), we have permanently changed the contents of the object. This is sometimes referred to as a destructive operation, because it does not leave the original object intact during the operation. In this second example, I'll modify the age immutably now:

const me = { name: 'Kyle', age: 33 }

// I recently had a birthday, let's increase my age immutably
const olderMe = Object.assign({}, me, { age: 34 })

console.log(olderMe) // { name: 'Kyle', age: 34 }

In this case, I create a brand new object and merge the old properties with the new ones to get the correct data structure. I still have access to the me object and now the olderMe object. olderMe reflects the changes we wanted to make to the data.

A Case Study: Array.prototype.sort()

A lot of our work involves manipulating arrays of data. You might find that after getting very accustomed to using declarative immutable methods like map and filter, you find yourself reaching for sort and BOOM 💥 you've mutated your underlying data permanently without intending to.

Array.prototype.sort is a destructive array method, performing the sort "in place" on the original array itself. I'll get into why this is the case in a little bit. First, let's observe what I mean.

If I have an array of numbers and call sort on it, the reference to that array doesn't change.

const arr = [5, 3, 2, 4, 1]
const arr2 = arr.sort()

console.log(arr) // [1, 2, 3, 4, 5]
console.log(arr2) // [1, 2, 3, 4, 5]
console.log(arr === arr2) // true, each variable references the same array

Sorting mutably might be exactly what you want if you never need to use the array to derive any other data from it. However, often you'll want to keep the original array intact for other purposes. Perhaps you have a table of data derived from a collection of objects, rather than mutate the array each time you need to sort it in a different way, it might be best to create a brand new array with the sort applied. Let's create a safeSort function to do this. I'm going to use a curried function to do so, which I will cover in a future blog post.

const arr = [5, 3, 2, 4, 1]

/* If you are unfamiliar with currying, this will look confusing, but break
 * it down into steps and it's pretty easy to understand.
 *
 * 1. The first argument is the optional comparator function the `sort`
 * method receives. This returns a new function.
 *
 * 2. The second argument (the first of the second function) is our array
 * to operate on. This implicitly returns the value to the right of the =>
 *
 * 3. We create a new array and spread the items of the original array into it
 * so as not to make any mutations to the original array.
 *
 * 4. We now perform the sort operation on the _new array_, leaving the old
 * one intact
 */
const safeSort = comparator => array => [...array].sort(comparator)

const arr2 = safeSort()(arr)

console.log(arr) // [5, 3, 2, 4, 1]
console.log(arr2) // [1, 2, 3, 4, 5]
console.log(arr === arr2) // false

Now our safeSort sorts the contents of our array without making any changes to the original, returning to us a brand new array reflecting our changes. Thus, we have made an immutable change to our data.

Implications

I wanted to take a moment to point out the tradeoffs being made between mutable and immutable data structures. Now, I am no expert in computer science, so I will give you the best information I have, but I want it to be clear there might be some cases where the generalizations I make here are wrong.

Mutations, and thus mutable data structures, have some great benefits. Mutating data models how we understand the world. When we make changes to something, we change that thing, we don't return a new copy with the changes applied. One of my favorite metaphors is drinking a glass of water. When we take a sip, we mutate the amount of water in the glass, and we mutate the amount of water in ourselves.

Mutations also tend to be great for performance, as the operations happen in place. They do not require new structures to be created in memory, or old structures to be garbage collected. For example, in video games, often game developers will create a "pool" of enemies, a set number of enemy objects, and then mutate the objects in that pool to reflect which enemies are alive and dead. Under the hood, you might kill an enemy and the program collects that dead object, mutates new life onto it and sends it back at you as a "new" enemy. You think you're being attacked by a new enemy, but in reality, that reference is the same reference as the old enemy.

There are downsides to mutations. First, the destructive nature of the operations can lead to complications, especially regarding situations where we might need to undo operations. Also, mutations can lead to difficulties with state management. What if two operations attempt to change the same data concurrently? Which one takes precedent? What data will we get back in return? Bugs from mutations can often be some of the hardest to track down and fix.

Immutability, and thus immutable data structures, also have some great benefits. Making changes to immutable data structures often leads to very prescriptive, easy to understand (albeit often verbose) changes to data. This methodology allows us to gain levels of certainty about our programs that mutations don't inherently give us. The popular state management library Redux is based on immutability, because this gives us the ability to serialize our state and use it for things like time-travel debugging and very simple undo/redo abilities.

The biggest downside to immutability has to do with memory consumption. Creating new data structures for each change can have an effect on performance, though be certain to benchmark your performance and verify before worrying about this too much. Most modern systems have ample memory for many of the operations you and I are doing in our web applications.

Conclusion

Understanding the difference between mutable and immutable data structures is very useful information. Being able to look at code and recognize mutations will really help you understand what transformations your data is going through and may even help you spot a bug or two.

In functional programming, we require immutable changes because of the purity of our functions. Mutations cannot make the guarantees immutable data can. Mutations can lead to inconsistent results and/or side effects, and we can't have that if we're really going to unlock the power of functions in coming posts.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Avoiding Mutations in JavaScript with Immutable Data Structures.

Just Enough FP: Pure Functions

Sun, 14 Apr 2019 00:00:00 GMT

Another fundamental of functional programming is a solid understanding of pure functions. A pure function is one in which its output is derived solely from its inputs, with no side effects. I know that might still seem like gibberish to some of you, so I'll break this down and hopefully make it simple and clear.

The First Part

The first phrase to break down and clarify is "its output is derived solely from its inputs". Another way to say that is this: given the same arguments, the function always returns the same value. Let's look at a basic example.

// A pure add function
function add(x, y) {
  return x + y
}

// or with an ES6 arrow function
const add = (x, y) => x + y

The add function will always return the same output given the same arguments. In fact, all functions in math are pure functions, so there's a good chance you're already familiar with the concept.

Now, what if the output doesn't depend on the inputs? Is it still a pure function?

function subtractFromMaxSafeInteger(number) {
  return Number.MAX_SAFE_INTEGER - number
}

In the subtractFromMaxSafeInteger function, given the same input, we always get the same output, right? Sure looks pure.

But it isn't.

Our output depends on a global constant Number.MAX_SAFE_INTEGER. This makes it impure, as our output should derive solely from the inputs. If our function was dropped into another program that redefined Number.MAX_SAFE_INTEGER, we'd end up with different outputs, which would break our function's purity.

In other words, the "outside world", that is the scope outside of our function, should have no affect on the output of our function.

We also need to be aware of any impure functions within the function we are evaluating as they will impurify an otherwise pure function. Let me show you an example of what I mean. I'll create a factory function that makes "friend" objects for a program. I'll want unique IDs for each "friend", so I'll create a generateID function as well.

// DISCLAIMER: Do not use this to create IDs. There are much better ways. Go find them.
const generateID = () => Math.floor(Math.random() * 10000)

const friendFactory = (name, age) => ({
  id: generateID(),
  name,
  age,
})

I could pass the same name and age to the friend factory, but I'll get different results each time because generateID is an impure function.

friendFactory('Anna', 31) // {id: 6777, name: "Anna", age: 31}
friendFactory('Anna', 31) // {id: 6233, name: "Anna", age: 31}
friendFactory('Anna', 31) // {id: 7223, name: "Anna", age: 31}

Notice, that the id property is different in each object returned from our friendFactory function. We could make our friendFactory a pure function again by generating the ID outside of the function's scope and passing it in as an argument instead.

The Second Part

Now, the second part of my description, "with no side effects", is a little trickier to understand. The way I like to describe it is that a side effect is a change outside the scope of our function. Let me demonstrate with an example.

let count = 0

const addWithIncrement = (x, y) => {
  count++
  return x + y
}

addWithIncrement(1, 2)

This addWithIncrement function will always return the same value given the same inputs, and its output depends solely upon those inputs. However, every time we call this function, we change the value of count, which is outside the scope of our function.

Another surprising impure function that falls under this category is a function that has an effect on the world outside of our application. For example:

const log = x => {
  console.log(x)
}

log('This is an impure function. Wha???')

The log function doesn't make a change inside of our program or application, but it affects the outside world, triggering the console to log out the value passed in. This is a side effect, and thus log is impure.

What Does This Mean?

It means that we need to be aware of which functions in our programs are pure and impure. We need impure functions for our applications to do anything meaningful. Strictly speaking, a program entirely made of pure functions (with no side effects) is equivalent to doing nothing at all.

But, using pure functions throughout our application until we need the side effect to do something meaningful will make our applications easier to test and reason about.

As we will see in future posts, pure functions create the foundation for some very cool functional programming techniques, especially composition.

In my opinion, your goal should be to use more pure functions in your application. Functions that do too much, or have random side effects, can result in buggy applications. Side effect bugs can be some of the most difficult to find and remove.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Identify Side Effects by Comparing Pure and Impure Functions.

Just Enough FP: Higher Order Functions

Mon, 08 Apr 2019 00:00:00 GMT

Making sense of functional programming requires a solid understanding of a few fundamental concepts. In my opinion, the first one you need to learn is the concept of "higher order functions".

A higher order function is a function that meets at least one of the following requirements:

It accepts a function as an argument
It returns a new function

Functions (and methods) that receive a callback argument are good examples of higher order functions that fulfill the first criterion, such as map or filter on an array.

A good example fulfilling the second criterion is the bind method for functions, which returns a new function (Here's a link to the docs if you're unfamiliar with bind).

Often, a higher order function will fulfill both criteria.

Why Are Higher Order Functions Useful?

There are several reasons higher order functions useful, including some that I will cover in future blog posts about currying, partial application, and composition. For now, I'll talk about more general uses of higher order functions.

Hiding Implementation Details

The first reason, in my opinion, that higher order functions are useful is that they are a great mechanism for "hiding" and abstracting away implementation details. This is the benefit gained from using higher order functions that receive a function as an argument.

For example, the map method mentioned before could be written any number of ways. Do we use a for or a while loop? How do we manage creating a new array and putting our new values into it? The higher order map method means that you, the consumer of the function, don't need to worry about those details. Even better, by using the higher order function, you are automatically opted into any upgrades and improvements that are made to the method.

Adding Functionality to an Existing Function

The second reason is to add functionality to already existing functions. The best way to understand this is through an example.

Often when debugging code, I want a fast way to log out to the console the result of a function while still allowing it to return that result, not breaking the call stack.

You could use a debugger statement. That might be the best strategy in some situations, but if the function is called a lot, it can be frustrating to have to "step over" so many functions.

You could also manually add the console.log, but sometimes that can be very tedious. You gotta save the result to a variable, log it out, then return it. Since higher order functions can receive functions as arguments, what if we make a higher order function that handles these implementation details for us.

function logResult(fn) {
  return (...args) => {
    const result = fn(...args)

    console.log(result)

    return result
  }
}

Our higher order logResult function receives a function as an argument, returns a new function that receives any number of arguments, calls the original function with those arguments, and logs out the result before returning it. Now, if I'm working in some code and want to see the result of a function call without having to store it, I can wrap the function in logResult and pass the args to that instead.

transformData(data) // Uhh, what does this do?

// We can wrap it with logResult to find out
logResult(transformData)(data) // Oh! That's what it does.

Now we can see the result of our transformData function every time it is called. Saves us a few steps of saving the result to a variable and logging it out manually every time.

Another example of higher order functions that you might be familiar with are Higher Order Components. Since React components boil down to simple functions, we can enhance them by passing them as arguments to higher order functions.

There are many articles out there on creating Higher Order Components (a style that has fallen out of favor, first with the rise of render props, and now with the advent of Hooks), so I don't feel a need to cover it here.

Some Additional Thoughts on Higher Order Functions

In JavaScript, a language where functions are first class citizens that can be treated like any other value, higher order functions are really no different than normal functions. The descriptor "higher order" comes from mathematics and it shouldn't concern us very much. Our concern should be understanding how to wield them to improve our programs.

As you grow more comfortable with higher order functions, I'm certain you will find a number of use cases for them. Use your imagination, who knows what you'll come up with.

In this series, I'm going over material from my Just Enough Functional Programming in JavaScript course on egghead. This post is based on the lesson Modify Functions with Higher Order Functions in JavaScript.

Just Enough Functional Programming Course Launch

Fri, 22 Mar 2019 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

In 2017, I came across The Mostly Adequate Guide to Functional Programming by Brian Lonsdorf. It's an incredible resource and introduction to functional programming in JavaScript. It inspired me to start giving talks about functional programming in 2018. After giving the talk several times, I decided to make a course to go along with it. That course is available to you now on egghead.io.

The course is called Just Enough Functional Programming in JavaScript and I think you'll like it.

It's a concise, to-the-point introduction to functional programming designed to help you get started and start applying these concepts to your work right away.

Here's what you'll learn in the course:

Higher order functions
Pure functions
Immutability
Currying
Partial application
Pointfree programming
Functional composition
Debugging
And more...

In just 30 minutes, you'll learn more than "just enough".

Here's the course intro video. Give it a watch!

Your Own Gathering

Sat, 02 Feb 2019 00:00:00 GMT

A few months back, Jason Lengstorf and I started a gathering for people in Portland to get together, relax, and get to know one another. Our biggest night so far had over 30 people crowding this cozy little backroom of a local bar. It was great.

A lot of people have expressed experiencing considerable FOMO since they can't make it or the desire to have something like this in their own city. I'm here to tell you that you can! It's simpler than it sounds. I want to let you in on all the planning Jason and I did for this gathering.

One of us, cause I don't remember who initiated: We should get some beers soon.

The other: That sounds great! What if we invited a few others?

The first: Awesome, let's share it on Twitter.

That's it. That's really all there was to us starting our gathering. It wasn't a lot of planning, and frankly, it hasn't been a lot of work either. Hardest part has been mentioning everyone on Twitter (a problem somewhat alleviated by our newsletter). We wanted to get together to hangout, we wanted our friends to join us, and the opportunity to meet new people from our community. No agenda other than that.

But Kyle, You Don't Understand My Very Specific Situation!

You're right. I don't. This might not work for everyone, but I think the idea of gathering people regularly around food and drink is universal and a good starting point for community building. In most cases, all it takes is some initiative, someone to get the ball rolling.

Now, I won't lie, Jason and I have a lot of initiative between us. We're both the kind of people to come up with an idea and execute it. We're also pretty decent networkers, too. Having the reach we have is helpful, but it doesn't mean you have to be us to make this work for you. I think you can create a gathering of your own with all the skills and talents you have right now.

The reason I am so confident that you can do this is that I believe that there is nothing fundamentally special or unique about our group. Since there's nothing unique, there's essentially no part of the gathering you can't replicate (or even improve). Here are some of the mundane features that I think make our gathering successful.

No Speakers

Our agenda has never been to have a traditional meetup with speakers and food. That's not what we wanted. Because meetups are organized around speaking, any networking and relationship building ends up happening as a byproduct of proximity, that is, it happens because you're unintentionally next to each other. It does not happen through the intentional activity of community.

Intention is the key difference. Having a gathering where the focus is community generates opportunities for genuine networking. For example, I've helped a couple people I didn't know before our gathering find new career opportunities already. Why? Because there was more space and room for understanding each other (and our needs) when the time allotted isn't taken up by a speaker(s) slot.

No Topic, Theme, or Agenda

Meetups tend to organize around a shared interest and attendees come to listen to someone talk about that shared interest (at least in tech meetups). This creates a fundamental problem. The shared interest increases the likelihood for redundant information transfer. That's a really boring way to say, you've probably heard what the speaker has to say before because you're interested in the same topic and have read and watched the same things.

Conferences tend to be the exception because often the talks are bit further ahead of the curve than at meetups. A new library was invented, a new technique (re)discovered. There is occasionally an incredible meetup talk (not suggesting any of mine have ever been that incredible), but on the whole, if you're staying up to date in your field, there's not a lot of new stuff being said.

But here's the thing we all share: we're all humans. Getting people together with no agenda means that they can talk about whatever they want. And I do mean talk. Without speakers, everyone participates to the level they want to in the gathering. Dialogues are preferable to monologues.

In our gatherings, we've talked about a wide swath of topics. We, of course, talk about tech. One time, we spent 20 minutes trying to figure out the algorithm for set of flashing lights on a jukebox because they caught our attention. We've talked about bad managers, religion, sex, politics, marital challenges, parental challenges, what we love and hate about our city, how shitty the weather is, and how good the beer is, etc. There is no shortage of things for people in a group to talk about because we all are sharing the common experience of being alive.

It sounds absurdly philosophical to put it that way, but I do think it makes a difference. I think when you don't have an agenda in the conversation, you're able to let people engage how they are most comfortable. When they are comfortable, you get to know who they really are. It creates a space of vulnerability, and vulnerability is a key ingredient in developing friendships.

Anyone Is Welcome

Yes, our group has a lot of devs. Those are the people Jason and I know. But you don't have to be a dev to join. At the moment, we have a number of designers, product managers, and significant others who aren't in tech that attend. Just recently, a young woman studying for the bar exam heard our conversation and joined us. She's now joined us twice and I hope she keeps coming. It doesn't matter who you are and what you do because of the prior principle of "No agenda". There's always something we can find in common to talk about.

The "in group" of our gathering is just anyone who decides to show up on a given day. There's no one left out because of what they do or where they are in their career. This is really important. In fact, when a person enters the room and there's no obvious spot to join in, we try and break the group up in a way that gets a new small group formed around the newcomer so no one has to deal with awkwardly standing or sitting around. Everyone who comes gets to participate.

Conclusion

I know I haven't given you precise steps on how to do this, but the truth is, I think just trying to start it with a few friends is enough to get the momentum going. Pick a spot, gather regularly, invite friends. Then, if you really want, follow the principles I've laid out above. There's a good chance it won't be long until your gathering is doing well.

Oh, and one last note, don't worry about metrics like other meetups. A gathering like this isn't successful because of how many people come, it's successful because a few people got to connect and have a good beverage and conversation. That's the only metric that matters.

Alright, with that, I hope to see you at one of our gatherings if you're ever in Portland. We'll get to add your shining face to a photo like this one.

Firebase and Gatsby, Together At Last

Sun, 27 Jan 2019 00:00:00 GMT

If you look just above the title of this post, you should see a beard icon and the phrase ${strokes} bestowed. It's a fun little indicator of how many likes this post has received to date. I built this using a Firebase Realtime Database. For those of you unfamiliar with Firebase, it's a cool, JSON-based DBaaS (database-as-a-service) product from Google that I've used in a few other projects.

Firebase comes with a JavaScript SDK that's normally a cinch to hook up to a client side code. In fact, I had zero complications with combining Gatsby and Firebase until I tried to deploy my new feature. That's when things started hitting the fan.

A Missing `Window`

The first issue I ran into was when I tried to run a build. Gatsby ran into some issues with Firebase. I was really confused at first because Firebase was working just fine in Gatsby's development environment. I wasn't expecting it to crash and burn so badly when it was built.

Turns out that Firebase's initialization code makes a reference to the window object. This isn't a problem in development, because we're using Webpack's dev server. But running gatsby build is a bit different. window does not exist in the build environment and you have to be careful where and when you try to access the object. Firebase was crashing every build because it was trying to access a property on this non-existent object.

Ok, how do we solve this?

After going down a few wrong paths (and reading some Github issues), I landed on a solution I'm pretty happy with. I ended up changing how, more precisely when, Firebase was initialized in the application. At first, I followed a tried and true method for initializing the app that looks like this:

import firebase from 'firebase/app'
import 'firebase/database'

const config = {
  apiKey: process.env.FIREBASE_API_KEY,
  authDomain: process.env.FIREBASE_AUTH_DOMAIN,
  databaseURL: process.env.FIREBASE_DATABASE_URL,
  projectId: process.env.FIREBASE_PROJECT_ID,
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
}

firebase.initializeApp(config)

export default firebase

export const database = firebase.database()

With this strategy, I have a file, firebase.js, that initializes the app right away and exports the initialized firebase instance around the application. More importantly, it exports my database around the application to be used in whatever components need to hook up to it.

The problem with this strategy, as mentioned before, is that the window object is not available to the initializeApp method during the build process (not to mention, those environment variables aren't correct either, but I'll address that later in the post).

To solve this, I need Firebase to delay initializing until we're in the client side environment. But, I still want to have a single instance in the app and a way to export the database. This calls for a refactor that makes use of dynamic imports and a singleton pattern.

Let's make it happen.

Simple Functions to the Rescue

Often, I often find a simple function ends up being the best solution to a problem. First, I started by changing the code in firebase.js to look like this:

const config = {
  apiKey: process.env.FIREBASE_API_KEY,
  authDomain: process.env.FIREBASE_AUTH_DOMAIN,
  databaseURL: process.env.FIREBASE_DATABASE_URL,
  projectId: process.env.FIREBASE_PROJECT_ID,
  storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
}

let firebaseInstance
export const getFirebase = firebase => {
  if (firebaseInstance) {
    return firebaseInstance
  }

  firebase.initializeApp(config)
  firebaseInstance = firebase

  return firebase
}

We don't import any of the firebase packages into the module. Instead, we export a function that receives the firebase package as an argument. Inside this function, we check that an instance of firebase does not previously exist (held in closure by the module). If it does exist, return the initialized instance, otherwise proceed with initializing firebase and return it. This is the singleton pattern I mentioned before.

Now, in the components that need firebase, I can wait until the componentDidMount lifecycle method has been called, which guarantees that the window object exists. Once I can make this guarantee, I can then dynamically import the firebase modules I need and pass them into my function. The firebase instance is returned from the function, which I can then get the database from. That code looks like this:

componentDidMount() {
  const lazyApp = import('firebase/app')
  const lazyDatabase = import('firebase/database')

  Promise.all([lazyApp, lazyDatabase]).then(([firebase]) => {
    const database = getFirebase(firebase).database()
    // do something with `database` here,
    // or store it as an instance variable or in state
    // to do stuff with it later
  })
}

// I might update this with hooks once they're released officially.
// You'll have to come back and find out.

With this code in place, I can make reads and writes to the Firebase database from a component. I thought this would be the end of my problems. I was wrong.

Gatsby, Netlify, and Environment Variables

Now, before I go into this I want to make it clear, I read the documentation for all of these things: Gatsby's environment variables, Netlify's environment variables. I thought I had it all set up correctly. I did not. I ended up reading (and reading) the docs a few more times before I finally understood what I needed to do.

For those of you who might not be familiar with environment variables, let me give you a brief explanation. As the name suggests, these are variables that are exposed to a particular environment, such as development, test, or production. For example, you might want to have an API_ENDPOINT variable in your code that is different depending on whether you're in development or production. Thus, you inject these different values into the environment when it is instantiated, and they're made available to your code via the process.env object.

Environment variables are a great way to keep private code private (yes, I know it's not perfect, but bear with me. You can read up about the challenges of environment variables elsewhere). Gatsby and Netlify both have a way to inject these variables into your build. But there's a bit of a catch with Gatsby.

Gatsby makes a distinction between two kinds of environment variables. They call them "Project env vars" and "OS env vars". In my original implementation, I did not prefix my env vars with GATSBY_, thinking I understood how these variables worked. My code was working locally, my environment variables were correctly injected and Firebase was initializing, but I soon realized that none of my variables were getting injected properly in the production build.

I was baffled, I had also set up my variables correctly with Netlify. I double and triple checked them. Then, I read the docs again and realized that Gatsby will only make available "OS env vars" to Netlify's build. Thus I needed to prefix all my env vars in my project, in my local .env.* files, and on Netlify with GATSBY_. As soon as I did that, the build passed and my blog was back to working.

// adding `GATSBY_` made it all better
const config = {
  apiKey: process.env.GATSBY_FIREBASE_API_KEY,
  authDomain: process.env.GATSBY_FIREBASE_AUTH_DOMAIN,
  databaseURL: process.env.GATSBY_FIREBASE_DATABASE_URL,
  projectId: process.env.GATSBY_FIREBASE_PROJECT_ID,
  storageBucket: process.env.GATSBY_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.GATSBY_FIREBASE_MESSAGING_SENDER_ID,
}

Conclusion

Gatsby and Firebase will work great together, but you'll have to ensure that Firebase isn't initialized until the window object is available. And double check your environment variables setup if you're struggling to get them defined during Netlify's build of your app.

Best of luck if you run into similar problems. Let me know what you think of my solution on Twitter!

State Machines: The XState Visualizer

Thu, 24 Jan 2019 00:00:00 GMT

I made mention in my "What Are State Machines?" post of the fact that a state machine is a graph data structure. Each state a node. Each transition an edge triggered by an event. You remember, right? No worries if you don't, now you know.

I also mentioned you can do cool things like create a graphical representation of your state machine because of this data structure. Well, I have good news. XState has a state machine visualizer tool.

The XState Visualizer allows you to see your state machine in action, which might be really handy for those of you who grok things visually. Let's take a look at it.

Open up the XState Visualizer in another tab with this link: https://statecharts.github.io/xstate-viz/. You'll see an example of a stop light in the visualizer by default. On the left, is the graphical representation, and on the right is the code to produce that representation.

On the left, each "box" represents one of our states. The initial state is indicated by the "dot and arrow" you see pointing to the "green" state. The highlighted state (indicated by the blue color), is the state the machine is currently in. The buttons inside each box will trigger the event with that name, and move it into the state it points to with the arrow. Give it a try.

Clicking the "TIMER" button will move the state to "yellow". Notice that the state and buttons that are not enabled become gray. You can continue to click event buttons to move the state along.

Another way to trigger events in the visualizer is manually in the "State" tab in the panel on the right. Click into the State tab, and you should see several items: Value, Context, Actions. At the bottom of the tab is an area for Events, where you can write your own and trigger them with the "Send Event" button. Since the light machine only has one event, try sending the TIMER event and watch the state update.

Just like clicking the event buttons inside our state boxes, sending events manually also updates the state. I'll discuss the extra parts of this tab, context and actions, soon.

Now that you know the basics of using the visualizer, try it out and get a feel for it. If you don't know where to start, why not start by copy/pasting the code from the elevator example in my "Our First XState Machine" post. Update the elevator as you go. Can you figure out a way to add an open and closed state to the elevator doors? Better yet, figure out how restrict the elevator to only moving up and down while the doors are closed. Send me your answers on Twitter when you do!

State Machines: Our First XState Machine

Tue, 22 Jan 2019 00:00:00 GMT

import { Elevator } from './_Elevator'

In a previous post, I explained what a state machine is and how to build one from scratch. In this post, we're going to learn how to make our first state machine using the XState library. First step? You guessed it. Install the library into your project.

npm install --save xstate

Next, we're going to get the Machine function and the interpret function from the library. These functions are very similar to the ones I made in the other post, so these might seem familiar.

import { Machine } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

Now, let's create an example. I'm going to use the same example that I used in an egghead lesson I made to introduce this topic, an elevator. Specifically, a single elevator box.

The box of an elevator can have three possible states: stopped, moving up, or moving down. Let's start configuring our elevatorMachine with these states.

import { Machine } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

const elevatorMachine = Machine({
  states: {
    stop: {},
    up: {},
    down: {},
  },
})

Let's give our machine an initial state of stop next.

import { Machine } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

const elevatorMachine = Machine({
  initial: 'stop',
  states: {
    stop: {},
    up: {},
    down: {},
  },
})

Now, we need to define the transitions for each state. For each state of our elevator machine, we can transition to the other two possible states. With XState, we define these using a state's on property, like so:

import { Machine } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

const elevatorMachine = Machine({
  initial: 'stop'
  states: {
    stop: {
      on: {
        UP: 'up',
        DOWN: 'down'
      }
    },
    up: {
      on: {
        STOP: 'stop',
        DOWN: 'down'
      }
    },
    down: {
      on: {
        STOP: 'stop',
        UP: 'up'
      }
    }
  }
})

Now that we've enumerated our states and event transitions, we can use the interpret function to make our machine useful. This function will allow us to define an action to occur for each transition, as well as start the machine itself.

import { Machine } from 'xstate'
import { interpret } from 'xstate/lib/interpreter'

// ...previous code for our machine

const elevatorService = interpret(elevatorMachine)
  .onTransition(state => {
    console.log(state.value)
  })
  .start() // 'stop'

Now we can use the send method on our elevatorService to send events and update the state.

elevatorService.send('UP') // 'up'
elevatorService.send('DOWN') // 'down'
elevatorService.send('STOP') // 'stop'

Now, what happens if we send an event that's not one of the enumerated possibilities?

elevatorService.send('FOO') // 'stop'

Absolutely nothing! Which is exactly what we want to happen. Only defined events should have an effect on our machine. That being said, you might be the sort of person who wants to throw up a red flag, so to speak, when something like this might occur. In that case, XState machines can be put into strict mode. In strict mode, a machine will throw an error when a non-enumerated event is sent.

const elevatorMachine = Machine({
  strict: true,
  // ...the rest of the machine configuration from before
})

// ...and all the interpreter code from before as well
elevatorService.send('FOO')
// Error: Machine '(machine)' does not accept event 'FOO'

Whoops! XState didn't like that. An error was thrown indicating an unaccounted event was attempted, but the error message leaves something wanting. Wouldn't it be nice to be able to identify what machine broke in the message? This is where giving a state machine an id can be really handy.

const elevatorMachine = Machine({
  id: 'elevator-1',
  // ... the rest of the machine configuration from before
})

// ...and all the interpreter code from before as well
elevatorService.send('FOO')
// Error: Machine 'elevator-1' does not accept event 'FOO'

And with that, we've finished making our first state machine with XState. I hope that you find this helpful as you get started using the library. I'll cover all the important parts with more depth soon.

If you'd like to see some of this code in action, you can check out this quick CodeSandbox I made below. Using only plain JavaScript, I added some buttons and a little "elevator" that the state machine controls. Try it out. I recommend hitting the "DOWN" button first, the elevator will go through the roof if you don't!

State Machines: What Are They?

Mon, 21 Jan 2019 00:00:00 GMT

Defining and managing state in software is a difficult challenge. Even simple systems can often be more complicated than they first seem. State machines provide a reliable interface for handling these systems and are capable of handling problems from the simple to the highly complex.

A state machine, more specifically a finite state machine, is an API that enumerates all the possible (and thus finite) states of a system. For each of these states, a set of events is enumerated which defines the possible transitions between states. A state machine can only ever be in a single state at a time and is only transitioned to a new state by an event.

By defining all the finite possibilities of our machine's states and events, we create a graph data structure describing our system. Each node represents a state, each edge a possible event from that state. There are a lot of cool things we can do with state machines because of this (like auto-generating visualizations of our system) that will be covered in future blog posts.

A Simple Example

Let's consider a very simple example, a light switch. A light switch has two finite states, an on state and an off state. Let's write a rudimentary form of a state machine representing a light switch in JavaScript as we go. You can follow along in an online editor such as CodeSandbox or JSBin if you'd like. I'm going to use whatever data structure comes naturally to me and make changes as necessary. Since we're listing out states, let's start with an array.

const lightSwitch = {
  states: ['on', 'off'],
}

A state machine also requires an initial state, so let's add that as well. We'll set our switch to 'off'. We should be energy conscious with our example, of course.

const lightSwitch = {
  initial: 'off',
  states: ['on', 'off'],
}

Now, for each of these states, we need to define possible events. That is, when a transition is attempted with a given event, what state should we derive next depending on the event? In the case of a light switch, there really is only one event, SWITCH. This SWITCH event transitions our machine to the opposite state.

Since these events correspond with each state, an array no longer serves our purposes well, so we will use an object instead. Each key in the first level of our states object will correspond with a possible state of our machine. Each state will then have an events object enumerating the possible events for that state. Each key in the events object will be the name of our event, in this case SWITCH, and the corresponding value will be the name of the next state.

const lightSwitch = {
  initial: 'off',
  states: {
    on: {
      events: {
        SWITCH: 'off',
      },
    },
    off: {
      events: {
        SWITCH: 'on',
      },
    },
  },
}

Now that we've enumerated the possibilities of our light switch, we need a function that can take a machine, interpret it, and give us back the correct state. Thus, let's implement a state machine interpreter.

Our interpreter will take a machine as an argument, and expose a set of methods that can be used to get the current state of the machine or attempt a transition on the machine.

const interpreter = machine => {
  // We store the current state in closure
  // keeping the value in memory
  let currentState = machine.initial

  return {
    currentState() {
      return currentState
    },
    transition(event) {
      // Since we enumerated all possible events
      // for each state, our next state is either
      // the defined state for that event,
      // or it is undefined, and thus we can
      // return the currentState
      const nextState =
        machine.states[currentState].events[event] || currentState
      currentState = nextState
      return nextState
    },
  }
}

Now we can use the interpreter on our lightSwitch machine and see it in action.

// ...code from before
const mySwitch = interpreter(lightSwitch)

// Try the current state
console.log(mySwitch.currentState()) // 'off'

// Try a defined transition
console.log(mySwitch.transition('SWITCH')) // 'on'

// Try an undefined transition
console.log(mySwitch.transition('FOO')) // 'on'

As you can see, our rudimentary machine and interpreter creates a pretty solid interface for managing the state of the light switch. Our light switch can never get into a "bad state", and it's completely inert to events that we have not defined. This should give us a lot of confidence in our application.

We can easily add methods and properties to this interface to enhance its functionality, too. For example, we could add a method to the interpreter to return all the possible events for a given state.

// ...inside the object returned from `interpreter`
allEvents() {
  const { events = {} } = machine.states[currentState]
  return Object.keys(events)
}

// ...further down
console.log(mySwitch.allEvents()) // ['SWITCH']

There are a lot more possibilities to enhance this rudimentary state machine, but I'd rather focus on a real state machine library in future blog posts. As I continue to write and explore this topic, I'll start using the XState library by David Khourshid. I encourage you to check it out and read up on it in the meantime. David's talk at React Rally is what initially inspired my interest in state machines and is something you should definitely watch. Alright, see you in the next blog post!

// Let's not leave the light on
console.log(mySwitch.transition('SWITCH')) // 'off'

Why I Rewrote My Blog With Gatsby

Wed, 09 Jan 2019 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

A couple weeks back now, I was starting to write a blog post to recap my 2018. I thought it would be a good idea to reference my goals for 2018 and started to review that post when I discovered something interesting. As I was reading a paragraph, I noticed some words that didn't sound like my voice. As I read further, there was a link to an air compressor. I assure you, I don't own an air compressor (yet) and I certainly would never put it in my article about my 2018 goals.

That's when I realized that I had been hacked. Fuck.

Here's a tweet thread regaling my woes that evening as I discovered the hacker had been changing my posts for four whole months!

I never did find the exact point of weakness that the hacker used to get in and mess with my stuff, but I suspect it comes from my inattentiveness to updating plugins and WordPress itself. It would be nice to be able to trust something like that to be secure, but it seems weaknesses are found and exploited regularly.

I took the steps of changing all my database users and their passwords (including the root user), repaired all the damage that was done and then some. But after doing all this, there's still no guarantee that 1) the intruder had been locked out of the system and 2) that this wouldn't happen again when I forgot to update a plugin a month from now. This put me in a tough spot.

On the one hand, I really don't like rewriting my blog, or even putting that much work into it. I like it functional and simple and that way I don't waste time rewriting it every year. I think devs everywhere waste a lot of time in this fashion, when they could put that time and energy to much better uses.

On the other hand, I now have a blog that's weak and vulnerable. It's irresponsible of me not to try and remove attack vectors if I can.

So I bit the bullet, and decided to rebuild my blog on Gatsby, and let me tell you, it was a blast!

Overall, my experience rewriting the blog (and streaming it while I did it) was really positive. I hit a few snags, but for the most part, there was always someone or some good documentation that was available to help me get through it. I think I was able to complete the rewrite in under 30 hours, which is pretty good.

What's great about having done this is that now I have a much more comfortable framework to make updates to the blog. You may notice a few improvements around here. My face is now at the bottom of each post, my latest egghead course is now present at the bottom of each page. I already have plans to add features such as pages to sell courses and workshops and more. I think Gatsby and it's vast ecosystem of plugins gives me a ton of power and flexibility, all while being really safe. No more updating plugins. I just build the site and host the static pages. It's quite amazing.

On top of that, I moved my hosting to Netlify which means I don't even have to pay for a server anymore. I am going to save $60 bucks a year by making this change. That's pretty cool if you ask me.

In the near future, I'll write more in depth about my process of converting the blog and make a few posts about Gatsby and Netlify. Should be a lot of fun.

Let me know if you have any questions about Gatsby on Twitter. Happy to help if I can!

The Importance of Competing Thoughts

Sat, 10 Nov 2018 00:00:00 GMT

Before I dive into this idea of mine, I want to tell you, I've been scared to write it out. It's been in my head for a few months, but I'm genuinely nervous to share it with others. I don't know how you're going to receive it. Hopefully well, because I'm going for it.

Some of you might know, I was a pretty good college golfer. For about 8 years of my life, my only real goal was to be a professional golfer. That didn't end up working out (I'm honestly kind of glad it didn't now, but it really hurt at the time.), but it did provide me with a lot of lessons to draw from that are useful in everyday life.

One of those lessons is this: in golf, and sports in general, in order to perform your very best, you have to be able to hold pairs of competing thoughts in your head. You have to completely and sincerely believe both, potentially paradoxical, concepts simultaneously. Here's an example:

When you are competing and performing, you have to believe fully that if you are on a "hot streak", that that streak will never end. You also have to believe that when you are having a "cold streak", that you can turn it completely around on the very next shot.

All hot streaks come to an end. All cold streaks come to an end. Averages exist because, over time, we perform... average. But, if you want to max out a hot streak, get everything you can out of it, the only way to do it is to block out the absolutely logical thing to think, "This could end at any moment." You must commit yourself to the fact that you cannot miss, that you have the hottest hand, and there is no end in sight. The moment you think about the streak or doubt yourself, it's likely over.

The same goes for when you're playing really poorly. If you're playing badly, it's likely there are errors upon errors compounding, some mental, some physical, and many of which you don't even fully understand. But, in order to get out of it, you have to think as positively as humanly possible. You have to block out any thought that says you're going to continue to screw up as you have. You have to fully believe the fact that you'll snap out of it, even though there is no evidence at the moment that you will.

I think learning to hold competing concepts in your brain has a lot to do with how you can be successful at any venture, including being a good software engineer.

I have had one of these competing thoughts on repeat in my brain for several months that is helping me keep myself in check. It's been helping me get refocused and progressing towards my goals. Those thoughts are these:

There are almost 7.8 billion people on the planet, I am completely unique.

There are almost 7.8 billion people on the planet, I am not special.

I am unique. I am the only combination of these genes that exists or will exist in the known universe. I find joy in the qualities and personal philosophies that make me me. Why shouldn't I? I believe that the value I offer to the world stems from, at least in part, the unique person I am. I bring something to the table no one else. Not sure what that is, but it's something. That being said, I can't let my uniqueness lead to a false belief of superiority or entitlement.

With so many people on the planet, it is highly unlikely that I am actually all that unique. Practically, every combination of person and personality exists. I might work hard, but guess what, there are many who also work hard, many who work harder. I might be smart, but guess what, there are many who are smart, and many who are smarter. If I want to achieve some goal in life, I have to be willing to believe that I am not special, that I don't deserve to achieve those things by merit of simply being who I am, or believing the things I do. This is the nature of entitlement. That we have earned things we haven't. Deserve things we don't. No, I have to be willing to put in the work to achieve those things. If I don't work hard, at least one of the other 7.8 billion people on the planet will work that hard. Probably even harder.

Now, I'm not suggesting that we all become workaholics, that would contradict the opening of this newsletter. I stand behind what I said. We all deserve breaks. But the work that you need to do won't magically get done either.

You need to hold two competing thoughts. You are special. You have value. You bring something to the table that others don't. This will help you find that job, get that promotion, foster a new opportunity.

You aren't special at all. You're just another human being, trying to make the most out of their time on this planet. If you want something, you have to do the work to get it. You don't deserve it just because of who you are.

I have been saying these things to myself a lot lately. I have something to offer companies, people, the industry, the community. I have a unique voice to share and it is worth something.

But I'm also just a person. A person who needs to stay focused and decide what I want in life and go after it because a great life isn't just going to appear.

You might need to tell yourself the same. You are special. You are like everyone else. You're awesome. You're ordinary.

There's nothing wrong with holding two, or even three or more, competing beliefs. The key is knowing what belief applies to what. If I say that I'm special and thus deserve a raise without doing the work, then I'm entitled and just an ass. If I devalue who I am as a person because I don't believe I have anything special about me, then I hurt myself.

I'm guessing that some of you do the same to yourself, too. Remember, I'm not that special. I'm probably not the only one.

The Role of Timing In a Job Hunt

Wed, 10 Oct 2018 00:00:00 GMT

In my last blog post, I shared with you several tips on how to make that hunt go better for you. We talked about how shifting our mindset to "seeking offers" instead of "getting a job" puts us in a position to "explore" rather than "judge". We need to explore many paths and options when trying to find the next step in our career. This week, I'm going to continue to discuss the job hunt by sharing an anecdote from this week and how that might relate to you.

When I initially put the word out that I was looking for a job, a friend I made at React Rally 2017 reached out with a great opportunity. The position was for a company whose product I really respect. I could see myself actually caring about it and even evangelizing for. I don't say that about a lot of products. Their technology stack fits perfectly with my skill set. It was a Bay Area company (good salary!) but I could work remotely (no relocation!) which is, in my opinion, the best combination. Not to mention I'd be working with a friend.

We schedule a time to hash out the details of the position. The day comes, we chat, and we feel really aligned. This could be a great fit. He starts working it up the chain to his manager. Gets the go ahead to proceed from them. Works it up one more level. Gets the go ahead from them.

But it had to go up one more level.

And it didn't get the go ahead from them.

My buddy gets back to me with the bad news. So and so doesn't want to hire any remotes at this time. They also don't want to revisit the idea until Q2 of next year. Obviously longer than I can wait.

Shit.

Now, I'm not going to dwell on this much longer than it takes me to write this post to you all, but it demonstrates an important part of a job hunt—timing.

I believe that we give our industry a tad too much credit for being meritocratic, that is, advancement is based upon what you have done and accomplished. There's certainly some element of meritocracy, it's not often that someone completely inept lands a coveted position for very long, but there are plenty of other variables at play in who gets which job in our industry.

One of those variables (and there are many) is timing. This could be your timing, their timing, or even someone else's timing. And if you don't learn to roll with it, it can really wreck you.

Your Timing

Are you ready for a dream opportunity if it landed at your feet tomorrow? Do you have the skills you need? The experience you need? The network, the clout, the authority you need to seize it?

Maybe you do. Maybe you don't. Whether or not isn't my point. My point is that if you aren't prepared for a job when it's available, then that job isn't available to you. Even if you'd be great at it in 6 months, a year, or more.

Their Timing

As my anecdote explains, even if you'd be a great candidate for a job, doesn't mean that they are ready for you to be a candidate. If you're new to these job hunts, and I suspect some of you are, you might hear the term "head count" thrown around. This is a way of describing how many people a team can hire at a particular time. As in, "We really like you, but we just don't have head count. I might be able to add a few heads in 4-6 months. You should try again then."

Sucks, but it's out of your control.

Someone Else's Timing

When you're seeking offers, it's easy to forget that you're actually competing for a limited resource against unknown third parties. Your timing could be perfect. The company's timing could be perfect. But if someone with a superior skill set, better cultural fit, or cheaper salary requirements (and a host of other possibilities) comes along at the right time, then your timing isn't really so perfect.

Shit. Again.

This happens, too. The difference between this and the "your timing" category is where the locus of control is. You control how ready you are for opportunities by working on your skill set and network. This is an internal locus of control. Everything to prepare yourself comes from within you.

You can't shape who does or does not apply for a job. Well, perhaps you could by nefarious means, but don't do that. Not cool. This is an external locus of control, it's outside of you and not one you can change.

How Do We Respond?

When bad timing occurs, there's very little you can do to change the immediate situation. It sucks, but it's a fact. However, we can be prepared for it. Something like this will likely happen to most of you at some point in your career, so here's my tips for being prepared.

Respond Professionally

This is an absolute must. Don't whine to them. Don't complain to them. If this happens to you and you respond poorly, it only hurts you, it does not help you.

By responding well, you may impress them. You might be remembered for a future opportunity. Plus, in the scenario where someone else beats you for the job, they might not accept the offer, and they may come back to you. Keep this in mind.

Don't Worry About It

The variable of timing in a job hunt means that there is a significant amount of luck involved in finding the right job. That being said, this pendulum swings both ways. Assuming that you are a qualified candidate, skilled at your job and hard working, then you will likely benefit from timing as often as you will suffer from it. Keep your head up when the pendulum swings away from you. Figure out how to move forward. You're seeking offers and there are more out there.

Coda

Random segue, but if you know what a coda is in music, you might get how this applies here. A coda signifies we've reached the end, but we're going to cycle back to another point. The job hunt is often cyclical. You'll probably be in this boat again. You might be on the hiring end of this equation at some point. Try to keep this in mind next time you find yourself in a job hunt.

How to be More Successful on Your Next Web Developer Job Hunt

Fri, 28 Sep 2018 00:00:00 GMT

If you follow me on Twitter, you may have seen this tweet go out into the universe. I'm in the process of exploring the next part of my career and asking you all to help me do that by spreading the word. Don't think spreading the word can make a difference? It totally can.

Just this past week, a junior dev I've been helping in his job hunt landed his first dev job! I used my network and made a tweet promoting his background, skillset, and hard work and it paid off. A company reached out to him, he nailed the technical interview, and now he starts in a few weeks. All because a tweet connected some people! Trust me, spreading the word can help, and I'd appreciate whatever support you could show me (if you haven't already. Much love to all of you who have!).

Putting oneself out there, into the job market, can be one of the most nerve wracking parts of one's career. Whether it's your first job, your second, or your tenth, being in the hot seat and under scrutiny can be really uncomfortable. No matter how many times you've done it, I don't think you can get rid of the nerves entirely. However, I think there are a few changes you can make alter your mindset and get more offers. So here are my tips to help you be more successful at job hunts.

Stop Trying to Win the Resume Lottery

There's this game that so many people play that I like to call the "resume lottery". People throw their resume and cover letter into a giant pile of other resumes and cover letters and hope and pray that somehow they stand out. It's nearly impossible to win this game. I mean that literally. According to Designing Your Life, a book I've been loving lately, their research suggests that playing the "resume lottery" has a success rate of about 5%. That's horrible!

Why is that percentage so low? Because as much as 80% of job openings never make it to a job board. When they do, they aren't always really open. Often, they have a candidate in mind that they've customized the opening for in order to appease HR. On top of this, according to a 2015 report, 52% of managers admitted to responding to fewer than half of people who applied for a position. What chance do you have of winning the "resume lottery" up against those odds?!

You can keep playing the game. You can submit hundreds of resumes. Sure, you'll get a few bites, but you'll learn almost nothing from your failures. There's no feedback mechanism, no incentive for those companies to help you improve. All the while, you're not building up a network, you're not gathering new information to act upon, and all you're left with is an empty inbox. What on earth are you supposed to do?

Try smarter, not harder.

Playing the "resume lottery" is insane. You need to lean upon your "weak ties", people whom you know, but aren't in your innermost circle ("strong ties"), to help you create "warm introductions". Most job placements come through referrals, and that's precisely what a warm introduction can do for you. Learning how to build up connections and get these referrals helps tremendously. So how do you do that?

You need to start doing "informational interviews". These aren't really interviews, they're conversations. You reach out to people who are doing a job you're interested in and you ask them to tell you about it (of course, with kindness, politeness and a little bit of charm if you can muster it). It's really that simple. People like talking about what they do! They'll tell you all about it, and you'll gain information. As you listen and respond, you'll be able to figure out 1) whether or not what they do is something you're interested in, 2) be able to share some of your own passions as you respond to them, which will help them unconsciously begin to see where you might fit, whether on their team or someone else's team they know, and 3) you'll begin to access their weak ties, thus expanding your own.

These weak ties, these connections, they're your way to more opportunities.

You're Not Looking For a Job, You're Seeking Offers

I'm going to be honest, I'm ripping this straight from Designing Your Life, so give them all the credit. That being said, this tip is really helping me have the right mindset in my search.

You need to reframe your thinking from looking for a job to seeking offers. It's going to change your approach entirely. When you're looking for a job, you're fixated more on doing what it takes to get a job, instead of exploring whether or not the job is any good for you. Exploration is the key.

There isn't a perfect job out there, not one just waiting for you at least. There are probably a number of jobs you'll do great at. Knowing this, knowing you don't have to get this job, but rather you're trying to give yourself options with many offers, means you can be your authentic self in an interview. You aren't trying to conform to them, instead you're on a path of discovery, you're learning things about them, you're focused on whether or not this fits with your goals, your personality, your aspirations.

When you're seeking offers, everything becomes an opportunity. Every conversation and interview, at the worst, still provides you with information and probably connections. And here's the thing, when you're relaxed and not focused on getting just this job, you'll do better at the interview in general, which will lead to more offers.

Even if you're just starting out in the field, you need to believe this, because it's absolutely true: You are capable of doing a good job at many places. There is no one job that will be perfect, no one interview that will make or break your career. If that was the case, then the only successful people would all have had the same path to their success, right? So dismiss that rubbish (sorry, I've been watching a lot of the Great British Baking Show and all my swears are somewhat Anglicized at the moment) and realize that your best chance at landing a great job is having a bunch of offers.

The other great thing about seeking offers is it immediately triggers your creativity and curiosity. You'll be amazed at how some of your informational interviews might lead to offers because of your creativity and curiosity.

Hope these tips help! Tell me some of your best tips in a comment down below!

3 Tips for Changing Your Career to Coding

Sat, 15 Sep 2018 00:00:00 GMT

Friday night, after React Rally 2018, I led a group of intrepid devs to Beer Bar in downtown Salt Lake City for what I like to call "the unofficial after after party". Our group was quite large, so we ended up divided amongst two large tables. Our particular table only had a handful of our group. It was Chris Ball, Gabe Ricard, and myself. The other half of our table was eventually filled with total strangers.

The strangers were legitimately nice. Asked if they could sit there, which of course they could, and then each of them introduced themselves and shook our hands. Very pleasant introductions all around. We settled down and they start talking in their group and we go back to talking shop amongst ourselves.

A little ways into our conversation, one of the strangers, Kevin was his name, hears us talking about coding and politely interrupts us, "Wait a minute, are you all programmers?!"

"Yup. We're here for a conference," we reply with a calmness that belies how excited we are that someone outside of tech is excited about what we do.

"Woah! That's crazy! I'm considering getting into web development and learning JavaScript. What's your best advice for someone like me?"

This is where Gabe gets all excited for me, "You have no idea how lucky you are to be sitting here," as he points at me. "This guy has a whole podcast about people who have made the change to web development!"

So I told Kevin my best tips, none of them coding specific, and now I'm going to share them with you.

1. Be Ready to Bang Your Head Against a Wall

Learning to code requires a lot of persistence. The only way you'll gain the skills to make the career change is to have the gumption and stubbornness to push through those times where you feel completely and utterly stuck. Sticking with it and overcoming the challenge before you is the only way to achieve your goals.

A guitar player is not ashamed to play the same chords over and over again in order to learn a new song or skill. Don't be afraid to write the same code over and over again until you completely get it. Don't be afraid to read that tutorial two, three, four, five or more times to understand it fully. That's how you make breakthroughs and start heading for your next wall.

2. Be Ready to Constantly Cycle Through Feeling Like a Genius and Feeling Like a Dumb Ass

Every programmer out there is familiar with feeling like a genius one moment and a complete dumb ass the next. This cycle repeats continually throughout one's career. The difference between the newb and the seasoned veteran is that the vet has done the cycle so often that they no longer fear it, and in fact embrace it.

Being a developer means going through waves of competency and struggle. As painful as the downswings might be, it's a clear indicator of previous growth. Being aware of this phenomenon, and being mentally prepared to handle it, will keep the bad parts of the cycle from crushing you. Awareness has the added benefit of keeping you humble while on your next upswing.

3. It's Probably Going to Take Longer Than You Thought

We've all heard the story of so-and-so who was able to change their life entirely in just three months. That spunky person who went from minimum wage to six-figure salaries overnight, all by learning to code.

This is the exception, not the rule.

The rule is you will in all likelihood, eventually make a pretty good salary. The rule is you will likely get benefits you enjoy and find some decent challenges to overcome. But it often doesn't happen overnight.

I think you should expect to put in about a year and a half of solid coding, that is doing some amount of coding, deliberate practice, most days for that time. It's not that you're not smart enough or capable enough sooner, but that a year and a half is about the amount of time it often takes to be comfortable enough with your new skills to pass an interview, build up enough projects to prove your new skills, and probably build up a network enough to even have places to apply. Be patient with yourself. You can do this.

Bonus Tip: Start Networking Right Away

Speaking of networks, you should be doing this from day one. Networking isn't a sleazy thing to do. It's not just about helping yourself, it's about recognizing that everyone needs someone sometime. You may need help now, but soon enough someone will need your help instead.

I recently read a great analogy for networking in the book Designing Your Life. Networking is more like asking for directions than asking for handouts. Almost everyone is more than willing to help someone else find their way and feels good about doing it. Have some faith this.

You can start networking by participating, not just lurking, in conversations. You can reach out for informational interviews, aka conversations where you ask someone to tell you about what they do. You get the benefit of learning details you can't learn otherwise while building up professional relationships. That's a win-win situation.

Conclusion

Making a career change is challenging. It's going to require persistence, patience, and probably some outside help. Don't be afraid to ask for it. Start developing relationships as soon as possible with people in the industry, it might lead to your next opportunity.

I don't normally do self-promotion in my material, but if you want to listen to a podcast devoted to this topic, check out my podcast Second Career Devs, where I interview people who have made the career change to software engineering or web development and share the lessons they learned along the way. Thanks.

Let Me Tell You About This Cat

Tue, 21 Aug 2018 00:00:00 GMT

The events of this story took place several months ago, but let me tell you, they are as vivid to me now as they were then. It's going to sound a bit ridiculous, but I had a chance encounter with a cat that I don't think I'll forget for the rest of my life. I'm hoping you'll find the story quite impactful as well.

One day in the late spring, I was coming home after having run an errand. I live in a two bedroom apartment on the second floor of a small complex. Our apartments are all connected by a wooden deck that meanders between two buildings. Our apartment, in particular, is around a bit of a corner with our entrance being the only one on that side of the building. It awards us a degree of privacy that the other apartments don't have. It's quite nice. It also means I very rarely run into unexpected people or things as I come around the corner to my front door.

So I'm coming home from my errand, walking briskly as I do, when I turn the corner and, to my surprise, see our neighbor's cat, Bullet, lying next to our front door.

I wasn't totally surprised. Bullet was an outdoor cat and over the last few years, he and I had enjoyed a few minor pet sessions together. Bullet was the old-timer of our apartments. He was 18 years old, pretty skinny at this point. His eyes were a bit occluded and often seeped of some form of fluid. He wasn't a sight to behold, but he was a good cat who often wanted nothing more than to be let inside his home (something I could never do).

I say to him, "Hi, Bullet!" and he immediately meows back at me. I walk up to my door, expecting him to leave, but he doesn't. He continues to meow and starts to rub against my legs as cats do. I set my grocery bag down and bend down to pet him. On this particular day, though, he's quite insistent. He keeps meowing at me. Again and again.

I eventually get the idea and I sit down on the deck, cross-legged. I'm barely to the ground when he climbs into my lap starts to curl up. Bullet has never done this before, never shown this level of affection, but I'm not one to refuse him this.

As he nestles in and I start to pet him, I notice that the sun is shining on us, creating a nice spot of light on top of him, warming up his thinning, gray fur. I can feel the heat upon him as I pet his side.

Perhaps a minute or so into this, Bullet begins to purr. This isn't a soft purr, one that can be barely heard like my own cats. This is loud. Loud enough to guarantee others heard it. I could feel the vibrations of his chest upon my legs as he did so. It's about this point that it dawns on me what is going on.

I start bawling.

As I said, Bullet is a much older cat. He's not in the greatest of health. Under-nourished. Tired. Alone. And now, out of nowhere, he is curled up in my lap, enjoying some pets to the fullest.

All he is trying to do is get a little bit of joy and pleasure out of the last few moments or days of his life.

He knows that the end is near, and he just wants a few minutes of sunshine and good pets before it's over. He's just trying his damndest to get something good out of this one and precious life.

I'm bawling as I write this.

We stay like this for about ten minutes. Him on my lap, me crying, sitting in the sunshine. As I stroke his rough fur again and again, I think about how much I understand him. I, too, want to have a little more joy and pleasure in this life. I, too, want to sit in the sun and feel the affection of another (or some similarly equivalent pleasure). I want to have more happiness in this life. To live the best I can with what I have.

That's really all most of us are trying to do. Almost every creature in the entire universe is trying to do the best they can.

Even the shitty ones.

The universe consists of limited creatures with their limited knowledge and their limited resources and their limited lives, striving to make something "good" for themselves.

I have to put "good" in quotes, because this is not some objective goodness. It's entirely subjective. I don't mean to imply that every creature is pursuing an ultimate good, the summum bonum. Rather, that most are pursuing a "good", even if that "good" is quite awful.

In those ten minutes, I was overwhelmed with compassion, with empathy for others. I understood others better on a fundamental level. Even people I vehemently disagree with, perhaps even hate, I understood now more than ever.

All because a cat sat in my lap for some pets in the sunshine.

Eventually, a cloud passed in front of the sun. Bullet took this opportunity to get up, perhaps to pursue another patch of light elsewhere. As he departs, I say, "Goodbye."

Bullet died two days later.

From Pastor to Programmer

Mon, 05 Feb 2018 00:00:00 GMT

I am often asked to share the story of how I went from being a Christian pastor to a software engineer. Now that I've started Second Career Devs, I am being asked this question so often that I thought it wise to write it down and answer it once and for all.

Where I Believe the Story Begins

Unlike many people who eventually find their way to programming, I never did any programming as a kid. I had a computer, a Commodore 64, but I mostly used it to play games and write stories. In other words, I don't think anyone suspected that I would wind up where I have.

I was an excellent student, albeit, an easily bored one (really, I am just an easily bored person). I slept through most of high school while still getting straight A's. I didn't really care about the grades, though. I was mostly concerned with athletics at that time in my life. That is a story for another time.

Because I was solid in all my classes, there was no particularly clear path for me to choose after high school. The irony of being good at many things is that it can sometimes make choices more difficult. You have more options than you know what to do with and a fear of choosing wrongly can be overwhelming. A bunch of my friends were going to pursue engineering, and I thought that would work for me, so I headed to college with a vague plan of becoming an engineer.

College mathematics continued to go well, but the work became incredibly tedious. I abhor tedium. It is something for which I have no patience. I began to grow increasingly tired of math homework that would only be a couple of problems, but would take multiple hours to complete by sheer volume of steps required. My instincts would tell me, "Computers will solve all these problems for me on the job. Why do I need to do this by hand?" Thus, I started to drift away from mathematics.

At the same time, I took my first philosophy course. I was immediately hooked. I had always been a thoughtful person (more in quantity than quality), frequently scolded by my peers and for "thinking too much". Suddenly, I found an area of study that matched my overly cognitive demeanor. This led me to make what I consider to be one of the worst decisions of my life, but I switched directions to become a philosophy major.

How Philosophy Lead to Theology

I earned athletic and academic scholarships to attend Lenoir-Rhyne University in Hickory, North Carolina and transferred there my junior year. The Southeast was quite the culture shock for me. I had never visited before my transfer and didn't know what to expect. One of the biggest culture shocks was moving right into the heart of the Bible Belt. I had never seen such overt religiosity in my life. While I was raised in a Lutheran church and considered myself a Christian, I did not share the same passion for Jesus as many of peers and elders did. It was eye-opening and life changing.

One night, late my junior year, I had an epiphany of sorts where I felt overwhelmingly compelled to devote myself to Jesus and his teachings. I became highly involved in a local church and various campus ministries. This was really the beginning of my ministry career.

Studying philosophy trained me to be excellent at critical thinking. I was also a pretty naturally gifted public speaker (I like talking a lot). Thus, I enjoyed the challenge of reading and deducing interesting insights from the Bible and sharing them with others. With these gifts and talents, I was both drawn to and encouraged to pursue a career in ministry.

I can't emphasize the "encouragement" enough. Looking back at that time from my current vantage point enables me to recognize just how much peer pressure shaped the next eight years of my life. There was an incredible amount of pressure put on me by others, and my own sense of guilt, to use these skills "for the Lord." As in, if I didn't use these skills in the church, that I would be squandering them, or even worse, committing sin. I, of course, didn't want to be a sinner and so it seemed like I was destined to be a pastor.

After college, I spent a year in a volunteer organization where I practically lived in a van with five other people, driving around the United States doing youth and worship ministry. We covered ~60,000 miles that year. It was a challenging time for my team. We started as a group of six, but only three of us, including me, stayed with the program for the entire year of service. After this time of volunteering, I continued following the natural path of ministry and became a pastor of youth and worship ministries for a small church in rural Illinois.

I took this job at the same time that our country entered the Great Recession. As you might imagine, this wasn't a good time to work for an organization that depends upon donations to survive. My time at the church was quite short, just over a year, and finances played a big part in just how brief my tenure was.

Because of the recession, the congregation had less discretionary money to tithe to the church. Less tithing means coming up short on budget. But it wasn't just the recession that was preventing people from giving. They also were less encouraged to donate because there was a general displeasure with the new pastor the diocese had assigned to the church.

This was the first time I really understood how money is power and how the intended target of an attack is not always the one who gets hurt. My church was unhappy with the head pastor. To hurt the pastor, they withheld their money. However, I being the lowest person on the totem pole, was the one who lost their job. With very little notice, I was told I was being let go. My final day at that church was Easter Sunday of 2010.

By then, I had become convinced that I needed to attend seminary so that I could finally be a lead pastor. Because, of course, when you're in charge, everything will be better (I know that this isn't true now, but a younger me had no clue). However, when I was let go presented a pretty serious problem. I was let go in the spring, after the admissions deadlines for virtually every seminary in the country had passed. I would have to wait a full year before I could get into school, and I didn't have a job, any savings, or any real skills at the time. To put it politely, I was pretty screwed.

There were only a handful of seminaries in the country with open enrollment. One of them was Fuller Theological Seminary in Pasadena, California. I applied and was accepted. In August of 2010, with no idea how I was going to afford Los Angeles or grad school, I packed up my entire life in my car and moved out to Southern California to earn a Masters of Theology.

How Theology Leads to Technology

This part of the story is challenging to tell in a linear fashion. In truth, there are three simultaneous storylines taking place, like three cords wound together to form a single rope. In this section, I will be weaving in and out of these storylines to try and tell the whole story.

In order to understand these three parts, you must understand something about me. I have many diverse and seemingly random passions, often pursuing three or four of them simultaneously. It's just who I am. Some last for a short season of my life, maybe a couple months or years, others last for much longer.

Storyline #1 - Music

I taught myself how to play guitar and write music in college. This is what eventually led to me being a worship leader and a music producer. While in grad school, I pursued a secular music career as a singer/songwriter doing folk/Americana music. I produced an album at the time. If you'd like to listen to it, you can hear it here.

Storyline #2 - A Serendipitous Mentor

My main means of staying physically fit in my life has been through playing sports. During grad school (and still today), my main sport was ultimate frisbee. I played in many regular pick-up games around Los Angeles and eventually made good friends with some of the people in the community. One of those people, Dave, became not only a good friend, but a mentor as well.

Dave and I shared something in common, we were both pastors. He was a few years older than I am and had finished his Masters before I met him. What was interesting about Dave's story was that he didn't work full time as a pastor. He had made the choice to go into real estate.

He understood that his gifts could be used in a much more efficient way that would still allow him to do some ministry. In fact, he could earn more money for his family and donate more to his ministry by not working as a full time pastor. Dave is very successful at what he does, and he was the first person to start to push me to think outside the box of traditional ministry. He helped me eventually understand that I didn't have to be stuck on the path I was on if I didn't want to be.

Storyline #3 - Learning to Code

One day, an acquaintance posted a link on Facebook about a course he developed for Codecademy. For those of you who might know, Codecademy is a free learning resource for coding. Remember that insatiable curiosity of mine? Well, it compelled me to click the link and give the course a try. Honestly, I don't remember what I learned that day (probably some HTML), but I enjoyed the course enough that I worked all the way through it. And then I found another course and worked through that, and then another and another.

Back to Music

My music "career" (if you can call it that) was going a bit better than I expected. I was playing shows on the Sunset Strip in Hollywood and getting a little PR here and there. So, of course, I needed a good website, but couldn't afford to pay anyone to make it for me.

Back to Coding

But I was learning how to code so I could build the website myself, right? Kind of. I had learned some HTML, CSS, and jQuery, but I was a little over my head in terms of understanding how the Internet worked. Servers, clients, etc. It was all new stuff to me. I'd get an idea and then bang my head against a wall in my free time trying to figure it out. Lucky for me, I had two things going for me. First, I had a few friends willing to help me get started. They helped my buy some server space and a domain name and connect the two. Second, I had spent my life teaching myself how to do things and knew how to persevere through times where it seemed like I would never be good at it. I had done it with golf. I had done it with music. I knew I could do it again with coding.

Back to Dave

Dave and I talked a lot about my future. I think he recognized some writing on the wall that I didn't and he knew I'd need to think outside of the box to find work (and to pay off my massive student loans).

During my time at Fuller, my theology moved much further left than what would be considered orthodox evangelicalism. I was partially heading that way to begin with, but the education I received gave me a whole new set of tools to more accurately consider the implications of Biblical texts. I began to realize there was a great chasm between academic theology and the theology taught from the pulpit on Sunday. Academic theology is interesting and nuanced. Pulpit theology lacks so much of this. Academic theology isn't afraid of suggesting a radical idea if it can be supported. Say something similar from the pulpit and you'll lose your job and be told, "You're going to burn in hell!" I've never been comfortable with knowing one thing and saying another, and this was making pastoral ministry more and more challenging.

Those theological stances are not terribly important for this story. What is important is that it meant I struggled to find work. Conservative churches have more money to hire pastors than progressive churches. Also, typically, churches require that you sign a "statement of faith," a document that defines their beliefs and your agreement with those beliefs. In a lot of cases, I just couldn't do this in good conscience.

Throughout all of this, Dave would remind me that I might have skills that could be used elsewhere. He didn't really know I had been coding on a regular basis, but he knew that I was smart and talented.

Back to Coding

I graduated seminary in December of 2012. I was engaged, about to marry Anna in a few months. She was still in school and wouldn't graduate until June. I was actively looking for pastoral jobs with almost no luck. I was often selected as a candidate, I'd get to the final interviews with the churches, and come in second place every single time. I know for a fact that I lost out on three jobs solely based on my support of the LGBTQ community. It hurt to come so close and fail again and again. I'm sure many people can relate to that in their own field.

In the meantime, I was working a smattering of part time jobs to make some ends meet. I was a private tutor, a janitor, an intramural sports coordinator, and a freelance blogger (I got paid to write articles about audio production). Anna was working a few random jobs, too. We were scraping by.

During this time, I developed possibly the best habit I ever established in my life. Every morning, I would wake up, make myself a full French press of coffee, and I would sit down and try and learn something new with code for a few hours each day. Coffee and code. That was it. I didn't have any particular path. I would just find tutorials that interested me or a simple project I could view the source and rebuild. I did this every day for about a year.

Anna and I got married in March of 2013, she graduated in June, and then we were faced with a decision. Neither of us were finding jobs, and neither of us wanted to live in Los Angeles long term. The cost of living was too high, traffic was horrible, we would never own a home, etc. We knew it just wasn't the right place for us.

Through a lot of prayer and discussion, we eventually landed on moving to Portland. We realized that our savings would last longer by moving to a lower cost of living city. We thought that it would be a good place for my music (it would have been, but Anna made me so happy I kind of stopped writing), we knew we'd have a few friends moving back there in a few years so we'd be able to have some community, and we thought Anna would be able to find work pretty quickly. I was still looking for pastoral jobs, but was losing hope.

We moved to Portland in September of 2013. It was really challenging. A new town without much money, no community, and no jobs. I don't recommend that many challenges in your first year of marriage. But we tried to dive right in.

Now the Part Where All These Random Things Come Together

One Sunday, my wife and I attended a church here in Portland and I met a guy named Mike. Mike is very well connected in Portland because he works for the city. I explained our situation and he asked me what my interests were. When I said coding, he arranged for me to meet two developers he knew.

These two devs were kind enough to look at the portfolio of little projects I had built up over my year of coding. To my surprise, both of them thought I knew enough to go get a junior developer job. This was really the first time I had ever considered it as a potential career.

I had tried for almost a year to become a pastor, had sunk about $90K into my education and was getting no where. This is when I remembered Dave's wisdom to think outside of the box. To pursue alternative avenues to success. So I decided to go for it. I was going to find a job as a web developer.

I applied to basically anything I could find. Seriously. Every job website. Every Craigslist ad. Luckily, the market here was booming and it wasn't flooded with junior devs. Within two months, I had a few offers. I chose to start my career with FINE and the rest is history.

Conclusion

You can piece together my career so far by looking at my resume and reading my other post--Four Years In. I have had some ups and downs, but mostly, my career has been overwhelmingly positive. When I got started, I had no idea where it would take me. And I am thankful for every part of it so far.

Thank you for reading my story. I hope it gives you some context to understand how I got to where I am. Please let me know if there are more details I should try and add to the story. I can update this as time goes on.

Not All “Just JavaScript” is the Same

Thu, 07 Sep 2017 00:00:00 GMT

I'm going to start this post with what will appear to be a tangent. I assure you, it's not.

My wife, wonderful as she is, is not a very technical person. She is very caring, though, and will often listen to me talk about the technical things I am working on. This often means I need to use metaphors and similes to get my point across. I want to take a recent one I shared with her and share it with you.

Imagine two similar, but slightly different, worlds that both required you to use two languages to communicate. In both of these worlds, one of the two languages is your common tongue, your lengua franca. You know it very well. Have studied it for years. You'll never forget it. Sure, this language can seem, at times, primitive and without polish, but you know how to use it well, be expressive with it.

In both of these worlds, the second language, while based, in part, on the other language, is much more foreign to you. You haven't used it as long. Fewer people speak it conversationally, it's specialized and, to an outsider, might even sound like gibberish.

Now, in both worlds, in order to start any conversation, you must use the second, more specific language before you can use the first language. In these worlds, the first language lacks almost all context for understanding with out the second language. There is one catch, though, one major difference between these two worlds. In one world, only one word from the more difficult language is needed to start your conversations. In the other, you might need to use hundreds.

What On Earth Are You Talking About, Kyle?

I'm talking about APIs and JavaScript obviously! If you think about it, every API is built upon a language you know. Some of these APIs are wonderful and allow you to express things easily without repeating yourself often. Some APIs aren't so great. Maybe they don't have the greatest architecture, or maybe it has some quirks and oddities that are difficult to grasp. Maybe they are so big as to be difficult to learn thoroughly. Maybe there's no documentation. I think we can all appreciate that one.

APIs are the second language in the metaphor. By starting a dialogue, or rather a program or algorithm with them, we gain access to whatever methods have been expressed within the API. Once we are in the domain of these methods, we often can revert back to our native tongue, but not always.

The Two Worlds

Currently, I have myself in two worlds at the same time. For my day job, I work with Ember, and for all my side projects and talks, I work with React. To me, React is the first world. I only have to use a few words and some idioms from the language to get it to work. Ember, on the other hand, is the second world, where there are hundreds of words you need to know.

The First World

With React, the only word you must know is "Component". If you're using ES6 classes and JSX, then the React.Component method is the only "word" you need to know to get started. Sure, there are idioms like props, setState, and componentDidMount, but the overall technical, specific language is quite small. Aside from that, you exclusively use "Just JavaScript", that is you use the primitives and data structures given to you by the language, not the React API.

The Second World

With Ember, there are many words to know. For starters, there are 40+ classes off the Ember module (according to the docs). There are methods upon methods to learn. Many having the same name as native data structures. Do I need Ember.Array or Array? When I use Function which Function am I getting? If an Ember.Object is an Object, why do I need special getters and setters to get properties (two-way data binding, of course, I'm being rhetorical). Some of these methods are really important to the overall ecosystem, like computed. And computed isn't enough to know, as there are methods on that method, such as alias and reads.

While Ember is written in "Just JavaScript," you spend a lot less time writing native JavaScript than in React. You end up writing a lot of Ember (literally, you have to write Ember a lot).

Which Is Why...

...I contend that not all "Just JavaScript" is the same, and this is specifically what I think people mean when they claim that React is "Just JavaScript™" (see what I did there?). Sure, with Ember (and other similar JS frameworks) you're writing with JavaScript, but you're spending more of your time using the API than using the language.

I think this is why React devs speak with such passion about the library and why they feel so productive. Once you get started, you virtually never need to consult the documentation again because there are significantly fewer "words" to know. There are also fewer quirks to know (setState is async, that's really the biggest one). You want to try something crazy? Just go for it with the language you already know. It's how we've gotten great patterns like HOCs and render callbacks.

With Ember, I find myself trying to do things with JavaScript, only to learn that what I really need is an Ember method. Ember has worked so hard to give me a "right way" to do things, but sometimes it feels like the "right way" is really difficult to discover. I'd rather be given the freedom to express the task at hand using the language I know best.

Conclusion

I'm not here just to bash on Ember. Ember was my first introduction to JavaScript frameworks and I'll always feel some positive sentiment towards the project. People have built some amazing things in Ember. I'm hoping my team and I can build a great thing with Ember. But I feel like we, the JavaScript community, is really learning that less is more.

Less API. More "Just JavaScript".

How to Write Your Own JavaScript DOM Element Factory

Wed, 12 Jul 2017 00:00:00 GMT

Recently at an interview I was asked to write a custom component from scratch with vanilla JavaScript. I thought I'd take a few minutes to write part of that code for you. It's not as scary as it might seem at first.

There are three basic parts to any DOM element: the type of element it is, any attributes we need the element to have, and any children of the element. Knowing this, we can start to write our factory function.

const elFactory = (type, attributes, children) => {}

The first thing we need to do is create the DOM element we will eventually return. We do this with the createElement() method.

const elFactory = (type, attributes, children) => {
  const el = document.createElement(type)

  return el
}

The next thing we need to do is apply each key/value pair found in the attributes object we pass in.

const elFactory = (type, attributes, children) => {
  const el = document.createElement(type)

  for (key in attributes) {
    el.setAttribute(key, attributes[key])
  }

  return el
}

The last thing we need to do is handle children. There are two basic types of children we might run into: strings and other elements. So our function will need to handle both cases. Also, implied by the variable name children is that we might receive any number of extra arguments, so we'll need to use the rest operator to gather up our remaining parameters into an array. That code looks like this:

const elFactory = (type, attributes, ...children) => {
  const el = document.createElement(type)

  for (key in attributes) {
    el.setAttribute(key, attributes[key])
  }

  children.forEach(child => {
    if (typeof child === 'string') {
      el.appendChild(document.createTextNode(child))
    } else {
      el.appendChild(child)
    }
  })

  return el
}

And now we have a factory function that will create DOM elements for us. We can use it like this:

const markup = elFactory(
  'div',
  { class: 'my-component' },
  elFactory('span', {}, 'Hello World!'),
  ' Thanks for reading my blog!',
)

document.body.appendChild(markup)

Which will output the following:

<div class="my-component">
  <span>Hello World!</span> Thanks for reading my blog!
</div>

In the future, I'll discuss how we might be able to handle updates and have state available to our components. For now, this should help you if you're ever in a similar situation.

My Mock Interview Experience with Rick Altherr from Google

Mon, 03 Jul 2017 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

A few days ago, I came across a tweet by Stephanie Hurlbut, a software engineer and entrepreneur who uses her influence to help other engineers out. Allow me to share that tweet with you:

I was really intrigued by this idea and was hoping someone would rise to the occasion. As it so happens, a few awesome people offered to give mock interviews. In particular, I came across Senior Software Engineer at Google Rick Altherr's offer.

Well, as you can guess, I took Rick up on his offer and setup an interview with him.

Some Context

I think it's appropriate to provide some context to why I was so interested in this opportunity. I reveal this with some apprehension. It's not really culturally acceptable to admit that one is interviewing with companies (even though, realistically, we know it's happening all the time and we might be better off if we could all be a bit more open about it), but I hope my honesty is appreciated by those who are interested in what the mock interview process was like.

For the last four to five months, I have been interviewing with companies for senior front-end JavaScript developer/engineer positions. I'm looking for the next challenge in my career and hoping to join a solid engineering team for a company with a great product. This season of interviewing has been challenging and, at times, even disheartening.

I've had a lot of interest, more than I expected and from bigger companies than I had even thought were available to me before. Companies like Stripe, New Relic, Amazon and others. I must be doing something right with my career for this to happen.

I have gotten to a final interview with every company I started the candidate process with, used quite a bit of PTO to get to these onsite interviews, but thus far, haven't been able to get over that hurdle of getting an offer.

Companies have a legal incentive not to provide feedback. As a developer, I find this frustrating. We're used to our code telling us why it isn't working and making changes. Interviews don't work like that. The feedback is often non-existent, and when it is provided, it is so vague as to be practically useless. So the opportunity to participate in a technical interview with no real pressure and guaranteed feedback was a perfect opportunity for me to learn if there's anything I can adjust moving forward in my search.

The Interview

After responding to Rick's tweet and getting the affirmative, we messaged each other a few times to set up a time for the interview. I handled this as I would any normal interview. We discussed times that would be a good fit for both of us and then hammered out a few of the details we wanted to cover in the interview. When the time came, we used a Google hangout and a Google doc to share the code. I've not used a Google doc in this way before (and I certainly missed some nice features of a code editor while coding), but it worked just fine. As Rick said, it had the added benefit of him highlighting some of my code if necessary. After some brief introductions, we dove right into Rick's problem.

Now, I won't share any details of the problem because, to some degree, the problem itself is irrelevant, and I wouldn't want to burn one of his questions. He told me later that he has used this question for four and a half years. I wouldn't want to be the reason he had to stop.

He described the problem. I made some quick notes of details I thought were important to finding solutions. I like to do this for two reasons. First, I don't like working through a solution only to realize I forgot a key part of it. Second, I think it's my first opportunity to show my thought process and what it would be like working with me on a problem. I think it indicates I can pay attention to details and summarize problems into their most salient parts. I asked some questions about what assumptions I could make and then focused on writing the code for the two main parts of the problem.

I solved one part of the problem relatively quickly, but it was the smaller of the two parts. The second, bigger part involved recognizing a key element of the problem (which I did). However, I wavered on what was the best strategy to solve it. This wavering slowed me down a bit and became a focal point of our discussion afterwards. After deciding a path ahead, I spent a little more time coding, about 15 minutes in total, before Rick cut me off. He cut me off so we would have more time to chat and that it was apparent I would solve the problem eventually.

The Feedback

Right away, Rick asked me a question I wasn't quite expecting, "How do you feel you are doing?"

I answered with some moderate confidence, but also with a hint of apprehension. I was confident I was on a good path to a solution, but I was uncertain that I was heading towards an optimum answer. I took some time to explain that this has been a common feeling in the interviews I have had. I don't have a background in computer science, so the more technical aspects of data structures, Big O, and algorithms is fairly new to me. I've only been studying these things for a short while (6-9 months). I can find solutions, I've yet to be completely stumped by a problem given to me in a technical interview. But I often get the sense, or know, that there is a more optimal solution that I am not coming up with.

His response was that he has seen hundreds of engineers attempt this problem. Of those many engineers, including those who work at Google, I was doing "average to above average" on solving the problem. I'll take that. That's a big win in my book.

He said it was clear I understood my language and that I did a good job describing my thought process as I worked. His main concern was my speed, that I needed to go faster.

I tend to be a methodical, slower coder. I get things done on time, but I get them done by thinking through my problem and then coding. Maybe you'd call me a "measure twice, cut once" kind of coder. This isn't normally a problem because I do think of solutions relatively quickly, but when I hit a place of uncertainty, I slow down and think through options. I question myself. I waver.

This wavering isn't serving me well. First, it makes me slow. I had never considered just how important speed might be to the culture of a company. Rick said that my speed might be acceptable at this company, but "it would never fly" at that company.

Second, I am a verbal processor (and an honest one), so while it serves me well in describing my thought process, it also means that I describe those moments when I'm uncertain and unconfident as well. This isn't likely to help me in an interview. An interviewer might think I'm trying to fish for an answer, or look for some kind of visual cue to indicate I am on the right track.

I took from this that I may have to push myself to code with a bit more speed. I think I also need to make decisions confidently, or at the very least, act like my solution is solid. If I discover there is a better way, I can simply state that fact, and refactor my code. It does happen. I have to signal less that I am unsure, or that I want affirmation I am on the right path. I have to have more belief that I am on the right path already.

Conclusion

Having done quite a few of these interviews now, I can say that this experience was very similar to the real one. It was so helpful to be able to talk immediately with my interviewer about how I did instead of trying to infer the feedback based on subtle social cues like speech, tone, and body language.

I really enjoyed this process. I think it should be a more common practice among aspiring and ambitious developers. It can be a great benefit to interview, even with friends, frequently. Practice will make the real thing much easier.

Personally, I thought it was great to get some feedback, and frankly, some affirmation that I am doing well with my chosen focus and that I am on the right path. Going through these really challenging interview processes has occasionally left me wondering if I'm not ready yet, or I'm not good enough. I don't think that's the case. I think I am really close to getting to my next goal.

So that was my experience doing a mock interview with Rick. I want to publicly thank him for taking the time to help out engineers this way. I also want to thank Stephanie for her part, creating an opportunity for people to connect. Thanks to both of you.

I know that this was a very personal post, but I hope there was something you could take from it. Feel free to ask me more questions in the comments if you have one. Having done this experience, I think I may have to offer some mock interviews for the junior developers I meet. If you're a mid-to-senior level developer, consider offering mock interviews, too. Or maybe trade them with a good friend. Either way, we're all bound to learn a little something more about being better at interviews.

Make Your Own Charts in React Without a Charting Library

Sat, 24 Jun 2017 00:00:00 GMT

import { ExampleBarChart } from './_BarChart'

Occasionally I see someone ask, "What's the best way to make bar charts with React? Are there any great libraries?" I often respond with, "Why not build it with React yourself?"

React's one-way data binding model is perfect for creating simple data visualizations from scratch and I want to show you how.

Why shouldn't I use a charting library?

Charting libraries are great! I'm not going to stop you. But bringing in a whole library for a simple data viz might be a bit of overkill in some situations. If you go the route of adding a charting library to your application, you now have to understand two APIs versus one. React's API is well suited to creating these visualizations, so I'm encouraging you to use what you already know.

A Simple Bar Chart

We are going to build is a bar chart. These are really easy to build with React. Once you understand the concepts, I'm sure you'll be jumping ahead and making even more complex visualizations in no time. Let's get started.

To make our bar chart, we're going to first need some data. Because I lack creativity, I'm going to create a data set based on the number of repos a few of my favorite Github users own (and mine for good measure):

const data = [
  {
    name: 'kentcdodds',
    repos: 371,
  },
  {
    name: 'sindresorhus',
    repos: 909,
  },
  {
    name: 'developit',
    repos: 222,
  },
  {
    name: 'getify',
    repos: 43,
  },
  {
    name: 'btholt',
    repos: 56,
  },
  {
    name: 'kyleshevlin',
    repos: 82,
  },
]

Next, we need to build a few basic components to represent this data. We'll start with a Chart component and a Bar component.

const Chart = ({ children, width, height }) => (
  <svg viewBox={`0 0 ${width} ${height}`} width={width} height={height}>
    {children}
  </svg>
)

const Bar = ({ x, y, width, height }) => (
  <rect x={x} y={y} width={width} height={height} />
)

These are really simple components. Our Chart component creates an svg based upon the width and height we pass in as props. Then, the Bar component creates a rect element that we will pass as a child of the Chart component.

Putting this together (with some math to handle the discrepancy in repo totals), we can make our bar chart like so:

const BarChart = ({ data }) => {
  // Width of each bar
  const itemWidth = 20

  // Distance between each bar
  const itemMargin = 5

  const dataLength = data.length

  // Normalize data, we'll reduce all sizes to 25% of their original value
  const massagedData = data.map(datum =>
    Object.assign({}, datum, { repos: datum.repos * 0.25 }),
  )

  const mostRepos = massagedData.reduce((acc, cur) => {
    const { repos } = cur
    return repos > acc ? repos : acc
  }, 0)

  const chartHeight = mostRepos

  return (
    <Chart width={dataLength * (itemWidth + itemMargin)} height={chartHeight}>
      {massagedData.map((datum, index) => (
        <Bar
          key={datum.name}
          x={index * (itemWidth + itemMargin)}
          y={0}
          width={itemWidth}
          height={datum.repos}
        />
      ))}
    </Chart>
  )
}

ReactDOM.render(<BarChart data={data} />, document.getElementById('barchart'))

If you've followed along, you should now have a bar chart of 6 bars. Their heights should correspond with how many repos the user has. There is one small problem, though. The bars are upside down.

This is a typical problem with bar charts and is easily solved. I just wanted to show you how.

In our BarChart component, we need to change the y prop to place the rect such that they all line up on the bottom. To do this, we can set y equal to chartHeight minus that rect's height. Let's make some small changes to the component:

const BarChart = ({ data }) => {
  // all the same ...

  return (
    <Chart width={dataLength * (itemWidth + itemMargin)} height={chartHeight}>
      {massagedData.map((datum, index) => {
        const itemHeight = datum.repos

        return (
          <Bar
            x={index * (itemWidth + itemMargin)}
            y={chartHeight - itemHeight}
            width={itemWidth}
            height={itemHeight}
          />
        )
      })}
    </Chart>
  )
}

And there you have it, a very simple to make bar chart. Check out a rendering of our bar chart below:

How I Stumbled Upon Normalizing Redux State

Thu, 18 May 2017 00:00:00 GMT

My most recent work project was an interesting challenge. I built an app (actually 2 Electron apps supporting 3 React apps communicating through WebSockets) that allowed a user (actually 4 simultaneous users) to look at an array of stories related to sea ports, select one, have a detail component pop up with more information about the story, and then move to the next or previous story from within the detail window.

For each of these actions, a particular story had to be retrieved from the Redux store. In my naive, initial implementation, stories were kept as an array and a simple .find() was used to loop through the array and match ids. For those of you who know where I'm going with this, this was a slow solution. For those of you who don't know where I'm going with this, let me explain.

Up until about a year ago, I knew very little of how data structures worked. I just used whatever structure seemed to make the most sense. Like in this example, I have a collection of stories, it seems most obvious to use an array. However, data structures all have pros and cons. One of the cons of an array is how slow a lookup is if you don't know the index of the item. Let me explain why.

Say I have an array with a lot of items (think thousands, for this example). Now imagine that I have to find an item in this array, but the only way I can find it is by checking, one by one, if the current item matches what I'm looking for. It would be like having to search through a filing cabinet, file by file, to find something. It's really slow. In CS terms, this search has a time complexity of O(n), meaning it takes the time of n items to find the right one. So how can we speed this up?

I mentioned that finding an item in an array is faster if you know the index of the item. You go directly to the correct spot and retrieve the item stored there. Does this remind you of another data structure? That's right. An object.

An object stores key/value pairs. If you know the key, you can get the value. This has a time complexity of O(1). Regardless of how many key/value pairs are stored in the object, the lookup is the same speed. So how do we take an array and create an object out of it?

In my situation, this is (roughly) what I did:

const array = [
  {
    id: 1,
    title: 'Awesome Story',
    content: 'This is a very awesome story',
  },
  {
    id: 2,
    title: 'Happy Story',
    content: 'This is a happy story :)',
  },
  {
    id: 3,
    title: 'Sad Story',
    content: 'This is a sad story :(',
  },
]

// Turn into an object with .reduce()
const objFromArray = array.reduce((accumulator, current) => {
  accumulator[current.id] = current
  return accumulator
}, {})

console.log(objFromArray)
// Logs out
// {
//   1: {
//     id: 1,
//     title: 'Awesome Story',
//     content: 'This is a very awesome story'
//   },
//   2: {
//     id: 2,
//     title: 'Happy Story',
//     content: 'This is a happy story :)'
//   },
//   3: {
//     id: 3,
//     title: 'Sad Story',
//     content: 'This is a sad story :('
//   }
// }

Now, to find an item, we do a lookup with the item's id property. This is much faster. To do this normalization in Redux, use this logic in your reducer when you receive the array. It is often helpful to maintain an array of the ids so you have a list of all the keys, in the correct order, to your new object. In the same reducer logic, map() out your keys into an array and define it as a property in your state object. Your state tree will come out looking something like this:

const state = {
  stories: {
    // an object that looks like the one logged out from above
  },
  allStoryIds: [
    // an array of each id to use as keys for lookup
  ],
}

After I had done all this, my app performed much faster. I don't have statistical breakdown of the data, but it was obvious to everyone. My team did a bunch of "oohs" and "ahhs" when they saw how much faster everything was performing.

Guess What? I Didn't Make This Up. It's Recommended by Redux

A few weeks later, I came across this: http://redux.js.org/docs/recipes/reducers/NormalizingStateShape.html. This just goes to show you should really read the Redux documentation, doesn't it? If you're looking to normalize your state shape even more, please give that a thorough read and see how it improves the performance of your Redux application.

If you have any questions or comments, leave them below, and let me know of any other ways you have stumbled upon to optimize your Redux state objects.

ShevyJS

Wed, 17 May 2017 00:00:00 GMT

This morning I released ShevyJS into the wild. ShevyJS is a remake of Shevy for CSS-in-JS styling.

If you're new to the concept of CSS-in-JS, you can find some great resources on the topic including this massive repo. In a nutshell, CSS-in-JS is the task of adding styles either inline or otherwise directly with JavaScript. You may have seen a style tag used in a React component. This was a form of CSS-in-JS.

Now, you can have the mathematics of Shevy's Sass version in your JavaScript client-side framework.

ShevyJS is a class that exposes a set of properties and methods for you to consume throughout your application. Because it is a constructor, you can define as many Shevy configurations you need and pass them around your app with imports and exports.

It is available on npmjs.org, and be sure to check out the repo at https://github.com/kyleshevlin/shevyjs. If you like the library, please star it.

If you have any questions, feel free to ask them here, or create an issue on the repository. And share examples of using ShevyJS in the wild.

What I Love About React #1

Sat, 22 Apr 2017 00:00:00 GMT

This won't be a very long, nor deep, post. As I was working on some code this afternoon, a thought occurred to me. I love React. I really do. I find it so pleasant to work in React, and I can't always describe why. However, I have at least one reason I can describe, and I thought I'd share that with you right now. I'll share more as I think of others.

One reason I love React is the simple fact that the same component can render different markup depending upon props and/or state. I think many of us have grown so accustom to this that we have forgotten how novel and amazing this is.

Let's take a very simple component for an example.

class MyComponent extends React.Component {
  constructor() {
    super()
    this.state = { isReady: false }
  }

  componentDidMount() {
    setTimeout(() => {
      this.setState({ isReady: true })
    }, 3000)
  }

  render() {
    return this.state.isReady ? (
      <div>I'm ready!</div>
    ) : (
      <div>One moment. I'm still getting ready.</div>
    )
  }
}

In this simple component, I am using a ternary to render one div when the component isReady and an entirely different one when we are not. There are a number of other ways to handle this situation that return the same result, but at it's core, any one of them will use a ternary or an if...else statement to return different DOM for different state.

This is absolutely brilliant. Could you imagine trying to accomplish this with a server side application? You could probably do it with vanilla JavaScript or jQuery simply enough, but would it be as elegant? Our component is as pure as the driven snow. It renders solely based on its inputs, is really easy to test, and pretty easy to reason about.

Just last year, I was working as a Rails developer. There's nothing in that ecosystem that even comes close to this. Often in this scenario, I would actually render both divs and hide the correct one with CSS. It was hacky, but made transitioning simple and nice.

React eliminates these hacks and instead provides us with a very elegant way of creating really responsive UIs (not responsive in design, but responsive to our data). It's just hard to beat how simple, yet powerful this mechanism is.

What is Most Important to a Web Developer?

Sun, 26 Feb 2017 00:00:00 GMT

import SocialPost from '../../../components/SocialPost.astro'

Recently, I ran a poll on Twitter asking web developers what was most important to them. Here's a look at the results.

Over 50% of the voters said the people they work with is most important to them, followed by the product they work on, and lastly, followed by the tech they use at work. No one replied with an "other", even though a couple people voted for it.

I wanted to take some time and write about what I found surprising and not surprising about these results. If you're not a fan of think pieces and only like technical articles, turn away now.

Not Surprising

I want to start with what is not surprising about the results. I don't find it surprising that developers said the people they work with matter so much to them, but I also don't think this is something exclusive to developers. Human beings are social creatures. It's in our nature to want to interact with the people around us, especially those we must spend so much time with. And since no one wants to put up with a difficult person for long, it makes sense that having people you enjoy to work with would be important.

Another way to put this is as a business develops a culture and a tribe, you recruit more people who fit and enhance that tribe. In doing so, you have a better chance of a newcomer fitting in (because you only select newcomers that already likely fit in) and reduce potential disruption. This might have some negative effects, but you are likely to find a group of people who like being around each other.

It also didn't surprise me that a third of voters said the product they work on mattered most to them. Again, I don't think this is exclusive to developers. People want to believe that the work they do is meaningful and has an impact. Working on a product that you don't care about, that you have no emotional investment in can be some of the most draining, boring and soul-sucking work. When people work on products that they actually care about, they give you their best work and feel satisfied and accomplished with what they do.

Surprising

On the other hand, I do find it surprising that developers say that the people they work with matter so much to them. If you were to take a broad slice of blog posts, tweets, and other articles written by developers, you'd get the picture that the tech stack would be the most important to them. We're quite fond of writing articles bashing this technology and praising that technology. We are opinionated about our field, and it would make sense that we would have strong opinions about what technology we use day in and day out. But technology was the least important of the three.

What I found most interesting about the results of this poll, is that they have a perfect inverse correlation to how much knowledge you can have about each one before taking a job. Let me explain.

When you're looking for jobs, web developer job descriptions are littered with acronyms to describe the tech stack used at a particular company. We obsess over these acronyms, because they represent hours and years of effort learning and programming. Developers fall in a couple camps, but when considering a job, they want to know what stack they will use. Will it be one I'm really comfortable with and love? Will it be a new language and new challenges? These matter to developers. And it's the easiest thing to learn about a new job. You ask a question, and you get a perfect, corresponding answer. There is no ambiguity, other than what might be used in the future.

Next, you might ask about the product you are working on. How often have you asked a developer what kind of product they work on, and you receive a semi-ambiguous response? "Well, it kind of does this. It kind of does that. Somehow it makes money." Products, can be challenging to describe, but generally you can describe the shape of it. You might not be able to express all the fine details of a product in an elevator pitch, but you can get a sense of what you will be working on. Thus, you'll likely be less clear on the product than you were on the tech stack, but you'll have a reasonable understanding.

But the people you will work with is a mystery prior to starting a job and continues to be for some time after starting. Unless you happen to previously know the people you are working with, you most likely know nothing about your future coworkers. Unless it is a very small company, you will likely only meet a handful of people in the hiring process and virtually everyone is on their very best behavior, each party trying to woo the other. At best, you'll get a small glimpse into the culture of the company, but will not have enough information to make an accurate assessment of the overall culture of your future team and the company as a whole. The only way to gather this data is to be a part of it and hope it works out for the best.

Final Thoughts

To summarize, it's not surprising that people care about the people they work with and the product they work on. I think people want to enjoy work and want to work on something that matters, that is important to them and to the world. I think developers are willing to sacrifice working on the newest technology stack for the opportunity to work with great people or on a product they can get behind.

What is surprising is that these very things might be the most difficult to ascertain before joining a team or taking a job. I wonder if there are ways that we can flip this correlation and make the things most important to developers (and people in general) easier to learn about.

Renderless Components

Thu, 23 Feb 2017 00:00:00 GMT

If you're using Redux with React, you are probably familiar with the concept of container and presentational components. If you are, you can skip ahead to the section Renderless Components. If you're not, let me give you a very brief description of each.

Container Components

The purpose of a "container component" is to gather and pass data into a presentational component. Container components are used to connect to stores, fetch data during various lifecycle methods, and otherwise gather and transfer data to child components.

Presentational Components

The purpose of a "presentational component" is to render UI based solely on the props passed to it. These have also been referred to in the past as "dumb components". These components have no (or at least very little) logic, and do not use any lifecycle methods other than render(). In fact, most presentational components are written as stateless functional components. That is, these components are pure functions that receive props as arguments and render appropriate markup. Presentational components are relatively easy to test due to this.

Redux and Container Components

Those familiar with Redux know that a single store governs your application's state in a Redux app. The typical way to pass this state to your app is through a Provider and using the connect() function to connect components to this Provider. These can be found in the react-redux package.

The connect() function creates a Higher Order Component, that maps state and actions to props and connects the component to the Redux store. Like so:

import React, { Component } from 'react'
import { connect } from 'react-redux'

class FooContainer extends Component {
  //...
}

export default connect()(FooContainer)

I won't go into the connect() API. The docs are very well written and there are plenty of tutorials and videos on how to use it. I simply wanted to show that we are not exporting FooContainer itself, but rather the HOC returned by the connect() function.

Redux and Presentational Components

Using the example from above, generally speaking, we would use this container component to connect to our store to gather props and pass those props into a presentational component. There are two ways to do this.

We can pass the props directly to our presentational component if we don't need to use any lifecycle hooks in a container component, like so:

import { connect } from 'react-redux'
import FooPresentational from './FooPresentational'

const mapStateToProps = state => ({
  someProp: state.someProp,
})

export default connect(mapStateToProps)(FooPresentational)

In this situation, someProp is passed directly into FooPresentational.

We can also map the props to the container component, and then pass them to the presentational component in the render() method of our container component, like so:

import React, { Component } from 'react'
import FooPresentational from './FooPresentational'

class FooContainer extends Component {
  render() {
    return <FooPresentational someProp={this.props.someProp} />
  }
}

const mapStateToProps = state => ({
  someProp: state.someProp,
})

export default connect(mapStateToProps)(FooContainer)

This way of passing props explicitly might be a bit cumbersome, but can be useful if you need to massage the props for any reason before passing them.

Renderless Components

When I first came to React, my mental model treated components and the UI as a 1-to-1 mapping. It took me some time to realize not all components will render DOM elements. It took me even longer to realize that not all components need to render anything at all.

It is a perfectly legitimate use of a component to render () { return null }. This is particularly helpful when you need logic to exist that updates your store, but has no associated UI. In this case, you're making a container component that doesn't return any presentational components. For now, I call this a renderless component. This is an incredibly useful pattern.

For a project I am working on, I need to update a value in my store, currentTime, with the current hours, minutes, and seconds. Since Redux requires reducers to be pure, the logic for updating the time must be in the action itself or passed to the action creator function as parameters. This means, I need a component to set up an interval to dispatch a function that will in turn update my store. Here's what a component like that might look like:

import { Component, PropTypes } from 'react'
import { connect } from 'react-redux'

// This is my action creator function
// It takes three parameters: hours, minutes, seconds
import { updateTime } from '../actions'

class UpdateTimeContainer extends Component {
  constructor() {
    super()

    this.intervalId = null
    this.startClock = this.startClock.bind(this)
    this.stopClock = this.stopClock.bind(this)
    this.getCurrentTime = this.getCurrentTime.bind(this)
  }

  componentDidMount() {
    this.startClock()
  }

  componentWillUnmount() {
    this.stopClock()
  }

  startClock() {
    this.intervalId = setInterval(this.getCurrentTime, 5000)
  }

  stopClock() {
    clearInterval(this.intervalId)
  }

  getCurrentTime() {
    const now = new Date()
    const hours = now.getHours()
    const minutes = now.getMinutes()
    const seconds = now.getSeconds()

    this.props.updateTime(hours, minutes, seconds)
  }

  render() {
    return null
  }
}

UpdateTimeContainer.propTypes = {
  updateTime: PropTypes.func,
}

const mapDispatchToProps = {
  updateTime,
}

export default connect(null, mapDispatchToProps)(UpdateTimeContainer)

As you can see, this component uses lifecycle methods like any normal component, but doesn't render any markup. That's right! A component will mount even if it doesn't render markup.

If you check your inspector, you'll see that React adds a nice little comment about this component . Our component exists in the virtual DOM and updates to the store without rendering pointless markup.

This pattern allows us to write business logic into our applications as React components. I have used this pattern for event handlers, listening to web sockets, and more. It seems every time I make an app, I think of a new use case for this pattern.

Conclusion

What I want you to take away from this post is that rendering null from a React component is a perfectly legitimate use of a component. Using this pattern will allow you to encapsulate necessary logic for updating your store (or however else you are managing state in your app).

I hope this helps and that you find use cases in your own projects for creating these renderless components. Let me know if you have any questions, ways to improve this technique, or examples using it in the comments.

Zeno's Paradox of Infinite Loop Scrolling

Fri, 17 Feb 2017 00:00:00 GMT

My current project has a strange requirement. Given a collection of items, a user should be able to infinitely loop scroll left and right in a carousel. From strictly a UI perspective, this makes sense, when I move to the left, add items to the right and vice versa. From a developer's perspective, this is kind of crazy.

Let's assume I have a collection, we can use an array of numbers for this example:

const collection = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Let's assume I can only see five of these items on the screen at once. Thus, when we reach either "edge" of the array, we should get the items on the other "edge" to populate our visible five. For example, if I went past the left edge, I would see this: 9,10,1,2,3.

The way this is handled, from a developer's perspective, is that when you scroll the container you add and remove items simultaneously (or .map() a new set of items for better performance) so that the number of items is always the same. Because the number of items is a constant, when we "move" our items, we must compensate the scroll position of the container an equal amount. If you move to reveal an item on the left we must:

Remove the item on the right
Add an item on the left
Then compensate the scroll position the width of one item

Doing this results in your scroll position being exactly the same as it was. Assuming a world where the wrapping container never changes width, and the performance of the machine you view this UI on is perfect, you would literally never move position. Crazy!

Similar to Zeno's paradox where the arrow never reaches its target, the user never actually scrolls despite what appears like scrolling.

Head Scratcher #1

Thu, 16 Feb 2017 00:00:00 GMT

I am starting a randomly occurring series called "Head Scratchers." At least once a week (probably once a day), I run into a problem that makes me scratch my head for while. So I'm going to share the problem and my solution with you. If you think of a better way to solve the problem, I want to see it in the comments below.

The Problem

Currently I am building an application for an interactive touch table that will be on a boat. This table will retrieve a number of locations associated with particular ports. The shape of the data (for now) is a bit odd. I can retrieve an array of the locations, but then have to gather them by ports for the user interface. This is what a few example items of this data might look like:

// My API endpoint returns an array of objects with ids and a foreign key to a port
;[
  { id: 1, port_id: 3 },
  { id: 2, port_id: 1 },
  { id: 3, port_id: 2 },
  { id: 4, port_id: 1 },
  { id: 5, port_id: 3 },
]

If I only had to display these items with their associated port, this would be fine, but the expectation of the user interface is to list them in groups by ports. So, I need to take this array and turn it into a two dimensional array gathered by ports.

My Solution

I needed to go from a one dimensional array, like [1,2,3,4,5], to a two dimensional array, like [[1,2],[3],[4,5]]. I can't accomplish this in one step (as far as I know). I can't use .map() since it's not a one-to-one mapping of values. I need a solution that will allow me to create my sub-arrays first, and then push them into a new array.

To start, I decided to use .reduce() to turn my array into an object, the keys of which are the port_ids and the values for each key are an array of the points of interest objects. That looked like this:

const items = [
  { id: 1, port_id: 3 },
  { id: 2, port_id: 1 },
  { id: 3, port_id: 2 },
  { id: 4, port_id: 1 },
  { id: 5, port_id: 3 },
]

const ports = items.reduce((acc, cur) => {
  if (!acc[cur.port_id]) {
    acc[cur.port_id] = []
  }

  acc[cur.port_id].push(cur)

  return acc
}, {})

The .reduce() method takes a callback and starting value. In this case, I want to start with an empty object. This empty object will be supplied as the acc value in the first pass through the function. acc stands for "accumulator" as this will be the accumulation of our iterations over each item. cur is short for "currentValue", which is the current item being iterated over.

With each pass, if the accumulated object does not have a key that matches the current port_id, we create a key of that port_id and assign it an empty array. Regardless of whether the array needed to be created, we will be pushing the current item into the array associated with the port_id. We then must return the accumulator to be used in the next iteration of the function. When this runs over our items, should have an object that looks like this:

console.log(ports)

// {
//   1: [{ id: 2, port_id: 1 }, { id: 4, port_id: 1 }],
//   2: [{ id: 3, port_id: 2 }],
//   3: [{ id: 1, port_id: 3 }, { id: 5, port_id: 3 }]
// }

Now we have an object whose keys are paired with values that will be the subarrays of our two dimensional arrays. We want those values, and we want them in an array. There happens to be a new method on the JavaScript primitive Object that will do just that, the .values() method.

Object.values(obj) returns an array containing the values of the enumerable properties of your object. Since our values happen to all be arrays, we will end up with an array of arrays. Using this method looks like this:

const twoDimItems = Object.values(ports)
console.log(twoDimItems)

// [[{ id: 2, port_id: 1 }, { id: 4, port_id: 1 }], [{ id: 3, port_id: 2 }], [{ id: 1, port_id: 3 }, { id: 5, port_id: 3 }]]

Now I have a two dimensional array gathered by ports. Since I mentioned that this is necessary, I might as well explain my needs there.

Each of these items, individually, will represent a Card of information. I need a list of these Cards gathered by their ports, thus I have CardGroups. Each CardGroup displays a list of its Cards. Lastly, I have a CardGroupsList that displays all my groups. It's a cascade of lists, and thus, my UI is a mapping over the outer array, followed by mapping each inner array. With React stateless functional components, that looks like this:

const Card = ({ item }) => <div className="card">{item.id}</div>

const CardGroup = ({ group }) => (
  <div className="card_group">
    {group.map(item => (
      <Card item={item} />
    ))}
  </div>
)

const CardGroupsList = ({ groups }) => (
  <div className="card_groups_list">
    {groups.map(group => (
      <CardGroup group={group} />
    ))}
  </div>
)

Conclusion

And that's how I turned one array into a two dimensional array sorted by a foreign key. I'll leave it to you to figure out how all the pieces fit together with the React components. I hope it's clear how I came to my solution. If you can think of a better solution, leave it in the comments (or create a Gist and link to it, might be easier). I'd love an opportunity to learn from one of you.

How to Dynamically Render React Components

Wed, 08 Feb 2017 00:00:00 GMT

I am currently working on a React/Redux universally rendered application at work. It has some fun parts and I want to share what I've learned from building them.

One of those parts is a component I have called the BlocksLoop. In the design phase of the project, long before I was ever a part of the project, the designers and back end dev had the foresight to create a system of reusable admin components. They called them "blocks". Each page of the application was to be architected by utilizing these blocks in different orders and patterns. This was a front-end developer's dream come true. I considered crying, but then didn't, mostly because I can't. Seriously. I have some weird dry eye condition. I don't create the same amount of tears as you normal, emotionally and physically healthy people. But I digress.

In the end, the designers came up with 10 reusable blocks for the project. The backend developer implemented an API that returned an array of objects. So, how do we handle rendering components when we have no idea how many, or specifically which ones we'll need at any given time?

In my last blog post, I showed you how we can render different components conditionally. We're going to take that a step further. Actually we're going to take that to 11.

Inspired by the architecture of reducers in Redux, I realized a simple way to handle this very dynamic array of objects was to use a switch statement.

I knew that each object in the array had a type property. I needed to make individual components for each type. I could then check this type, and require the proper component with each one. This is significantly easier architecture than attempting to write a giant component to handle all the types. So let's see how this works.

For this example, imagine that I have several built out components. Each of these components represents a type of block. We're going to import these into what will become our BlocksLoop component. I'll also setup our component to accept a blocks prop, but it won't do anything important yet.

import React, { Component, PropTypes } from 'react'
import HeadingBlock from './HeadingBlock'
import TextBlock from './TextBlock'
import ImageBlock from './ImageBlock'
import ListBlock from './ListBlock'

export default class BlocksLoop extends Component {
  render() {
    return (
      <div className="blocks_loop">
        {this.props.blocks.map(block => (
          <div className="block" />
        ))}
      </div>
    )
  }
}

Right now, I'm just returning all the blocks as a simple div and not utilizing the imported individual blocks. Let's solve that with a switch statement. To make it cleaner, we'll move this logic into a method on the component that's called each time a block item is mapped over.

// ...

export default class BlocksLoop extends Component {
  constructor() {
    super()
    this.getBlockComponent = this.getBlockComponent.bind(this)
  }

  getBlockComponent(block) {
    switch (block.type) {
      case 'heading':
        return <HeadingBlock key={block.id} {...block} />

      case 'text':
        return <TextBlock key={block.id} {...block} />

      case 'image':
        return <ImageBlock key={block.id} {...block} />

      case 'list':
        return <ListBlock key={block.id} {...block} />

      default:
        return <div className="no_block_type" />
    }
  }

  render() {
    return (
      <div className="blocks_loop">
        {this.props.blocks.map(block => this.getBlockComponent(block))}
      </div>
    )
  }
}

And there you have it! Our blocks array is mapped over, each item is passed into our method, and the correct component is returned dynamically. If for some reason a type was added in the back end before I could make a new component for it, the method returns an empty div with a class I can style.

I think it might be possible to reduce some of the boilerplate in the switch statement by creating a variable, such as let dynamicComponent = null, and then overriding that assignment in each case with the correct component. Then in one last step in the function, I could add the key and {...block} props (via the Object spread operator) to the currently assigned dynamicComponent variable. I'm ok with being this explicit for now. It's very legible and understandable.

If you find this useful, I'd love to hear about it in the comments. Or if you have a way to improve this, I'd love to hear that, too.

Loading State Trick for Stateless Functional Components in React

Fri, 20 Jan 2017 00:00:00 GMT

I want to share with you a little trick I've been using lately with stateless functional components in React. This is probably really old news to some of you, but I'm hoping there are a few of you who don't know this one yet.

If you're getting started with React, and especially if you're using Redux, you've probably come across the concept of container and presentational components.

Container components provide data to nested components. These components will generally use lifecycle methods, such as componentDidMount, to fetch some data and pass it down.

Presentational components, on the other hand, are used solely for displaying data passed into them and generally do not use any lifecycle methods. Often, if a presentational component does not require any lifecycle method (other than the required render), then this component is written as a stateless functional component.

A stateless functional component is simply a function that returns the markup (React functions or JSX). Props are passed as arguments to the function, and then utilized within the markup. Let's make a simple example of a stateless functional component that expects an array of items, and displays each one of those items.

import React, { PropTypes } from 'react'

const DisplayItems = ({ items }) => (
  <div className="items">
    {items.map((item, index) => (
      <div className="item" key={index} {...item} />
    ))}
  </div>
)

Display.propTypes = {
  items: PropTypes.array,
}

export default DisplayItems

I hope the ES6 doesn't scare you. I've created a function called DisplayItems. This function expects a props object as an argument, and I'm using ES6 destructuring to make it clear that I'm expecting and will use an items property on the props object.

Then, I am using the implicit return feature of ES6 arrow functions to return the markup (in this case JSX, it's all I really use) from within the body of the function.

Then, I map over each item, returning another div. React requires that we add a key attribute to items that are dynamically populated, which is often the case with displaying arrays. In this case, it was easy to use the index, but it might be more useful to use a property on the item itself in your case.

Lastly, I am using ES6's Object spread syntax to pass all props from item into the div. In your example, it is possible that this inner item div would be another presentational component that needs access to all the props on item.

Thus, if we used this in our app, regardless of how many items we pass to this stateless functional component, React would give us the wrapping div, and then any divs generated by the map function.

But what if you currently don't have any items and you don't want to display the wrapping div until you have items?

It is possible to reconfigure this component to display alternative markup if there are no items to display.

Imagine that I have built another component called LoadingSpinner which simply shows the user a loading spinner animation. Perhaps it looks something like this:

import React, { PropTypes } from 'react'

const LoadingSpinner = () => (
  <div className="loading_spinner-wrap">
    <svg
      className="loading_spinner"
      width="60"
      height="20"
      viewBox="0 0 60 20"
      xmlns="http://www.w3.org/2000/svg"
    >
      <circle cx="7" cy="15" r="4" />
      <circle cx="30" cy="15" r="4" />
      <circle cx="53" cy="15" r="4" />
    </svg>
  </div>
)

export default LoadingSpinner

And maybe I've written some basic styles for it to animate the circles:

.loading_spinner-wrap {
  width: 100%;
  padding: 50px 0;
}

.loading_spinner {
  display: block;
  margin: 0 auto;
  fill: #000;

  circle {
    animation-name: upAndDown;
    animation-duration: 2s;
    animation-timing-function: cubic-bezier(0.05, 0.2, 0.35, 1);
    animation-iteration-count: infinite;

    &:nth-child(2) {
      animation-delay: 0.18s;
    }

    &:nth-child(3) {
      animation-delay: 0.36s;
    }
  }
}

@keyframes upAndDown {
  0% {
    opacity: 0;
    transform: translateY(0);
  }
  25% {
    opacity: 1;
    transform: translateY(-10px);
  }
  75% {
    opacity: 1;
    transform: translateY(-10px);
  }
  100% {
    opacity: 0;
    transform: translateY(0);
  }
}

Now, I can set up my DisplayList component to either render the LoadingSpinner component, or my list, depending on whether any items have been passed to it. Like so:

import React, { PropTypes } from 'react'
import LoadingSpinner from './LoadingSpinner'

const DisplayItems = ({ items }) => {
  return items.length ? (
    <div className="items">
      {items.map((item, index) => (
        <div className="item" key={index} {...item} />
      ))}
    </div>
  ) : (
    <LoadingSpinner />
  )
}

Display.propTypes = {
  items: PropTypes.array,
}

export default DisplayItems

Did you see what I did there? I removed the implicit return from the DisplayItems function, and then used a ternary operator to determine which component gets rendered.

If items has any length other than 0, the ternary will evaluate to true and thus render our items list. However, if the length of the array is 0, it will evaluate to false and render our LoadingSpinner component. You might end up with something similar to this:

You could, of course, use any other component that you would prefer to render instead. You can determine what's best for your project, and even what's best per component. But if you're looking for a way to indicate to your users that you're expecting data to eventually make it to your stateless functional component, perhaps this pattern will be useful to you.

Let me know if this is helpful to you in the comments and link to any examples you have of this trick or similar ones. I'd love to see them.

How To Use Client Side Libraries in a Universal JavaScript App

Thu, 01 Dec 2016 00:00:00 GMT

At work, I am building a JavaScript application with universal rendering. There are a number of challenges with building a universally rendered application, but one challenge in particular is making sure code that should only run on the client doesn't cause the server to crash.

Today, I built a React component that used the imagesloaded library to detect if any images nested in the component were loaded. This is very useful for downloading large images. You can set the opacity of the image to 0 until it loads, and then transition to a visible state.

Sadly, this is not as simple as importing the library and treating it like any other application. The reason: the window object doesn't exist in a Node environment. Thus, any code that requires the window object will fail, and often fail loudly (which are, of course, the best errors, pesky as they may be).

There are a number of possible solutions to this problem. Some involve setting a fake global.window object in your Node server. Another solution might be to use jsdom but I think that could be overkill. What we need is a solution that allows the code to harmlessly fail when it runs on the server, and then run as it should on the client. Here's the trick.

const isBrowser = typeof window !== 'undefined'
const imagesLoaded = isBrowser ? require('imagesloaded') : () => {}

It's really that simple. First we create a check for whether this code is being run on the client or on the server. If it's on the client, we require the library using CommonJS (not ES6 imports) and it runs as it should. If the code is being run on the server, we return an empty function that is perfectly harmless when called. It's a simple little trick to keeping your code from crashing your server.

Next Steps

I have not tested this out, but if you're trying to use methods from a client side library on the server and throwing errors, I believe you could add methods to an otherwise empty object. Make sure these methods are just empty functions, thus continuing the trend of harmless server side failure. And remember, it's not really failure. This code wouldn't do anything in that environment anyways.

In Webpack 2, I would take this code a step further and split it so it's not even requested until it is needed on the client, and thus present another potential solution to this problem.

Best of luck with this trick and building your own universal application. Let me know if you think of any hiccups that this technique might raise, or any other clever tricks you have up your sleeve for this scenario.

State Snapshots in Redux

Wed, 16 Nov 2016 00:00:00 GMT

Redux is a predictable state container for JavaScript apps. I've been using it in all of my apps recently and I discovered an elegant and clever use of it that I want to share. The rest of this article assumes you know how to use Redux. If you do not, follow the link above and read up before continuing this one.

The Problem I Was Solving

In one particular app I am working on, the UI depends upon state to determine the correct layout and color scheme. I have several elements (a logo, heading, and footer) that each are colored based on several booleans kept in state. When certain actions are taken, such as opening the nav, I need to change the state of those items. If the user were to close the nav without selecting a link, I need those elements to return back to the state they were in.

The first, most obvious solution was too simply fire actions that would change the color of each individual piece of UI like I had when opening the nav. This proved problematic. While I knew with certainty what state the UI should be in when the nav was open, I was not sure what state the UI should return to when the nav was closed. Trying to accommodate for every potential scenario would not only have been tedious, but buggy at best. Any new page in the app would have to be coded for. Then the solution dawned on me.

Snapshots

I could create a snapshot of any part of my state object, store it within that same state object, and then use its values to replace my current state at any given time. It's first-level "Inception" for your state.

This creating and applying a snapshot of state became a significant feature of the app as it was a much better way for returning to a previous state than my other efforts. Let's walk through the code to accomplish this.

The Code

Any Redux app requires a few things:

An initial state
Actions to dispatch and change state
Reducers to handle actions and return a new state object

Before I start tackling changing state, I like to consider what my initial state is. Generally, I define my initialState in the reducer file it belongs to, but for the sake of this article, I'm going to be repetitious, showing you what your initial state might look like and then copy/paste this into my reducer where it normally would be. Without further adieu, or initial state:

const initialState = {
  headingIsLight: false,
  logoIsLight: false,
  footerIsLight: true,
  navIsOpen: false,
  uiSnapshot: null,
}

We've added on particular property of interest to us, the uiSnapshot property. We're going to use this key to store pieces of our state. Since this is the initial state, we can set it to null for the time being (and will later see that this has an added benefit).

Next, we need actions to dispatch to our reducers. There are a number of strategies for handling action creators and action types out there and I'll leave it to you to research them. For now, I've been using an actionTypes.js file for all my types, and then creating action creators under an actions directory.

// actionTypes.js
export const OPEN_NAV = 'OPEN_NAV'
export const CLOSE_NAV = 'CLOSE_NAV'
export const TAKE_UI_SNAPSHOT = 'TAKE_UI_SNAPSHOT'
export const APPLY_UI_SNAPSHOT = 'APPLY_UI_SNAPSHOT'

// actions/ui.js
import {
  OPEN_NAV,
  CLOSE_NAV,
  TAKE_UI_SNAPSHOT,
  APPLY_UI_SNAPSHOT,
} from './actionTypes'

export function openNav() {
  return { type: OPEN_NAV }
}

export function closeNav() {
  return { type: CLOSE_NAV }
}

export function takeUISnapshot() {
  return { type: TAKE_UI_SNAPSHOT }
}

export function applyUISnapshot() {
  return { type: APPLY_UI_SNAPSHOT }
}

Before we dispatch actions, we need reducers to handle them (and technically we need reducers to create a store to even dispatch our actions). So next we create a reducer to define how we handle each of our action types:

import {
  OPEN_NAV,
  CLOSE_NAV,
  TAKE_UI_SNAPSHOT,
  APPLY_UI_SNAPSHOT
} from './actionTypes'

// Our initial state from before
const initialState = {
  headingIsLight: false,
  logoIsLight: false,
  footerIsLight: true,
  navIsOpen: false,
  uiSnapshot: null
}

const reducer = (state = initialState, action) {
  switch (action.type) {
    case OPEN_NAV:
      return Object.assign({}, state, {
        navIsOpen: true,
        headingIsLight: true,
        logoIsLight: true,
        footerIsLight: false
      })

    case CLOSE_NAV:
      return Object.assign({}, state, { navIsOpen: false })

    case TAKE_UI_SNAPSHOT:
      return Object.assign({}, state, { uiSnapshot: state })

    case APPLY_UI_SNAPSHOT:
      return Object.assign({}, state, state.uiSnapshot)

    default:
      return state
  }
}

export default reducer

So this part needs some explanation. In a Redux reducer, we handle each action.type with a different case. Each case is designed to return a new object with our desired state.

If you're unfamiliar with Object.assign, I would suggest reading up about it here. The first argument is our target, in this case, an empty object. Any following argument is deeply merged into our target. So we start by handling (virtually every) case by using Object.assign({}, state) and then pass another object containing just the state we want to change. In the OPEN_NAV case, we can see that we want to change 4 properties of our state, and thus pass an object containing those changes as the final source to our Object.assign() method.

Understanding how Object.assign() works is key to understanding how snapshots can be saved and applied. Let's say that in our store we dispatch an OPEN_NAV action, preceded by a TAKE_UI_SNAPSHOT action like so.

import store from './store'
import { takeUISnapshot, openNav } from './actions/ui'

store.dispatch(takeUISnapshot())
store.dispatch(openNav())

When we take our snapshot, the uiSnapshot property contains our entire previous state, including its own initial state of null. An example snapshot would look like this:

{
  headingIsLight: false,
  logoIsLight: false,
  footerIsLight: true,
  navIsOpen: false,
  uiSnapshot: {
    headingIsLight: false,
    logoIsLight: false,
    footerIsLight: true,
    navIsOpen: false,
    uiSnapshot: null
  }
}

As you can see, our state tree has been duplicated. Now when we apply the snapshot, we merge the value stored under uiSnapshot at the root level of our tree, which handily resets uiSnapshot to null. Thus, if a user closes the nav without choosing a link (and thus choosing a different state), we can close the nav and revert to the previous state just by applying the snapshot.

import store from './store'
import { closeNav, applyUISnapshot } from './actions/ui'

store.dispatch(applyUISnapshot())

Because navOpen: false is stored in the snapshot, the nav closes when we apply it to state (though, I would likely dispatch closeNav() to be explicit. There's no harm when Object.assign() encounters key/value pairs that are equal).

The Sky's the Limit

I think the uses for this technique are many and I wouldn't be surprised to find that it's already being used in lots of places. One potential use case I can think of is when an error in your application occurs, you could log out a snapshot of your entire state tree and use that snapshot for debugging purposes. I could also see it being useful if you just wanted to toggle between states while developing components.

Conclusion

Hope you find this technique useful. Please feel free to share any other use cases you can think of or any libraries already using this technique. I would love to read through the code and learn any new tricks I can from it.

Why I Think Opening External Links In New Tabs Is a Bad Idea

Sun, 27 Mar 2016 00:00:00 GMT

In previous posts I've mentioned my vehement dislike of purposefully opening links in a new tab. Here's a short list of reasons why it's a bad idea:

It's not the default behavior of links.
It's extra work, generally because the developer will code it to open normally, someone will see it and say that's wrong and then the developer needs to reopen the project, add the code and send it back.
It steals control away from the user. The user should be able to choose whether links open in this tab or a new one.
Lastly and most honestly, it's demeaning to the user. Let me explain.

Forcing a user to open a link in a new tab is almost always done to ensure that the user does not leave the website. This isn't the action of a confident website that knows the value of its content. This is done out of fear. Fear that a user will never come back. Fear that the back button might stop working. Fear that the user doesn't know how to open links in a new tab on their own. That's a little ridiculous.

In my opinion, if you want a user to stay on your site then you better provide them with content compelling enough to keep them there. Because stealing control away from the user displays a lack of faith in two ways. First, a lack of faith in the intelligence and ability of your user and customer. If you don't believe in your customer enough to trust them to know how to use your site, you should reconsider your relationship to the user. Second, exerting unnecessary control over the user is a lack of faith in your own brand and product. If your brand and product is compelling, users will stick around. Or comeback. People respond to confidence, online and offline. Shouldn't you have some confidence in yourself? Just some food for thought.

JavaScript: External Links in New Tabs

Sat, 26 Mar 2016 00:00:00 GMT

I've written before about my not so mild hatred for the request to open all external links in new tabs. For those who don't know, this is done by adding target="_blank" to the anchor tag. I don't like doing this for so many reasons, but I'll save that rant for another blog post.

Now, I've been asked to do this so often that automating this process was long overdue. I spent a few minutes and wrote some JavaScript that programmatically looks for external links and adds target="_blank" to them if necessary.

Now, the defining characteristic of an externally pointing link is that it has to be an absolute path and thus start with "http". We can use this to target only those links. Here's how:

function setTargetBlankOnExternalLinks() {
  const links = document.getElementsByTagName('a')

  for (var i = 0; i < links.length; i++) {
    if (/^http/.test(links[i].getAttribute('href'))) {
      const link = links[i]
      link.setAttribute('target', '_blank')
      link.setAttribute('rel', 'noopener noreferrer')
    }
  }
}

setTargetBlankOnExternalLinks() // call this after the DOM is ready

This is pretty straightforward. Find all the links, loop through them and check if they begin with "http" (The use of test() instead of match() here is important since test() returns a boolean while match() returns an array or null). This means that relative links are given a pass, and links that happen to have "http" in them elsewhere, such as "/link-to-blog-about-http" don't get mistakenly modified.

I hope this helps and saves you some time.

Intro to D3.js and Data Visualization

Sun, 13 Mar 2016 00:00:00 GMT

Recently, I worked my way through the D3 Intro Course taught by Ian Johnson over at Front End Masters and have been practicing what I've learned ever since. I'm not great at it (yet), and I haven't made anything too amazing, but I am getting a better grasp of this awesome library (big thanks to creator Mike Bostock and all his posts/tutorials about it).

I am currently working on a project at FINE that utilizes D3.js, so I wanted to code up an example for you. This way, you can see some of the techniques I might use in the project and perhaps inspire you to try out D3.js in a future project of yours.

First things first, you can't build a data visualization without first having some data to work with. Lucky for me, there's data everywhere. I decided for this example, I would create a dataset based on the people I work with everyday.

To do this, I created a JSON file, turning each one of my fellow devs into a an object in an array. Normally, you shouldn't objectify people, but I got their permission to so this time (Remember, there are ethics to responsible data visualization). Here's a small snippet of that JSON file:

{
  "teammates": [
    {
      "id": 1,
      "name": "Charlie",
      "birthdate": "1988-10-17",
      "position": "DevOps",
      "startdate": "2015-07-06"
    },
    {
      "id": 2,
      "name": "Eman",
      "birthdate": "1986-09-16",
      "position": "Front End",
      "startdate": "2015-05-12"
    }
    // More teammates here...
  ]
}

You Can't Do Data Visualization Without Some Data

Now I have some data to work with. I thought it would be interesting to create a bar chart that graphs each dev's age and how long they've been at FINE. This would be represented on the X axis and with a radio button would toggle between the two. Later, I will add some sorting methods to the Y axis. Let's start coding this up.

While we could code this visualization as a one-off piece of code, I think it's a good idea to follow the "Reusable Charts" pattern laid out in this awesome blog post. In short, a reusable chart turns our visualization into a function that can be called on multiple datasets. This way, when our dataset is updated, we simply re-render the chart with the new data. To do this, we need some basic setup to our code.

if (!d3.chart) {
  d3.chart = {}
}

d3.chart.fine_visual = function () {
  var data, svg

  function chart(container) {
    // Setup static elements of our visualization
    svg = container

    // Call update function to apply our data to our visualization
    update()
  }

  chart.update = update
  function update() {
    // Code the dynamic elements of our visualization
  }

  chart.data = function (value) {
    if (!arguments.length) return data
    data = value
    return chart
  }

  return chart
}

d3.json('teammates.json', function (err, teammates) {
  if (err) {
    return d3
      .select('.js-display')
      .append('p')
      .text('There was an error retrieving the data')
  }

  var data = teammates.teammates
  var display = d3.select('.js-display')

  var visual = d3.chart.fine_visual().data(data)
  visual(display)
})

The code starts by ensuring that the d3.chart object exists so that our custom function can be set as a property on the d3.chart object. This is followed by var declarations that will be scoped to our function. Next is the chart function which will be returned when this visual function is called. This is followed by setting a property on our chart function of our update function (so that we can call updates on our chart). Lastly, any chart property that can be customized by our end user needs this chart.property pattern to create getters and setters for the property.

Once the custom chart function is created, an AJAX call to the data is made. Upon returning the data, the custom function is called with the data supplied to it with the .data() setter.

The Chart() Function

The chart function within our custom function is where pieces of our visualization that will remain static should be instantiated. If this code is instead put in the update()function, it will be re-rendered to the page (meaning multiple axes would pile on top of each other). Thus, it follows that pieces of the visualization that will be updated are moved into the update() function.

An example of static content is an axis. A bar chart will have an X and Y axis, representing some scale of our data. In the case of my example, the X axis will represent time measured in months, and the Y axis will be used to identify different developers.

In order to add an axis to our visual, a decision must be made regarding what scale to use. D3 provides a number of different scale types, saving you from the hassle of coding your own (though you can if you want to). In this case, the linear scale will suit our purposes, but we could have also considered using the time scale as well. Be sure to read about d3 scales when you have a chance.

To implement the scale and append an axis based on it, the following code is used:

var xScale = d3.scale
  .linear()
  .domain([
    0,
    d3.max(data, function (d) {
      return age(d.birthdate)
    }),
  ])
  .range([0, width])

var xAxis = d3.svg.axis().scale(xScale).orient('bottom')

var xAxisGroup = svg.append('g')

xAxis(xAxisGroup)

I have left out some code on purpose here, namely the helper function age(), in order to focus on the more important pieces. A linear scale is declared, the domain is set from age 0 to the maximum age of our dev team, and the range is from 0 to the full width of our visualization. Then, an axis is declared and called on the svg var in an appended g element. The example follows a similar pattern for the Y axis, but uses the ordinal scale instead. I may cover the sorting functionality of the Y axis in depth in another post.

The D3 Pattern: Selecting, Entering, Appending, Exiting, Removing

Now that the axes are in place, the bars can be added to our chart. D3 has a pretty specific pattern to follow when rendering data driven elements to our visual. It seems downright counterintuitive at first, but begins to make sense the more you understand how d3 is acting upon our objects. This pattern looks similar to this:

var bars = svg.selectAll('.bar')
  .data(data);
  .enter()
  .append('rect').classed('bar', true)
  .attr({
    x: 0,
    y: function(d,i) { return i * 35; },
    width: function(d) { return xScale( age(d.birthdate) ); },
    height: 30,
  })
  .exit()
  .remove();

While this isn't the exact code used in the example, it's a good example of showing this d3 pattern at work. Because d3 can update elements already on the page, it's important that we select those elements. If not, we would end up creating a function that added a whole new set of elements each time the data was updated. This is why all elements are selected, then the data is entered, existing elements are updated, new ones are added and unused ones are destroyed.

Customizable Settings

The last convention I want to cover is how to add configurable settings on our reusable chart via adding a property to the chart() function. You may have noticed above, that we had a small bit of code looked like this:

chart.data = function (value) {
  if (!arguments.length) return data
  data = value
  return chart
}

This bit of code allows our user to get and set the data property for our chart. This is what enables us to reuse this chart in another instance or update our current chart by setting a new dataset. Typically, this is used on width and height properties to allow the user to customize the size of their visualization, but there can be many other uses.

Taking these concepts (and adding a few more I leave you to discover), a quick and interesting data visualization can be created. Play around with it a while and explore the code. Fork it on Codepen or make your own, and best of luck as you explore d3.js in the future.

<p class="codepen" data-height="770" data-theme-id="0" data-slug-hash="YqPNeo" data-default-tab="result" data-user="kyleshevlin"

See the Pen{' '} <a href="http://codepen.io/kyleshevlin/pen/YqPNeo/"> d3 Intro - Example for Mingle post </a>{' '} by Kyle Shevlin (<a href="http://codepen.io/kyleshevlin">@kyleshevlin</a>) on{' '} <a href="http://codepen.io">CodePen</a>. </p>

Using && and || in Bash Scripts

Wed, 09 Mar 2016 00:00:00 GMT

I write about Bash so often you might start to think it's all I do. It's not, but considering I spend a good portion of my day in the terminal, I'm always on the look out for ways to make it a more efficient experience.

Recently, I came upon a simple trick for bash scripts that just has to be shared. It involves the operators && (AND) and || (OR). In most cases, && and || are used for evaluation purposes, resulting in a boolean value (true or false).

In most languages, this would look something like this:

# Using Ruby for this example
foo = true
bar = false

if foo && bar; end # returns false; && requires both expressions to evaluate to true
if foo || bar; end # returns true; || requires only one expression to evaluate to true

The && Operator

Since we know that an && requires both expressions to be true, we can use this knowledge to chain bash commands that we only want to run in succession if the first command was successful. For example:

cd foo && touch bar.html

If the terminal is able to successfully cd into the directory foo, then it will attempt to create the file bar.html. If it fails, no attempt at file creation will be made.

The || Operator

In other circumstances, we might want to try one command and then another if the first fails. In this case, the || operator is our friend. I have specifically used this in a bash alias I've made for deploying a site. Depending upon what version of Capistrano is being used in a project, the terminal command syntax is different. Thus, we simply try one, and if it fails we try another.

# Literally my alias for deploying to production
alias capp="cap deploy -S loc=prod || cap prod deploy"

Putting Them Together

So, you can see that you can quickly use these to construct larger scripts that can do a rudimentary form of error handling without a lot of effort. Often, I need to deploy the same feature branch of code to multiple environments. I made a bash function using the && and || operators like I've laid out here to do just that with one short command.

# Deploy a branch to all branches
function mgdep () {
  # if no argument is passed to the function, get the current branch (the feature branch)
  if [ $# -eq 0 ]; then
      # get_git_branch is a bash function I've made that grabs the current branch
      branch=$(get_git_branch)
  else
    branch=$1
  fi

  git checkout master && git pull --rebase origin master && echo -e "\033[0;32mMaster checked out and pulled\033[0m"
  git merge $branch && echo -e "\033[0;32m${branch} merged into master\033[0m"
  git push origin master && echo -e "\033[0;32m${branch} pushed to master\033[0m"
  # You've seen my Capistrano alias above, ones for stage and dev are used further down
  capp && echo -e "\033[0;32m${branch} deployed to prod via master branch\033[0m"
  git checkout stage && git pull --rebase origin stage && echo -e "\033[0;32mStage checked out and pulled\033[0m"
  git merge $branch && echo -e "\033[0;32m${branch} merged into stage\033[0m"
  git push origin stage && echo -e "\033[0;32m${branch} pushed to stage\033[0m"
  caps && echo -e "\033[0;32m${branch} deployed to stage via stage branch\033[0m"
  git checkout dev && git pull --rebase origin dev && echo -e "\033[0;32mDev checked out and pulled\033[0m"
  git merge $branch && echo -e "\033[0;32m${branch} merged into dev\033[0m"
  git push origin dev && echo -e "\033[0;32m${branch} pushed to dev\033[0m"
  capd && echo -e "\033[0;32m${branch} deployed to dev via dev branch\033[0m"
  # Terminal-notifier lets me know all the deploys have completed
  git checkout master && terminal-notifier -message 'Deploys completed. Master checked out.' -sound 'default'
}

Conclusion

Hope this inspires you a bit and encourages you to create your own bash scripts for programmatically adding some efficiency into your development process.

My Favorite Git Aliases

Thu, 10 Sep 2015 00:00:00 GMT

If you're like me, you like to find patterns in your work and turn them into aliases and shortcuts in the terminal. I thought I'd share with you my current Git aliases, explaining a few along the way.

For starters, you'll want to add these aliases to your .gitconfig file.

[alias]
  br = branch
  brm = branch --merged
  brnm = branch --no-merged
  ci = commit
  co = checkout
  copl = "!f() { git checkout $1 && git pull --rebase origin $1; }; f"
  df = diff
  lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative
  mg = merge
  st = status
  plo = pull --rebase origin
  pho = push origin
  plod = pull --rebase origin dev
  phod = push origin dev
  plos = pull --rebase origin stage
  phos = push origin stage
  plom = pull --rebase origin master
  phom = push origin master
  reaper-nokill = remote prune --dry-run origin
  reaper = remote prune origin

Most of these aliases are self explanatory, but let's go through some of the less common ones.

brm

Using the branch --merged command will give you a list of branches merged into the branch you're currently on. It's counterpart branch --no-merged does exactly the opposite. These commands are great for cleaning up merged branches.

copl

This is a function that takes a branch name for an argument. It first checks out that branch, and then runs a git pull --rebase on that branch. I found myself constantly checking out a branch and pulling it immediately, so I turned it into one alias.

lg

This is a prettier log format. It will actually create the branch structure in the terminal.

reaper

Sometimes you need your local git to forget about remote branches that no longer exist. This is where pruning comes into play. When I first wrote this alias, it was repr for "remote prune". Phonetically, that sounded like "reaper" and given that I'm slashing branches from git, it seemed appropriate to rename the alias after our friendly harbinger of death.

So there you have it. Hope this Git aliases help you out. Leave some of your favorites in the comments below.

Bash Shortcut: Copy your Present Working Directory to your Clipboard

Sat, 25 Jul 2015 00:00:00 GMT

Like most developers, I'm always looking for ways to increase my efficiency. One way I like to do this is through Bash functions.

Just like other programming languages, Bash functions allow you to combine Bash commands or manipulate user input to output a desired effect. While I have a good number of Bash functions, today we're going to focus on a simple one: how to copy your present working directory to your clipboard.

While in your terminal, the present working directory (or pwd) is the directory you are currently in. Using the command pwd will supply you with an output of your current directory.

The other Bash command we're going to use is the pbcopy command. This command is short for "pasteboard copy" and will take the standard input and paste it on the clipboard. A nice feature of the pbcopy command is the ability to "pipe" (|) the standard output of one command into the pbcopy command. We're going to use that to make our Bash function. Put this in your .bash_profile or .bashrc file.

# Copy the PWD to the Clipboard
alias cpwd="pwd | tr -d '\n' | pbcopy && echo 'pwd copied to clipboard'"

Now we can use the command cpwd to copy our present working directory to the clipboard. I use this frequently for getting the right file paths for symlinks, but there are other uses as well.

Hope this helps!

Bash Shortcut: How to Make Directory and Change Directory in One Command

Sat, 25 Jul 2015 00:00:00 GMT

If you're like me, you're constantly using the command line to make a directory and then immediately change to that directory. Here's a Bash function that will allows you to do that:

# Make a directory && cd into that directory
function mkdircd () { mkdir -p "$@" && eval cd "\"\$$#\""; }

This function takes the user supplied directory name, makes all the directories needed to get there, and then cds to that directory.

Hope you find it useful!

Small Gripe: Target=“_blank”

Mon, 26 Jan 2015 00:00:00 GMT

I'm often asked to make small, almost trivial changes to our clients' websites. One of these changes that grinds my gears is the frequent request to "Make this hyperlink open in a new tab/window."

This bothers me because it changes the default behavior of links and takes away the user's control over his or her browser. Default behavior of a link is to open in the current window. Now, every browser/system I know of provides the user with an action that can open a link in a new tab (for example, cmd + click on Mac will do this). Adding a target="_blank" to a link robs the user of this ability.

Clients' reason that opening a link in a new tab will prevent a customer from leaving a site prematurely and not converting a sale. Shouldn't we have faith that our customers will stick around and buy products if they want to? One might even reason that removing the default behavior might be discomforting enough to turn away users.

My thoughts, don't selfishly change default behavior if you don't have to.

Here's a much better written article on the subject: http://css-tricks.com/use-target_blank/

Kyle Shevlin's Blog RSS Feed

AsyncData

Representing async data, imperatively

AsyncData and Result

Do I expect to ever use this?

Nothing is Something

data Attributes for Testing

Prefer Gaps To Margins

Why I dislike margins

Why I love gaps

Final thoughts

“Refactor” is Not a Scary Word

Why is it a scary word?

What does the word actually mean?

Implications of the proper definition

An example

Final thoughts

Fun Coding Exercise: Pyramid Slide Down

The problem

My initial thoughts

The solution

Optional steps

Conclusion

Algorithm: Sliding Window

The Problem

The Solution

Why is this the best way to handle this solution?

Summary

The Consciousness Lottery

How I Built “Test Your Focus”

Optimizations

Next steps

Full code

What ADHD Feels Like to Me

A non-exhaustive primer on ADHD

Understimulated

Stimulation Modifiers

Executive Dysfunction

Hyperfocus

Closing thoughts

Prefer Explicit Maps

Key takeaways

"Why didn't you use new Map()?"

My git Workflow for Refactoring

Some groundwork first

Our example

Step 0: Write some tests

Step 1: Refactor

Step 2: Adding our danger variant

Step 3: Review & Merge

Summary

Additional resources

Never Call new Date() Inside Your Components

A step further

Let's make another example

Wrap up

Composable Flourishes

Our component

Additional things to consider

prefers-reduced-motion

No JavaScript

Wrap up

Prefer Alphabetized Object Keys

What about logical groupings?

How do I make this easy to do?

Wrap up

Responsive Design and Composition

Multiple compositions to the rescue

Design System Retrospective

What problems were we solving?

Inconsistency

Developer velocity

A dumpster fire of an existing "design system"

My solution

Using composition to design

So what was the problem?

What I would do differently

Summary

Prefer Noun-Adjective Naming

Prefer Multiple Compositions

`AsyncData`

`AsyncData` and `Result`

`data` Attributes for Testing

"Why didn't you use `new Map()`?"

My `git` Workflow for Refactoring

Step 2: Adding our `danger` variant

Never Call `new Date()` Inside Your Components

`prefers-reduced-motion`

`align-items: center` vs. `text-align: center`

No Outer `margin`

What are "outer" `margin`s and `padding`s?

Type `TODO`

Tip: Sometimes `any` is ok

Joke: You shouldn't use `TODO` excessively

Using `children`