We’ve been on a forked version of Relay v8 for a couple years. While the new versions had some neat features, nothing really compelled us to upgrade until now. Relay v11 (the one with hooks) is the biggest release since Relay Modern & it’s amazing. Aside from hooks, it lets us use React’s Suspense API instead of the render props pattern, allows for fine-grain control of query invalidation, and provides patterns for avoiding waterfall queries. While we’ve been able to clean up a bunch of our code, there have also been a few sharp edges during the migration. Let’s explore.

Partial Data and Client Fields

In our app, queries only need to load once. After the initial fetch, we use subscriptions to keep the data fresh. The only problem is figuring out how to prevent Relay from disposing of the query after the component got unmounted. In previous versions, we did this by forking the QueryRenderer. In v11, it’s as easy as setting the fetch policy to store-or-network and increasing the buffer size: const store = new Store(new RecordSource(), {gcReleaseBufferSize: 25}). The only gotcha was that any clientField would always get flagged as missing. For example, we had a field handler that turned rich text into plaintext for client-side searches:

{
  content @__clientField(handle: “contentText”)
  contentText
}

In the above case, the record was flagged as missing. To determine which field caused this, I put a breakpoint in the DataChecker to pause when a missing field was hit.

The workaround is to set the hidden clientField record. It’s kept on the parent object under the handleKey. For example, every client handler we write now starts with this preamble:

const handler: Handler = {
  update(store, payload) {
    const {dataID, handleKey} = payload
    const record = store.get(dataID)!
    const handleKeyValue = record.getValue(handleKey)
    if (handleKeyValue === undefined) {
      record.setValue(null, handleKey)
    }
  }
}

By initializing the value from undefined to null the record is retained & regarded as available.

Subscriptions & Cached Queries

There’s only one problem with trusting subscriptions to keep all the data fresh: bad internet. If a computer goes to sleep, or a cell phone goes through a tunnel, it’s safe to say the data is stale & should be refetched. Connectivity logic isn’t app specific, so it should live outside the app. In our case, we use a package called Trebuchet to handle connectivity. When the client loses connection with the server, Trebuchet alerts the app that it is disconnected, kills the websocket, & starts a new one. Once it reconnects, it fires reconnect callbacks. In this case, we simply refresh the active queries:

useEffect(() => {
    const refresh = () => {
      loadQuery(variablesRef.current, {fetchPolicy: 'network-only'})
    }
    environment.transport.trebuchet.on('reconnected', refresh)
    return () => {
      environment.transport.trebuchet.off('reconnected', refresh)
    }
  }, [])

This is SO much more elegant that what we’ve done in the past!

Hooks

It took me awhile to understand usePreloadedQuery, useQueryLoader, and loadQuery. These were all new concepts because the QueryRenderer is the equivalent of the new useLazyLoadQuery. That hook is discouraged because it can lead to waterfall loading just like before. In my experience, it also didn’t lend itself well to the Suspense pattern, so I decided to forgo it entirely & go with useQueryLoader.

Since my app previous used QueryRenderer extensively, it was already set up to perform lazy loading queries. I created a helper hook that makes useQueryLoader operate similarly to useLazyLoadQuery:

const [queryRef, loadQuery] = useQueryLoader<TQuery>(query)

const varRef = useRef(variables)
if (!areEqual(variables, varRef.current)) {
  varRef.current = variables
}

// refetch when variables change
useEffect(() => {
  loadQuery(variables || {}, {fetchPolicy: 'store-or-network'})
}, [varRef.current])

As you can see, loadQuery gets called immediately when the component renders. While this pattern doesn’t make the data show up any sooner today, it keeps the door open in case I want to do some optimization later down the line . If I had used useLazyLoadQuery, those future refactors would be harder.

When I combine this hook with the query refresh hook above, it makes for a great one-liner that guarantees fresh data. The only problem was partial data…

Partial Data

Relay now supports partial data by default, which means a component can render as long as its fragment can be completed from the local cache. This is amazing! The only problem is that it doesn’t play well with createFragmentContainer. In other words, if you replace your QueryRenderer with usePreloadedQuery, any child components that use createFragmentContainerwill not trigger suspense (as of React v17.0.2 + Relay v11.0.2). For example:

const Child = createFragmentContainer(() => {
  return <div>props.user.pet.name</div>
}, {
  user: graphql`
  fragment Child_user on User {
    pet {
      name
    }
  }`
})

const Parent = () => {
  const data = usePreloadedQuery(graphql`
      query ParentQuery {
        user {
          ...Child_user
        }
      }
    `,
    queryRef
  )
  return <Child user={data.user}/>
}

In the above scenario, The data in parent is partial. Child does not have the required data to render, yet it still gets called! If Child instead uses useFragment, it would suspend correctly. However, the same problem would still apply to descendant components. This left me with the following options:

• Refactor ALL instances of createFragmentContainer to useFragment
• Include ...Child_user @relay(mask: false) in the Parent so the Child won’t render early (which would also cause Parent to subscribe to ALL changes and re-render a bunch)
• Refactor just Child to useFragment & pray that it requests a field that is not already cached so it suspends
• Change the fetchPolicy to network-only and admit defeat
• Use UNSTABLE_renderPolicy: 'full' with usePreloadedQuery

I opted for the 5th option. renderPolicy is eventually going away, but it’s still there, and using it here buys me some time so I don’t have to immediately refactor all my createFragmentContainer components to useFragment.

Paginated Queries

The final hurdle was migrating to usePaginationFragment. The new API for this hook is beautiful in its simplicity; bravo to the team for simplifying what is a ridiculously difficult area! Refetch queries are now generated automatically via a refetchable directive. There were only 2 gotchas during this refactor.

First, pagination only applies to fragments, so I found myself calling usePreloadedQuery and usePaginationFragment in the same component. It felt weird to have a query & fragment in the same component, but it is otherwise harmless.

Second, the refetchable fragment is on Query. Maybe I’m alone, but this was the first time I’ve ever fragmented on the Query type. Usually I fragment on Viewer, but I couldn’t figure out how to declare my User object as using the Viewer protocol.

Entry Points

Entry points allow you to fetch different components based on the data returned. This is a really cool concept, but honestly I don’t use it for 2 reasons.

First, React.lazy is good enough. Sure, it requires an extra round trip, but that roundtrip is for a .js, which comes from our CDN so it’s extra fast.

Second, and most importantly, we have a Progressive Web App (PWA). That means most of those async chunks are fetched from the CDN via service worker long before they’re used. Sure, the client might not use every chunk, but making the app faster only costs us a few extra gigabytes/month of throughput. At Facebook scale, the cost may be prohibitive. At our scale, it’s literally pennies.

Conclusion

Overall, the initial upgrade took 2 days to complete. The business case to upgrade was the following:

• The old version had old dependencies with known vulns
• Declarative errors & loading states using Data Fetching with Suspense
• Attract new developers with our clean, modern codebase
• The new API is simpler, so it’s easier to train new developers on the new patterns
• Less code (AKA surface area for bugs) using directives like appendEdge
• Easier to upgrade to a newer version when the next killer feature drops

Now that the patterns are in place, we can distribute the work across our team and complete the refactor in the coming months. We won’t explicitly create issues to refactor from createFragmentContainer to useFragment. However, if one of us is already working on a component that uses the legacy API, we’ll take an extra minute to upgrade to useFragment. We call this “in the neighborhood” refactoring. We use it for massive, app-wide refactors such as migrating to Typescript or Emotion for CSS-in-JS. It’s been a great pattern to ensure that each developer can still ship user value & work on challenging problems.

GraphQL is great. Every GraphQL endpoint agrees to speak the same language of {data, errors} and that makes communication between servers easy. Now suppose two public APIs both speak GraphQL; what advantages can we leverage? Packages like graphql-tools make it easy to merge and stitch schemas together, which allows teams to build out separate parts of their subschemas via join and union functionality. But what about 3rd party schemas that have their own authentication, rate limiting, and errors? For example, take a look at GitHub’s GraphQL API. Wouldn’t it be great if you could nest GitHub’s endpoint in your own schema? In a single GraphQL query, you could get the user’s name from your application as well as their bio from GitHub:

# Application schema
query {
  viewer {
    name
    githubApi {
      # GitHub's schema
      query {
        viewer {
          bio
        }
      }
    }
  }
}

Of course this is only the beginning. A client could update your app and GitHub without any extra backend logic. Just good ‘ol GraphQL:

mutation ($userId: String!) {
  addFriend(userId: $userId) {
    user {
      name
      githubApi {
        mutation {
          followUser(input: {userId: $userId}) {
            user {
              bio
            }
          }
        }
      }
    }
  }
}

With nest-graphql-endpoint, this is finally possible 🎉.

The Business Case

Building a successful SaaS today means meeting customers where they are — integrating against the tools they already use. I’ve built integrations for Slack and Atlassian, but when it came to building a GitHub integration, I noticed I was re-creating a lot of the logic that GitHub’s API already had built-in.

For example, our planning poker meeting fetches all the team’s stories from GitHub, provides a fun, immersive way to score each story, and exports the scores back out to GitHub. Without nesting GitHub’s schema, I made my own GitHubIntegration object that had a repos field. That field had a custom resolve function that fetched the repos from GitHub by using a handwritten GraphQL string. This wasn’t great for a few reasons:

• It’s extra code that I have to maintain
• The query doesn’t expressively show front end devs which parts comes from GitHub
• Without a dataloader, multiple queries can cause multiple fetches to GitHub
• Even with a dataloader, multiple fetches to GitHub are unavoidable unless every query is identical (thus overfetching)

What I needed was a way to batch all the fragments going to GitHub, merge them into a single network request, and then parse the response into their corresponding fragments again. Why batching? Because in the real world, queries can get pretty large & often repeat themselves:

query {
  viewer {
    githubApi {
      query {
        ...Bio
      }
    }
    myTasks {
      user {
        githubApi {
          query {
            ...Bio
            viewer {
              bio
              id
            }
          }
        }
      }
    }
  }
}

fragment Bio on _extGitHubQuery {
  viewer {
    bio
  }
}

How it Works: nest-graphql-endpoint

For all of this complexity, I wanted a way to nest endpoints in my schema with just a single line of code:

const mergedSchema = nestGitHubEndpoint({
  parentSchema,
  fieldName: 'githubApi',
  parentType: 'User',
  resolveEndpointContext: (source) => ({accessToken: source.accessToken})
})

That’s it! Your User object now has a githubApi object that includes queries, mutations, and errors. resolveEndpointContext allows you to fetch and provide necessary keys to access the endpoint.

Behind the scenes, here’s how it works:

1. It fetches the GitHub schema & prefixes all the __typename fields so you can write your query without worrying about naming conflicts
2. It collects all the fragments inside the gitHubApi objects & merges them into a single query
3. It prunes unused variables, variable definitions, & fragments
4. It un-prefixes the __typename fields so GitHub understands the query
5. In the event of a name conflict, it will alias fields before the request is fetched
6. It de-aliases the response, re-applies the __typename prefix, and filters the errors by path

Let’s see how it’s built.

Building the GitHub Schema

GitHub offers a great package called @octokit/graphql-schema. It provides a GitHub schema that is guaranteed to be up to date so I don’t need to asynchronously fetch the introspection schema. Then, I use graphql-tools’ wrapSchemato rename the types with my prefix. wrapSchema internally adds a proxying resolver that calls their delegateToSchema function. Since we’re handling all the fetching ourselves, we can overwrite that resolver with the default GraphQL resolver:

(source, _, _, info) => source[info.fieldName]

Finally, we use graphql-tools to merge our wrapped schema into our parent schema. That gives us an object extension that looks like this:

user {
  githubApi {
    errors {...}
    query {...}
    mutation {...}
  }
}

Note that errors is its own field, even though it will be populated by the response of query or mutation. By design, GraphQL makes it seemingly impossible for 1 field to populate the response of another. To get around this, the errors field returns a promise & exposes the resolve callback to the other operations by mutating the source. You can call it hacky, but I think it’s pretty clean 😎.

Batching the Fragments

Before the days of Urql, Apollo, and Relay Modern, I wrote a bad GraphQL client cache called Cashay. While the project didn’t go anywhere, it taught me a bunch about the GraphQL AST. For example, traversing an AST is painful, but GraphQL has a node visitor function built-in!

Let’s suppose our query has a bunch of variables, but only some of them need to be sent to GitHub. How do we figure out which variables to prune? It’s as simple as:

const usedVariables = new Set<string>()
graphql.visit(selectionSet, {
  Variable(node) {
    usedVariables.add(node.name.value)
  },
})

This same pattern can be repeated for fragments, variable definitions (the chunk that looks like $foo: String!, $bar: ID), and even the __typename fields that we prefixed. Once each fragment is refactored into a standalone query, it is time to batch as many together as possible and merge them.

To accomplish the batching, we use a dataloader with the caching functionality turned off. Why no cache? Each request will have a query that is a little different than the others. For example, one fragment might ask for viewer {id} while the other asks for viewer {id, bio}. We want to merge those together, and if we cached based on the key, then they’d be kept separate.

That said, we want to reuse the same dataloader for the entire execution, so we keep all the dataloaders in a WeakMap where the key is the context because a new context is created for each call to GraphQL.execute. By using a WeakMap, we are preventing a memory leak because as soon as GraphQL.execute no longer references the context, it will be garbage collected from the WeakMap, too.

Once a single tick has passed, dataloader calls its batch function with an array of queries & variables that we can merge together. First, we merge all the fields that have unique names. Then, if two fields share a name, we compare all their children. If the two fields are different, we alias one of them:

# Before
query {
  repository(name: "parabol", owner: "parabolinc") {
    id
  }
}
query {
  repository(name: "nest", owner: "mattkrick") {
    id
  }
}

# After
query {
  repository(name: "parabol", owner: "parabolinc") {
    id
  }
  repository_2: repository(name: "nest", owner: "mattkrick") {
    id
  }
}

This strategy allows us to batch an endless number of fragments together into one network request. We just have to keep a list of the aliases we added so the final response looks just like the #Before request.

Handling the Response

When GitHub responds, it might not be a GraphQL object. GitHub could be down, or the gateway could take too long to respond, or if the auth token was invalid, it might just send{message}. To handle those cases, the executor wraps the fetch with a timeout & if the response doesn’t look like a GraphQLExecutionResult, it will coerce it into one.

Once we have something in the shape of {data, errors}, all that’s left to do is create one response object for each fragment. That means de-alias the fields that we renamed, re-prefix the __typename fields, and filter errors by fragment. Filtering errors is easy because most errors have a path that shows where the error occurred. For example, if the path is['viewer', 'repository_2'] , then we know the error should only appear in the 2nd fragment.

Conclusion

Nesting GraphQL endpoints is the next step in GraphQL’s world domination. In a future where every service uses a GraphQL schema, integrations will be a breeze to implement and require a bunch less code. Sound like fun? We’re hiring. Let’s build cool stuff together.

Nesting GitHub’s API in your GraphQL Schema was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

Scaling is relative. When Uber builds a scalable metric service, they build a proprietary database to resolve their queries. When Facebook scales a live feed, they build it to support millions of connected clients. This post is for the rest of us. Subscriptions in GraphQL have taken a back seat and it’s my goal to change that.

The most popular subscription client is abandonware and uses an insecure, inefficient protocol. That means those of us who want to build a real-time app are forced to roll our own. So if you have dreams of hitting 10,000 connected clients, but you’re also terrified that it might cause your server to catch fire, read on. We’ll walk through the GraphQL reference implementation, tear it apart to maintain a stateless execution service, and use some clever tricks to keep your response times way lower than any hosted GraphQL service out there.

GraphQL Subscription Basics

The lifecycle of a graphql query is pretty simple. The server receives a query, parses it, validates it, then resolves it. Using graphql-js , a basic implementation simply calls the graphql function. A slightly more advanced implementation caches the parsed & validated query AST so the server only has to worry about calling execute. Subscriptions are similar, except since we want an async iterable instead of a promise, we call subscribe instead of execute.

Behind the scenes, the subscribe function does only two things. First, it creates a source event stream. Then, for every source event, it maps the event to a response. It’s simpler than it seems. A source event is nothing more than what gets posted to the PubSub. That event then gets passed to the execute function and out pops the response, which you can send to the client.

There’s a good reason for two streams. Imagine Alice triggers a mutation like CreateTask and we want to tell Bob about that. So, the mutation pushes the source event to the PubSub, but what should the source event include? To answer that question, we need to know what Bob had requested. Maybe Bob wants the entire Task, or maybe just who made the task. Heck, he may just want to know the updated total number of tasks! Since we can’t be sure until we look at Bob’s subscription (which might be on a different server) the best we can do is include the bare minimum: a taskId and the payload type to resolve the response, like CreateTaskPayload (Pro tip: sharing a payload type between mutations and subscriptions greatly simplifies your business logic, see The Hybrid Strategy for GraphQL Subscriptions).

The ability for a single event to transform into a bespoke response for each subscriber is powerful, and something GraphQL offers out of the box. The problem arises when we begin to scale — our GraphQL execution service is tightly coupled to the WebSockets and subscriptions that rely on it. In a perfect world, our GraphQL execution service would be stateless, and our subscription service would maintain the subscriptions and WebSocket connection. So let’s build it.

Creating a Stateless Execution Service

In a production application, GraphQL queries and mutations can come in from a variety of sources. From our client app, they arrive as persisted queries. From our GraphiQL admin interface, they come in as a full string that will need to be parsed & validated. If it is a webhook or superuser, it might use a private schema. If the caller is a subscription, we’ll need to pass in a rootValue and hopefully reuse the dataloader to reduce resolution time. No matter the business logic, there is no state preserved by the service. This is important because as we squeeze performance out of it, we only have to focus on improving throughput, not memory management. That means we can incrementally improve the service by introducing graphql-jit, deploying more instances around the globe, and using dataloaders more aggressively (see tips below).

Creating a GraphQL Subscription Service

With query execution solved for, all that remains is building a service that holds onto the state: the transport (WebSocket, SSE, or WebRTC) and GraphQL subscriptions. Think of a subscription like a database cursor, except in the form of an async iterable.

The life of a subscription begins with emitting an event to the PubSub (e.g. Redis, RabbitMQ) from a mutation. From there, the PubSub listener needs to look up a list of GraphQL Subscriptions and republish the event to each. It’s a PubSub inside a PubSub, and you can build one in 50 LOCs. Note that while some npm packages offer this functionality, I have found them to be largely inefficient (e.g. unnecessary lookup tables) and at times leak memory. In my experience, if it’s 100 LOCs or less, it’s better to build vs. buy.

The second trick is to convert that event callback handler into an async iterator. If this looks a little intimidating, don’t worry. The article Understand Async Iterators Without Really Trying teaches you how to do it in 5 minutes using a simple click listener. Why not NodeJS streams or observables? Simply because async iterators are native ECMAScript, which is why graphql-js chose to use them.

Now, instead of calling subscribe, which uses the default execute function, we call createSourceEventStream, which will return the source event stream we just created. While the function may seem esoteric, this is exactly why it was built. The final step is to transform the source event into a response by asynchronously calling our stateless execution service. While the full implementation is less than 50 LOCs, the gist is even shorter:

async next() {
  // wait for a new source event from the PubSub
  const sourceIter = await this.sourceStream.next()

  // if the event is "done" then there's no value
  if (sourceIter.done) return sourceIter

  // include the socketId of the user that triggered the mutation 
  // and the dataLoaderId so we can reuse it
  const {mutatorId, dataLoaderId, rootValue} = sourceIter.value

  // include everything needed to execute the query
  const {socketId, authToken, query, variables} = this.context

  // ignore the listener if they triggered the mutation
  if (mutatorId === socketId) return this.next()

  const result = await callStatelessExecuteService({
  query,
  authToken,
  dataLoaderId,
  variables,
  rootValue,
  socketId
  })
  return {done: false, value: result}
}

And there we have it! The ResponseStream is calling our stateless execution service instead of defaulting to an execute call. As we grow the number of stateless execution services, we can put them behind their own reverse proxy (or even use a hosted service). We can also independently scale our socket servers, which will become critical as we strive to reduce intra-team latency for our growing international user base. But before we do that, we’ll want to make sure we squeeze all the efficiency we can out of each service.

Maximizing Efficiency

Tip #1: Use a DataLoader

Getting all the efficiency out of a stateless execution service begins with the dataloader. As you determine which queries are hot, you can refactor your direct database queries to using a dataloader. This will save duplicate queries, which is extremely useful for graph-type data structures (it’s called GraphQL for a reason!). For example, if a Team requests a User that requests the Team, it’ll only request the Team once. Caching individual DB hits is far more powerful than something that caches the entire query, and far more beneficial for real-time results.

Tip #2: Reuse DataLoader for Subscriptions

If your business logic allows, you can reuse the same dataloader that your mutation used for the subscription. In practice, this can reduce your resolution time to <1ms for subscription payloads. All that’s required is a dictionary of dataloaders with a TTL on each. Again, nothing that 50 LOCs can’t fix. To reuse the dataloader, simply publish its ID so the subscription service knows which execution service to call.

Tip #3: Lazily Instantiate DataLoaders

In earlier versions, before every GraphQL execution I would create an object with about 30 dataloaders in it and add that to the GraphQL context. After profiling the heap usage, I found that it was allocating/GCing ~16KB per request! So, by using a getter pattern, I refactored the class to only instantiate a dataloader when used. By using some Typescript trickery, I was able to maintain the same type-safe guarantees so typos are still caught before runtime.

Tip #4: Use graphql-jit

After a GraphQL query is parsed and validated, you’re left with an AST that doesn’t have predictable return values. While this isn’t too important to the developer, it’s hugely important to the V8 JavaScript engine. graphql-jit rewrites the AST into a function that provides predictable return types, which reduces the admittedly non-trivial overhead that GraphQL uses.

Tip #5: Don’t Monitor so Gosh-Darn Always

Hosted GraphQL solutions that offer a monitoring “feature” do more harm than good. The overhead of these services — checking the resolution time for every single GraphQL field is not trivial. Have a problem that you need to narrow down? Monitor up. But once things look good, don’t accept a 20%+ increase in resolution time as a cost of doing business.

Tip #6: Use Persisted Queries

Replacing the full query string with a hash is both more efficient and secure. In our app, certain subscription queries were upwards of 15KB. Assuming an MTU of 1500 bytes, that means sending 10 packets to the server — a difficult task for a mobile device on the go. A single hash guarantees it fits into a single packet. Using a persisted query also means the query is trusted. No annoying “security researchers” making arbitrarily deep queries in an attempt to DOS our server. The only gotcha is that we need to know if the hash refers to a a subscription or a query/mutation to dispatch it to the correct service. To do that, you can write a custom hashing function that prefixes the query hash with the operation type.

Tip #7: Use Execution Results to Update Subscription State

Whether you use a JWT or a session ID, chances are your WebSocket has some authentication state that a GraphQL mutation may change. For example, if you have a resetPassword mutation, you’ll probably want to force all other connected clients for that user to log out. Simply check the payload type of the result, and handle it appropriately. In practice, this allows us to guarantee the validity of the JWT for the session, which means we only have to check the JWT blacklist when the socket connects. That’s a huge performance win and addresses the #1 concern that’s always brought up in the cringeworthy, never-ending “JWT is bad” debates.

Tip #8: Popular Doesn’t Mean Better

What’s the difference between a Junior and Senior Developer? The Senior knows that the sexy hosted solution with the CLI that sets up your project in “3 Easy Steps” is going to be the bane of your existence in 6 months when you’re locked into its walled garden and you need to do something it doesn’t support. Hosted solutions are buggy. A small SaaS can go broke. A megacorp can sunset services with little warning (Google, anyone?). You know what’s sexy? A vanilla GraphQL server on bare metal.

Wrapping Up

There you have it. Everything I’ve learned about GraphQL Subscriptions after 4 years of trial and error. If playing with this stuff is interesting to you, join the fun and PR some open source projects! For example, graphql-jit needs a PR to support subscriptions. If getting paid to write open-source code is your jam and you’d like to do it from anywhere in the world (cheers from Medellín, Colombia) we’re hiring folks to come build the future of remote work.

Nobody likes a callback. It’s like a modern day equivalent of a GOTO statement. But how can we replace those pesky ones like click handlers? Chances are, you’ve refactored all all the easy ones into async/await statements, but there are still those pesky holdouts like DOM events, WebSockets, event emitters, and any other stream-like object. Sure, we could turn those into Observables, but turning 1 callback into 3 doesn’t seem like much of an improvement. If I can promisify a function, why can’t I iterable-ify an event stream? The answer is the new 2018 async iterables, and since it was first proposed a few years ago, there has been a lot of old, confusing, and just plain wrong info out there. So, through the magic of trial and error, here’s how I wrote a helper to turn click handlers into for-loops.

Starting Simple

In programming, just like in life, lazy is usually better. So, when I build something new, I like to be as lazy as possible and delay writing code that makes me think. So, let’s just write what we want it to look like & stick all the hard stuff in a black box:

// I want to go from this
document.addEventListener('click', (event) => console.log('click')

// to this
const clicks = streamify(document, 'click')
for await (const event of clicks) {
  console.log('click')
}

So far so good! Now we just need that magical streamify function to actually do something. We know it’s going to call addEventListener, which takes a handler that gets the event. So let’s fill in just the easy parts and put the hard stuff in another black box:

function streamify(element, listener) {
  const handler = (event) => {
    // do magic here
  } 
  element.addEventListener(listener, handler)
}

Progress! Now avoiding the difficult things, let’s figure how to return an “async iterator”. To be honest, I’m not really sure what that looks like, I can’t just write new AsyncIterator(), but I know async means promise and an iterator is something that returns more than 1 value, kinda like a generator, so let’s roll with that and return an endless supply of promises. Useless functions are my specialty, so that’s easy:

function* streamify(element, listener) {
  const handler = (event) => {}
  element.addEventListener(listener, handler)
  while (true) {
    yield new Promise(resolve => resolve(event))
  }
}

Now we’re hoeing where there’s taters! It looks like the handler is getting an event and the Promise is yielding an event, so now I just have to somehow move the event from the handler to the Promise. The dumbest thing I can think of is just sharing a variable, so let’s do that:

function* streamify(element, event) {
  let nextResolve
  const handler = (event) => {
    nextResolve(event)
  }
  element.addEventListener(event, handler)
  while (true) {
    yield new Promise(resolve => {
      nextResolve = resolve
    })
  }
}

And there we have it! We have a working streamifier! When a click event comes in, it resolves with the promise we gave it. Pretty sweet! …until someone clicks really fast.

Robustifying the Streamifier

The naive solution only works for slow events. If 2 events get fired in quick succession, the 2nd call will get swallowed. We don’t want that, especially if we’re using this for something like websockets. So, what the heck, if 1 shared resolver is good, an array of them must be better! Let’s just queue the events as they come in:

function* streamify(element, event) {
  const pushQueue = []
  const handler = (event) => {
    pushQueue.push(event)
  }
  element.addEventListener(event, handler)
  while (true) {
    yield new Promise(resolve => {
      const nextEvent = pushQueue.shift()
      resolve(nextEvent) // error! no nextEvent
    })
  }
}

Succe…er, no. This solves the push problem, but now we’re getting an error because the iterator is requesting a click event before one exists. Dang. Well, a queue worked for pushing events, why not use one for pulling in resolvers?

function* streamify(element, event) {
  const pushQueue = []
  const pullQueue = []
  const handler = (event) => {
    const nextResolve = pullQueue.shift()
    if (nextResolve) {
      nextResolve(event)
    } else {
      pushQueue.push(event)
    }

  }
  element.addEventListener(event, handler)

  const pullValue = () => new Promise(resolve => {
    const nextEvent = pushQueue.shift()
    if (nextEvent) {
      resolve(nextEvent)
    } else {
      pullQueue.push(resolve)
    }
  })
  while (true) {
    yield pullValue()
  }
}

Wooo! it works! Now I can click as fast as I want forever! …but what if I only want to listen to the first couple? Natively, I would call removeEventListener, but the handler function is hidden away in our sweet new wrapper. How can I remove it when the stream ends? Well, I’ll start simple & just write how I want it to look:

// from this
let clickCount = 0
if (clickCount++ > 2) {
  document.removeEventListener('click', handler)
  console.log('Bye!')  
}


// to this
let clickCount = 0
for await (const event of clicks) {
  console.log('click', event)
  if (clickCount++ > 2) clicks.return() // this breaks the loop
}
console.log('Bye!')

I know the generator value has that magic return() method, but I wish i could write it myself so I could also call removeEventListener. I know that little * isn’t actually magic; it just tells the function to wrap the return value in a special object with 4 methods. So, let’s ditch the star & write the generator how the engine actually reads it (plus add our little extra handler):

function streamify(element, event) {
  ...
  return {
    [Symbol.asyncIterator] () {
      return this
    },
    next: () => ({
      done, // TODO how do we calculate this?
      value: pullValue()
    }),
    return: () => {
      element.removeEventListener(listener, handler)
      return {done: true}
    },
    throw: (error) => ({done, value: Promise.reject(error)})
  }
}

That may look daunting, but it’s really just a bunch of boilerplate that the * gives us for free. In the bad old days before generators, we used to have to write similar hacky things all the time. Today, that boilerplate should look pretty familiar because it’s the same stuff you see when you log Set or Map to the console.

Let’s see what we got: TheSymbol.asyncIterator() method tells the rest of the world to treat this like a generator instead of an object that just happens to have the exact same fields. Everything else returns an object with a done field and maybe a value. If done is false, we know we can expect some kind of value — and since this is an async iterator, I’m guessing that value is gonna be the same pullValue() promise we were yielding before. All that’s left to do is figure out the value of done when next() gets called. Since we know done should be true if throw or return gets called, let’s do like we did before & and share the variable in the outer scope:

function streamify(element, event) {
  ...
  let done = false
  return {
    [Symbol.asyncIterator] () {
      return this
    },
    next: () => ({done, value: pullValue()}),
    return: () => {
      done = true
      element.removeEventListener(listener, handler)
      return {done}
    },
    throw: (error) => {
      done = true
      return {done, value: Promise.reject(error)}
    }
  }
}

… and we’re done! I can now write a for-loop that iterates every time an event comes in. If I don’t like the value, I can call throw. When I’ve had enough, I can call return.

Here’s how it looks all put together:

const streamify = function (element, event) {
  const pullQueue = []
  const pushQueue = []
  let done = false
  const pushValue = async (args) => {
    if (pullQueue.length !== 0) {
      const resolver = pullQueue.shift()
      resolver(...args)
    } else {
      pushQueue.push(args)
    }
  }

  const pullValue = () => {
    return new Promise((resolve) => {
      if (pushQueue.length !== 0) {
        const args = pushQueue.shift()
        resolve(...args)
      } else {
        pullQueue.push(resolve)
      }
    })
  }

  const handler = (...args) => {
    pushValue(args)
  }

  element.addEventListener(event, handler)
  return {
    [Symbol.asyncIterator]() {
      return this
    },
    next: () => ({
      done,
      value: done ? undefined : pullValue()
    }),
    return: () => {
      done = true
      element.removeEventListener(event, handler)
      return {done}
    },
    throw: (error) => {
      done = true
      return {
        done,
        value: Promise.reject(error)
      }
    }
  }
}

Conclusion

If you’ve scrolled all the way to the bottom to find the link to the GitHub repo, here it is.

In 5 minutes, we’ve written a 50 LOC wrapper that goes toe-to-toe with all the competing dependency-infested packages out there. After wrapping our events, we can finally proclaim that we no longer write code with callbacks. The dream of 2012 is here! Best of all, instead of learning what an async iterable is, we learned how to use it. We didn’t have to break out the functional programming textbooks to study the definition of a Subject, Deferrable, or Disposable. Instead, we built something practical — like taking a cooking class and walking away with dinner. Way more fun than CS theory.

The only question that remains: just because we can, does that mean we should? From a clean code perspective, maybe! But what about performance? Promises are inherently slower than callbacks, and on top of that, we’re calling shift() a bunch on 2 queues. Running the code in Chrome 67, it’s 2x-100x+ slower than native callbacks for 100–1,000,000 events. When the code gets transpiled to ES5, that grows to 20x-1000x slower! So from a benchmarking standpoint, it’s plain awful. But in the real world, that equates to literally an extra 0.1ms to handle 10 concurrent events. Pretty fair trade for ditching the callbacks!

Understand Async Iterators Without Really Trying was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Back in late 2016 I wrote an article called GraphQL: Tips after a year in production. Since then, GraphQL started offering native subscriptions, Relay got so good you could replace Redux with Relay Modern, and I learned a few neat tricks along the way. I’ve also made a bunch of mistakes. Looking back on my GraphQL journey, here’s what I’d change.

1. Use a DataLoader from the get go

DataLoader is a small cache that is beautiful in its simplicity. Instead of caching the entirety of the GraphQL response, it caches database queries to be used in resolve functions. I put off implementing it in my app for fear that it was a premature optimization. Boy was I wrong. Looking back, I should have done it a lot sooner. Aside from the generous performance boost, it simplified my resolve functions by standardizing how I fetch things from my database. Less code = less room for me to write bugs. The only drawback is that the cache wasn’t designed to work for subscriptions. To fix that, I wrote my own little (100 LOCs) add-on package called dataloader-warehouse. Instead of caching data for each subscriber, it gives you the option to cache data for each publish, essentially turning an O(n) operation into O(1), which is nice.

2. Mutation Fragments in your Subscription Payload

If you have a real-time app (and who doesn’t? It’s 2018!) You’ve probably written a few GraphQL subscriptions to keep all the data on your page fresh without a pesky refetch. The biggest mistake I made in GraphQL is how I organized my subscriptions. I started out by building 1 subscription for each page view in my app, but that meant my back-end had to change whenever the front-end changed. Next, I tried breaking subscriptions into CRUD types for each entity, e.g. CreateTaskSubscription, UpdateTaskSubscription, DeleteTaskSubscription. That was awful for 2 reasons: I had 3x more code to maintain, and I still had to write hacks because sometimes I needed to know how it was updated. For example, was a single task deleted, or was a user deleted, which triggered 10 calls to DeleteTaskSubscription?

Finally, I arrived at something I call the Hybrid Strategy. It works by first breaking the mutation payload into a fragment.

fragment UpdateTaskMutation_task on UpdateTaskPayload {
  task {
    dueDate
  }
}

Then, using the power of GraphQL, I include that fragment in both my mutation and my subscription:

mutation UpdateTaskMutation($task: Task!) {
  updateTask(task: $task) {
    error {
      message
    }
  ...UpdateTaskMutation_task
  }
}

subscription TaskSubscription {
  taskSubscription {
    __typename
    ...CreateTaskMutation_task
    ...DeleteTaskMutation_task
    ...UpdateTaskMutation_task
  }
}

Because the subscription shares the mutation fragment and handler, I’m guaranteed that if the mutation works, the subscription works. To learn more, see The Hybrid Strategy for GraphQL Subscriptions.

3. Errors in the payload

In the code sample above, you probably noticed that I included an error object in the response for updateTask. It goes back to the timeless question, “If I succeed at failing, was I successful?”

Errors are the same way. I used to throw them, but that made it difficult to figure out if the error was something I threw or if it was something unexpected. If I threw it, I wanted to use it in a client-side error message, but if it was unexpected, I wanted a generic “Server Error” message to hide the gory details. By writing every mutation with a succeed-by-failing mentality, I can replace any thrown error with that generic message. I can also extend the returned error object to make it as helpful as possible, because nothing makes me hate an app more than hitting an error and not knowing how to fix it. To track what errors folks are seeing, you can even send an alert to your exception tracker whenever you return an error. I wrote a whole bunch on the topic in The Definitive Guide to Handling GraphQL Errors.

4. Simplified Folder Hierarchy

In my original post, I advocated for breaking your queries into folders by entity type. Since then, my app has grown from medium-sized to large, and the hierarchy didn’t scale with it. Some mutation files were growing to well over 1000 LOCs, which were just a pain to look at. Now, I advocate for a flatter hierarchy of 4 folders: 1 for each of your queries, mutations, subscriptions, and types. Each file contains a single query (or type) and life is a lot simpler. Sure, there are a a lot more files, but just get yourself an IDE that auto-imports as you type and you’ll never need to rummage through the folder. The only exception is for Connection and Edge types — I create those with a helper and export them from the same file as the base type.

5. You probably want an Interface

The boilerplate advice is to use an interface for things that are related, and a union for things that aren’t, but have common fields (whatever that means). In practice, I tried using unions plenty of times, but always refactored them to interfaces. In fact, the only unions in my entire app are my subscription payloads (since they’re the amalgam of many mutations). Since interfaces can share fields, your queries will be cleaner since you can extract shared fields before you fragment on the specific types. Additionally, as your data structures get more complicated, you can sub-class them, which becomes very useful.

For example, let’s say I have a Vehicle, which is either a Car or a Truck. Every Vehicle has an Engine, but a Car has a CarEngine and a Truck has a TruckEngine:

const vehicleFields = () => ({
  engine: {
    type: Engine
  }
}

const Vehicle = new GraphQLInterfaceType({
  fields: vehicleFields
})

const Car = new GraphQLObjectType({
  fields: () => ({
    ...vehicleFields(),
    engine: {
      type: CarEngine
    }
  })
})

const Truck = new GraphQLObjectType({
  fields: () => ({
    ...vehicleFields(),
    engine: {
      type: TruckEngine
    }
  })
})

Sidenote: By thunkifying my shared fields, it makes schema changes pretty painless.

Now, I can write my queries in a very concise manner, without the need for extra fragments. For example, if a truck engine is just a car engine with an auxiliary power unit, I can get everything I need with a single fragment, instead of having to fragment on both Engine and Truck.

vehicle {
  engine {
    horsepower
  }
  ... on Truck {
    bedSize
    engine {
      APU
    }
  }
}

While it doesn’t look like much here, this makes component fragments in your app much cleaner. It also means Relay-generated flow types are as accurate as possible, which saves me from myself. You may be asking yourself, if 2 types are almost the same, why not just use the superset and leave a few fields blank? That was my strategy to avoid interfaces, and it served me for awhile, until it didn’t. Given enough time, your types will evolve to the point to where you’ll need to interface them. A good rule of thumb is if you know the best path forward, spend the extra time to do it right, if you don’t, pick the fastest path. For me, that means building interfaces from the start.

6. Use your schema to generate typings

If you use typescript or flow, chances are you’ve found yourself building typings that look a lot like pieces of your schema. For the Relay folks, you already get bespoke flow types for every fragment you create, but those don’t include things like enums and query input variables. For things like these, I use gql2ts (the successor to gql2flow) to generate types for general use. You can even use these types on your Node server, which can be pretty helpful when writing more complex resolve functions. This single source of truth is a huge benefit because now when you extend an interface, you don’t have to remember to extend your flow type, too.

Looking forward

With these tips, I hope you manage to avoid some of the time-consuming pitfalls that got me. GraphQL continues to be a great pleasure to use, and that’s largely because of the growing, active community around it. There are still plenty of best practices I haven’t touched on here, including schema stitching, internal schemas, using GraphQL to transport OT/CRDT changes, persisted queries, etc. If you’ve found some neat patterns yourself, or think some of mine are baloney, be sure to let me know!

GraphQL: 3 Years in, and lessons learned was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.

Click here to share this article on LinkedIn »

Recently, I screwed up and it resulted in a client getting a white screen when they used our app. Like most apps, we have an initial GraphQL query that fetches a ton, including a list of all your notifications. One of those notifications referenced a field that no longer existed in the database (oops!). The result? GraphQL was a champ and sent both data and errors to the client. But the client, well it completely ignored the data because it handled the response as an error. In hindsight, that was pretty dumb. It’d be like flunking a student for getting less than 100%. It just ain’t right.

GraphQL’s ability to send both data and errors is nothing short of amazing. It’s like having a talk with a real human: “Hey Matt, here are those results you wanted. I got you everything except that task field; I went to look it up, but it didn’t exist in your database.” With all this power, we could do some really cool things on the client! Unfortunately, most client code boils down to this:

if (result.errors) throw result.errors[0]

That’s not perfect, but if we didn’t throw an error, then the onError handler wouldn’t be called, which is how I propagated server validation errors to the UI. So, choosing between writing a flawless server and not receiving server errors, I went with the former — and it worked for almost 2 years! …until it didn’t.

Identifying Error Types

To make sure I fixed the root cause, I started researching all the types of errors we throw in our app and all the ways other folks handle GraphQL errors. There are a plethora of errors that a client can encounter when querying a GraphQL Server. Whether it’s a query, mutation, or subscription, they all fall into 6 types:

1. Server problems (5xx HTTP codes, 1xxx WebSocket codes)
2. Client problems e.g. rate-limited, unauthorized, etc. (4xx HTTP codes)
3. The query is missing/malformed
4. The query fails GraphQL internal validation (syntax, schema logic, etc.)
5. The user-supplied variables or context is bad and the resolve/subscribe function intentionally throws an error (e.g. not allowed to view requested user)
6. An uncaught developer error occurred inside the resolve/subscribe function (e.g. poorly written database query)

So, which of these errors are critical enough to ignore all the data? Numbers 1–3 for sure, since they occur before GraphQL even get called. Number 4, too, it calls GraphQL, but only receives errors in response. For 5–6, GraphQL responds with both partial data and an array of errors. Some would conflate type 5 with type 2, for example running out of query “points” (like what GitHub does) could constitute an HTTP 429 (too many requests). But at the end of the day, the simplest answer is the best: If GraphQL gives you a result with data, even if that result contains errors, it is not an error. No changing HTTP codes based on error types, no reading the errors to decide how “critical” a particular error is, and no reading the data to see if it’s usable. I don’t care if the result is {data: {foo: null}}. Data is data; any arbitrary nully logic implemented after GraphQL returns is just that: arbitrary.

Following this logic, error types 1–4 would be sent as errors to the client because there is no result.data. But what about types 5–6?

Don’t Intentionally Throw Errors in GraphQL

As of March 2018, neither Apollo-Client (including subscriptions-transport-ws) nor Relay Modern is perfect at handling errors. Relay’s mutation API comes close with its onCompleted(result, errors) callback, but this is sorely missed for queries and subscriptions. Apollo is extra flexible with its ErrorPolicy; but neither offers best practices, so I propose my own: If the viewer should see the error, include the error as a field in the response payload. For example, if someone uses an expired invitation token and you want to tell them the token expired, your server shouldn’t throw an error during resolution. It should return its normal payload that includes the error field. It can be as simple as a string or as complicated as you desire:

return {
  error: {
    id: '123',
    type: 'expiredToken',
    subType: 'expiredInvitationToken',
    message: 'The invitation has expired, please request a new one',
    title: 'Expired invitation',
    helpText: 'https://yoursite.co/expired-invitation-token',
    language: 'en-US'
  }
}

By including errors in your schema, life gets a lot easier:

• All errors are sanitized and ready for the viewer before they hit the client
• You don’t need to throw a stringified object and parse it on the client
• You don’t have to send the same error in 22 different languages (you know who you are)
• You can send the same error as a breadcrumb to your error logging service
• Most importantly, your GraphQL errors array won’t include any user-facing errors which means your UI won’t ignore them!

For mutations (and subscriptions), that’s an easy sell. Even easier if you follow my hybrid approach to subscriptions because your subscriptions reuse your mutation payloads. But what about queries? There exists a dichotomy in GraphQL best practices today: mutations and subscriptions return a payload full of types, but a query just returns a type. Using my blunder as an example, imagine a request where team succeeds but notifications fails:

mainQuery {
  team {  #succeeds
    name
  }
  notifications { #fails
    text
  }
}

To avoid losing partial data, we treat the whole thing as a success, but in doing so, we lose the errors! How can we get both? We can’t go back to throwing errors for the reasons listed above, but wrapping every object is a payload would be pretty ugly:

mainQuery {
  teamPayload {
    error {
      message
    }
    team {
      name
    }
  }
  notificationPayload {
    error {
      message
    }
    notifications {
      text
    }
  }
}

While it’s not ideal, this would only apply when the UI needs to know about an error. Sound familiar? It functions just like an error boundary in React:

The granularity of error boundaries is up to you. You may wrap top-level route components to display a “Something went wrong” message to the user, just like server-side frameworks often handle crashes. You may also wrap individual widgets in an error boundary to protect them from crashing the rest of the application.

So if returning a null or empty array suffices, go right on ahead; but send the event to your exception manager to track it. If you notice a particular query piece is failing regularly, then you can wrap it using a payload to create a pseudo error boundary. While more art than science, this means I treat all GraphQL operations the same, and I don’t needlessly bloat my entire schema.

Now when it comes to trusting the client, if the client shouldn’t see it, your server shouldn’t send it, which brings us to the final handler.

How to Hide Your Shortcomings (from the client)

Remember the good old days when all errors were unintentional? Nowadays playing catch with errors is more common than, well, actually playing catch (looking at you React v17 with your crazy promise throwing internals).

After refactoring our intentionally thrown errors into a regular field in our response payload, any remaining errors must be unintentional (i.e. developer errors), which means we should cover our tracks and replace the message with something vague like: “Server Error”. In a perfect world, these would be caught, sanitized, and returned as an error property in the response, but you’ll never catch ’em all (so you can stop wrapping every single statement in a try/catch). We still send the real error to our logging service so we can fix it before anyone knows its broken, but the client should never see it because the error might include sensitive things like our actual database queries that we use in production. Along with the vague message, it is worthwhile to keep the error’spath, since that will help us determine where the error occurred. Again, simple is best: For every error in errors, send a generic message and path to the client alongside the partial data.

Once that result is on the client, it will be handled as a successful request. You could even ignore the errors and be fine (and if it’s a query, you might have to!). However, if you wanted to make use of it, you could still reference it anywhere the errors array is available. Putting it all together, here’s how it looks in Relay Modern:

// Called for error types 1-4 (5xx, 4xx, missing/invalid query)
const onError = (err) => {
  this.setState({err})
}

const onCompleted = (result, errs) => {
  // Called for error type 6 (eg unexpected missing DB field)
  const err = errs.find(({path}) => path.includes('approve'));
  if (err) {
    onError(err.message);
  }
  
  // called for error type 5 (eg expired auth token)
  const {approve: {error: {message}}} = result;
  onError(message);
}

commitMutation(env, {mutation, onCompleted, onError})

Remember, this works perfectly for mutations, but queries and subscriptions swallow errors unless they’re thrown, which means if you want it in your UI, you better put it in your schema!

Conclusion

tl;dr

• If GraphQL gives you results.data, it is not an error, so don’t throw it on the client.
• If the viewer should see the error, return the error as a field in the response payload. If it’s a query, make a response payload.
• Replace any remaining GraphQL errors with a generic message, but don’t throw it on the client and don’t expect the UI to always be able to handle it.

Whether it’s for a query, mutation, or subscription, we identified 6 distinct types of errors that a request can encounter when returning a GraphQL response. We came up with a strategy to guarantee that partial data is never ignored by the client. Finally, we ensured that the viewer always sees the errors we want them to see (and nothing more!). We also managed to avoid the deep, dark rabbit hole of throwing custom errors like GraphQLConnectionError that seem so popular despite their shortcomings. How do you handle errors? Is this already common knowledge and I’m just late to the party? Let me know.

The Definitive Guide to Handling GraphQL Errors was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Business Case

Too much boilerplate, team members never documenting their action creator APIs, the ebbing battle of connecting to smart containers vs. dumb components, code-splitting reducers, memoizing selectors, merging local and domain state, async actions, accidental mutability. If you’ve ever written a moderately complex Redux app, you know the struggle is real. If you’re just starting out and wonder why it’s so complicated, you’ve probably just been told to hush or given some sage hippie advice like

Thankfully, the community has rallied together to invent some pretty neat workarounds. Need async functionality? Plop a generator in your middleware and call it a saga. Need to memoize? Use reselect. Need to eliminate boilerplate? Pick your favorite action creator package that turns 20 simple lines into 10 confusing ones. Heck, I even jumped on the bandwagon and wrote a store enhancer so you had a GraphQL-esque documented API in your devtools. At the end of the day, Redux worked and the code shipped; but I’d be lying if I said I wasn’t tempted to turn React’s new Context API into my own simple state store. Thankfully, as of v1.5.0, Relay is shipping with a client schema, and my code is looking a lot cleaner.

Using the Client Schema

As of today, the client schema is “undocumented”, which is a facebook alias for “freakin sweet”. Getting it running is simple:

Write the schema. While you can’t create new types exclusively for the client (yet?) you can use types you created in your server schema. For this example, imagine contentFilter is an input that filters out tasks that don’t include the supplied contentText:

extend type Team {
  contentFilter: String
}

extend type Task {
  contentText: String
}

This is where the real magic is. If I were using Redux, I’d create a TeamReducer and TaskReducer. Then, since I enjoy splitting code & splitting headaches, I’d asynchronously add those reducers to the store when the dependent components mounted. With Relay, I request these fields just like any other field in my fragment. No extra connect(), no runtime errors because the fragment is compiled at build time, no “dumb component” debate, and the code spliting comes free with the compiled query.

Compile the schema. Adding the client schema is as easy as adding an arg:

relay-compiler --schema serverSchema.graphql --client-schema clientSchema.graphql

Mutate! Do I use deep freeze or immutable.js? Maybe I just trust that my team will use Object.assign correctly for each reducer? Nah, forget it. Thankfully, Relay has it handled with that sweet commitLocalUpdate:

reactRelay.commitLocalUpdate(environment, (store) => {
  store.get(teamId).setValue(e.target.value, 'contentFilter');
});

That’s right, the same API you know & love for server mutations is used for local updates. Boilerplate be damned!

Memoizing

If something is calculated from state, does it become state, too? MobX might call it “computed” state. Redux just says “who cares, memoize it”. But how can you handle that with Relay? In our real-world example above, I need to take a draft-js object, turn it into a string of plaintext, and match against a regex. Now, turning 50 draft-js objects into strings on every keystroke isn’t exactly cheap, so it’d be nice to memoize. I could memoize it at the component level by keeping it in state, which is essentially what reselect does, and that works perfectly well! …but what if I could memoize at the app level? With this one weird trick, I can combine my client schema with a custom handlerProvider.

Write the handler. For any field containing a draft-js stringified object, I want to parse it, extract the text, and set a peer contentText field to the result:

const ContentTextHandler = {
  update(store, payload) {
    const record = store.get(payload.dataID);
    const content = record.getValue(payload.fieldKey);
    const {blocks} = JSON.parse(content);
    const fullText = blocks.map(({text}) => text).join('\n');
    record.setValue(fullText, 'contentText');
  }
};

Provide the handler. Relay has a default handler (so that’s how they do the magical stuff with connections!). By extending it, the world is your oyster:

const handlerProvider = (handle) => {
  switch (handle) {
    case 'connection': return ConnectionHandler;
    case 'viewer': return ViewerHandler;
    case 'contentText': return ContentTextHandler;
    default: throw new Error(`Unknown handle ${handle}`);
  }
};

For more info, read the docs

Trigger the handler. There’s a secret __clientField directive that Relay provides so you can do magical things. By including it in the query, you can recompute state whenever the query is run.

fragment on Task {
  content @__clientField(handle: "contentText")
  contentText 
}

Now, whenever a query comes in, Relay looks for that handler and generates the plaintext for that decorated field. Pretty sweet! (Note that you’ll still want to call ContentTextHandler.update in your mutations/subscriptions, this only runs on queries.)

Conclusions

And just like that, you can avoid reducer boilerplate hell, use GraphQL to document your local API, get code splitting for free, memoize at the application level, and be the envy of all your friends when you tell them your domain and local state share a single source of truth. Got any other neat patterns for Relay? Let me know in the comments.

After a whole lot of trial and error, I finally came across a pattern that scales linearly with your app. Hopefully, it’ll keep you from suffering as you embark on real-timeifying your app.

Some Background

The holy grail is a page where every piece of domain state updates in real-time, the code is maintainable, and there is no overfetching. That’s as true today as it has been since the first AJAX request. After all, pseudo-real-time apps have been around for decades. You send an AJAX every 5 seconds for everything on the screen and you’re there. The problem is that when it really counts, 5 seconds is too long, and when activity is sparse, 5 seconds is too short. Subscriptions fixed this because instead of dry humping the server ad infinitum, the server tells you what’s changed.

Meteor was the first framework to really leverage this using what’s called a LiveQuery. It tailed the MongoDB Oplog and pushed the changes to subscribed clients. RethinkDB later perfected this by building a natively reactive database. Both strategies are good, but suffer from 2 problems:

First, the overfetching: If you care about the content of a Todo and someone changes the priority, you’re still handling the whole gosh darn document. Sure you could pluck individual fields before you send to the client, but then that subscription cannot be reused across the app, and from there it’s overfetching the whole way down.

Second, and most importantly, they’re limited by how the data is stored. If you care about a Team as well as the number of Todos they are have, you either need to denormalize that count onto the Team table, or you need to also subscribe to a Todo count and patch the 2 together. Back-end changes to accommodate the front-end? That’s a code smell.

Enter GraphQL

GraphQL changed all this with their newfangled data-transform pipelines. It can even be used for a LiveQuery like those mentioned above, although I don’t recommend it (to learn why, I highly recommend the awesome talk from GraphQL Summit). With GraphQL, a subscription is no longer limited by how it is stored in a database because each subscription triggers a client-defined query. The only problem left to solve is how to segment subscriptions. After talking to a lot of folks, reading a lot of code, and trying a lot of stupid things, I learned there are 3 ways to segment subscriptions: per-query, per-entity, and per-mutation. Let’s look at each.

Per-query Subscriptions

The siren of the bunch. You just got the thumbs up to make a piece of your app reactive so you build a subscription around a single component. If any data in that component’s query changes, your subscription will let you know with a single beautiful payload. Unfortunately, your marketing team then changes the layout of the page and you quickly learn that as your components change, your server must change. Updating 10 mutations and your subscriptions because a new<Footer/> got added is lame, so you hunt on for a better pattern.

Per-Entity Subscriptions

This type of subscription is the most popular. From PubSub textbooks to GraphQL example repos, you see it everywhere. It’s pretty simple: if you have a mutation that modifies a Team with ID of 123, then you publish a message to Team.123 in perfect Topic.Channel fashion. Simple, right? Well, until you call an AddTeam mutation. If you publish to channel Team.124, no one will be listening yet, so you’ll need to post it to parent channel, such as Team.userId. Another channel just for listening to teams you get added to? Not great, but not terrible.

Next, assume that you have a RemoveFromCompany mutation that removes you from every Team and for every team, removes each Todo item. The poor client listening on theTeam and Todo channels is going to receive 1 message for each Todo, Team, and company; That’s m*n + m + 1 messages! A client handling 100 updates in quick succession may drop below 60fps, but again, not terrible. A smart batching strategy can easily mitigate this.

Third, and here’s where it gets fun, is that per-entity subscriptions inherently overfetch. Imagine a ChangeTeamName mutation. You only change a single field, but the subscription returns the entire Team object because you share it with other mutations. Sure, some of those fields may be expensive to fetch, but what’s a little overfetching if it means the code is maintainable…

Unfortunately, maintainability is a nightmare, which brings us to the real reason why per-entity subscriptions are bad news: they transfer state, not the event. For example, if I pop a toast when a Todo gets removed, will RemoveFromCompany trigger 100 toasts? If a user got added to a team, are they brand new, or did they reactivate? Who added them? Was it you from your cellphone while you’re looking at the same page on your computer? At the end of the day, I came to the harsh realization that I needed more than just state. I needed the event.

Before realizing what the problem was, I solved this by bifurcating state and event into separate Team and Event channels. I told myself the Team channel would handle updates to the Team object, and the Event channel would handle any toasts or one-off messages. As the app grew and business logic changed, I realized the Event payload often contained the entire Team object and I didn’t even need the Team channel! In fact, the Event payload was almost identical to the payload of the mutation that triggered it, yet here I was working tirelessly to squash bugs to keep the 3 separate queries and handlers returning the same result. Like an idiot.

Per-mutation subscriptions

A subscription is a mutation you didn’t know you wanted. With that in mind, it makes perfect sense to subscribe to a mutation. Imagine a subscription payload that looks identical to the mutation payload, sharing a single handler and query fragment. When business logic changes, you go to the single source of truth to update.

Unfortunately, where per-query subscriptions fail because they require constant changes to the back-end, per-mutation subscriptions fail because they require constant changes to the front-end. Imagine if you had a single channel for each mutation, like ChangeTeamName.123. Any component that used the team.name field would also have to subscribe to it. Looks like another dead-end for maintainability.

Secondly, we’re still overfetching. The mutation payload likely provides more data than the component needs. For example, the RemoveFromCompany payload might include teams, but your TodoList component only cares about the Todos that got removed. Do you chose to overfetch, or do you write a second handler?

Hybrid Subscriptions

If you already have subscriptions, you probably implement some sort of hybrid without realizing it. Either you have separate ADD/REMOVE/UPDATE subscriptions and subscribe to all 3 simultaneously on the client, or your subscription payload is a union of an added item, removed item, or updated item, or you just fetch the whole item regardless of the type (which gets tricky for deleted items!). Regardless, both per-entity and per-mutation subscriptions lack maintainability and suffer from overfetching, but in opposing ways. Back in the days of fixed-payload subscriptions, we had to pick one. Thankfully, this is where GraphQL saves the day. We can take the best parts of per-entity and per-mutation strategies and create a new type of hybrid subscription that has never been possible, until now…

… just kidding! Paywalls suck, Medium.

How to implement Hybrid Subscriptions

Let’s start with the server. In the ChangeTeamName mutation, we return a ChangeTeamNamePayload like team { name }. We know publishing to a channel like ChangeTeamName.123 will make life hard for the front-end developers, so instead, we publish to Team.123. Why use entity-based channels? Because it’s the perfect compromise. If we published everything to a single channel, then we’d be sending the user every message, even the ones don’t don’t affect her current view. She probably doesn’t care about an updated Todo item if she isn’t currently looking at her list of todos! Conversely, it’s cruel to make a <Team/> component rely on an ever-changing list of mutations that affect the team; but <Team/> and <TodoList/> components that both subscribe to a Team subscription? Yeah, that’s manageable.

Next, the only thing to add to your call to publish is the mutation name: publish(Team.123, {team, type: ChangeTeamNamePayload}). The subscription payload is simply a union that resolves the concrete type based on this type. It’s so easy it’s like the Betty Crocker of real-time apps.

Since mutations and subscriptions return the same object type, they can share handlers. Since subscriptions do the grouping on the server, components don’t have to. All that’s left to fix is the overfetching.

To solve this, I break each mutation query up into standalone fragments. For example,

fragment ChangeTeamNameMutation_team on ChangeTeamNamePayload {
  team {
    name
  }
}
ChangeTeamNameMutation {
  ...ChangeTeamNameMutation_team
}
TeamSubscription {
  ...ChangeTeamNameMutation_team
  ...ChangeTeamColorMutation_team
}

As seen, in the subscription I include every fragment with a _team suffix. Not too hard, but a codemod could make it even easier (*hint hint*). Writing per-channel fragments and handlers makes great sense because 1 mutation calls many subscription channels, and 1 subscription is triggered by many mutations. Since GraphQL lets you fragment on type, this isn’t a problem. Even for mutations that can return widely varying payloads (ie a ToggleTeam mutation that either adds or removes) you can still employ unions and interfaces. Even better, it means if all your business logic lives in the same handler. Need to pop a toast to the mutator, quietly update the state on the mutator’s other devices, and announce a separate message to the rest of the team? No sweat. Here’s what it looks like in production.

Conclusion

Hope this inspires you to add some real-time functionality to your app! Thanks to GraphQL, I’m able to write subscriptions that use the same queries and handlers as my mutations, which means they’re maintainable, have drastically reduced overfetching, and best yet, the pattern scales modularly so you can make your app reactive 1 mutation at a time, which should make your boss happy. Working on something similar? Reach out!

The Hybrid Strategy for GraphQL Subscriptions was originally published in HackerNoon.com on Medium, where people are continuing the conversation by highlighting and responding to this story.

Unfortunately, being a new library, there are a lot of questions left for the community to solve:

• How do I pass the environment down my render tree?
• How do I switch between environments?
• When do I unsubscribe?
• Where do I trigger a subscription?
• What caching strategy should I use?

…And that’s just the front end! What about the server?

• How do I filter out the message for the person who made the mutation?
• Where do I authenticate the subscription requests?
• What if I need to kick someone off a subscription?

Well, here it goes.

The Front End

Enviroment

When you read the Relay example, you see an environment variable that gets passed into a QueryRenderer, and it’s all good. But how does it go through nested routes? Passed via props? Good Lord no; it’s a prop, not a peace pipe. We could just create a singleton, but that’s only 1 step better than attaching it to window. The answer, elegantly solved by Redux’s Provider, is context. Just make yourself a Provider & any child that wants it can grab it. But context isn’t great for stateless components, so you’ll probably want to make a withAtmosphere HOC that puts it in the props for you. Why do I call it Atmosphere?

Creating the Atmosphere

My app uses http to fetch results until the user hits a component that needs a websocket, and then it switches. When I no longer need the websocket, it switches back to http. Some routes can even use http or websockets, depending on where they come from. In other words, the environment used by a QueryRenderer is non-deterministic and I need something that handles it all. Naturally, the atmosphere encompasses all environments, so that’s what I called it.

To set the Atmosphere, I first made a class that stored all the environments & could return the current one with something like atmosphere.get(). This was easy enough, but each environment had its own store so some things got refetched and I ended up calling withAtmosphere all over the place.

The cleaner alternative was to extend Environment. This gave me 2 benefits: I could get at it from any fragment container viaprops.relay.environment and my networks shared a store (albeit at the cost of unsafely using the internal _network, but I like to live dangerously). Now, upgrading to a socket fetch is as easy as environment.setSocket(). I can even hardwire my fetchQuery functions as methods inside the atmosphere. That way if my http authorization header changes, I don’t need to create a whole new environment, i just environment.setAuth().

Unsubscribing

Way back when, in the days of Relay Classic, there was something called a clientMutationId. It was a simple ID that accompanied a mutation on its journey through request & response. While it’s no longer needed for mutations, the concept works beautifully for subscriptions. Each subscription request sends along an opId (name borrowed from Apollo). Then, when it’s time to unsubscribe, the client just sends the opId that it keeps in its Atmosphere. Finally, if we put the requestSubscription in Atmosphere, then we can completely abstract away the opId in favor of returning a simple unsubscribe function that gets passed to our components. In Facebook land, this could be used to unsub from a newsfeed story after a user scrolls past it. But how do we start the subscription without reverting our sexy functional components back to boring Component classes?

Where to Subscribe

Just like Redux’s famous connect(mapStateToProps), subscribing when a component mounts can be as easy as withSubscriptions(subscription). But what if you want multiple subscriptions? Unfortunately, GraphQL spec 5.1.3.1 (yes, I’m fun at parties) clearly states that only 1 subscription is allowed per operation. This is a bummer because most queries need at least 3 accompanying subscriptions (added, removed, updated) to keep it fresh. Again, borrowing from Redux’s compose function, we can gather up all of our unsubscribe functions and execute when the time comes.

Personally, I don’t like to unsubscribe on unmounts. The reason is simple: imagine an app with 100 todo items. That’s an expensive query. Now imagine the client navigates away and then back again. You’ll have to refetch the query because the data went stale as soon as the subscription ended. If you wanted to turn it into an inequality, it’d be something like this:

NumMessagesAfterUnmount * AvgMessageSize < P(ReturnVisit) * QueryCost

If the client leaves the page & receives 10 1KB messages, it’ll cost you 10KB. If there’s a 20% probability that they return to the page and issue a new 100KB query, then the expected value is 20KB. That means if you kept the subscription alive you’d save twice the data! You could even use page analytics to determine the exact probability of a return visit and tweak accordingly. At least, in theory…

Caching Data

A big difference between Relay Classic & Modern is that Modern always fetches the query when a component mounts. That means the above strategy won’t work out of the box. To circumvent this, there is the suggested strategy… and then there’s my strategy.

The Facebook folks recommend that you apply a cache at the network layer. In other words, in your fetchQuery function, before you call fetch, you check your cache for the outgoing request. If it’s there, you return the cached result. If it’s not, fetch and cache the result so you’ll be ready next time. They even make it super easy by giving you a cache with a global time-to-live (TTL). If you want fine-grained TTL, you could trivially implement your own.

Unfortunately, both options are hogwash for one reason: If you query for those 100 todo items, and then your subscription sends in that 101st, your cached query is now invalid because it still has 100 items.

My solution is simple: don’t remove the data from the Relay store until you’re ready. This could be when you unsubscribe from the subscription that kept the query fresh, or it could be your own TTL.

By default, when QueryRenderer mounts, it asks the server for data. When that data arrives, it tells the store it cares about that data. When it unmounts, it tells the store it no longer cares. If nothing else cares about that data node, it gets garbage collected. To fix this, I wrote a custom QueryRenderer that tries to resolve the response from the store before going to the network. Then, if you specify a subscription or TTL, it keeps caring about that data until the sub ends or TTL expires. In other words…

Pro tip: This strategy doesn’t work if your mutation delivers a partial record. For example, if you query a connection where each edge has a cursor, and then your mutation doesn’t provide a cursor, it’ll always think the query is incomplete. Ask me how I know. To debug this, stick a break point on RelayAsyncLoader#_handleMissing to see what field is missing.

The Back End

Broadcast

Socket.io has a useful function called broadcast where it sends a message to everyone but the sender. How can we mimic that functionality so calling a mutation doesn’t result in a mutation response + an identical subscription payload? The solution is to place the socketId in the GraphQL context.

For example, at the end of your mutation, include the mutator’s socketId in the payload that goes to the pubsub. Then, in your GraphQL subscribe function, compare that mutatorId to the subscriber’s socketId. This works because the pubsub payload doesn’t have to follow your schema and when it gets returned from subscribe, GraphQL will filter out the extra field.

// addTodoMutation.js
getPubSub().publish(`todoAdded.${teamId}`, {newTodo, mutatorId})

// todoAddedSubscription.js
const filterFn = (value) => value.mutatorId !== socketId;
return makeSubscribeAsyncIter(channelName, filterFn);

Sidenote: if you’re wondering why my pubsub is in a thunk, see GraphQL: Tips after a year in production.

Authentication

Without locking down the subscription above, any attacker with knowledge of a team’s ID could listen for new todo items. That’s why the subscribe function, just like the resolve function for single payloads, is the best place for authentication. Before initializing the async iterator, while the request is still cheap, I shut down any funky requests. Then, for validation that depends on the incoming payload, I have the filterFn. Note that I don’t always have to return the pubsub payload. That payload could be the data necessary to trigger a user-specific query. That’s the power of evented subs!

Kicking folks off a subscription

Sometimes, you need to remotely kick someone off a subscription.

Thankfully, that’s as easy as calling asyncIterator.return(). For that to make sense, I recommend reading an article on Async Iterators & playing around with them until they stop feeling like magic. It’ll take a few hours. When you call return(), your awaited iterating loop will resolve and you can tell the client that the subscription has ended. This is where that onCompleted callback for Relay comes in. Now you can pop a grumpy modal when people use potty words.

Conclusion

And with that, we’ve covered all the pitfalls of getting Relay set up for efficient subscriptions. There are still plenty of interesting problems to tackle, like extracting GraphQL to a stateless microservice, avoiding waterfall query requests using React Router v4, and talking to multiple endpoints (like GitHub’s new GraphQL API). If that sounds like fun to you, you’re weird

…and I want to work with you. We’re hiring a Senior Full-stack dev & Summer Intern. You’ll be employee #5 at a company that’s in Alchemist, one of the top accelerators in the world. We’re backed by some of the best investors from across the country, including SV Angel and even Slack, so we gotta be good, right? If you’re happy just playing with this stuff in your free time, get a little side hustle going by checking out our open issues, submitting a PR, and grabbing a piece of the company with our Equity 4 Effort program.

Why unit testing a DB sucks

Let’s name all the ways that unit testing can be a real pain in the DB:

• All your tests share the same database (goodbye concurrent testing!)
• Compared to in-memory arrays, it’s dead slow
• 1 mutation can change many fields on many tables, meaning 50+ individual assertions is not uncommon
• Asserting UserX is on TeamY is hard when both have non-deterministic unique IDs
• Achieving the right pre-test state of the DB is a lengthy, painful, error-prone process that often takes longer than writing the business logic itself

Seems like quite a mountain to climb! Let’s dig in.

The Premise

There are enough 101’s in the world, let’s do something that actually occurs in the wild. Let’s say we’ve got a mutation that updates a customer’s credit card number. We receive a card token (because there’s no way I want the added burden of safely handling your actual credit card), send it to Stripe, get back the last 4 digits, and update it in our DB. Seems simple enough! Unfortunately, getting the database (and Stripe) to a state that can handle this scenario is painful. We have to create a User. We need that user to have an Organization with a valid credit card. That Organization needs to be a valid Stripe Customer and have a valid Stripe Subscription. Oh yeah, and we need this test to be lighting fast, because we’ve got a lot more.

Setting up the database

First, we’ll need a database just for testing. If you’re like me, you already have a series of database migrations set up so you can safely update and rollback your DB in production. If not, you probably have some kind of function that you can call to create a bunch of tables and indexes. Simply make sure the database used is a function of an environment variable (eg NODE_ENV="test") and run it.

Second, we’ll want to speed up the database by softening the write durability. While having a hard durability (making sure the doc was written to disk) is ideal for production, a soft durability (assuming the doc got written to disk) is much faster. Since this is only needed when you initially set up your test database, I run it directly after the migration. Combined, the migration and softening is like a webpack DLL: you only need to run it once when you install the repo or make a major change.

Finally, we’ll need to teardown the database and remove the records. Using an afterAll function in Jest won’t work because it’s run after all the tests in a file complete, so you might be wiping out rows of data that another test still needs. Instead, we want to trigger something after all the tests complete. It’s a little unintuitive, but you’ll need to write a script and reference it in your Jest config’s testResultsProcessor. In that teardown, I like to drain the DB connection pool so the process exits clean and every so often I empty out all the records — do this too much and it becomes added overhead, never do it and you’ve got a huge DB on your test machine, so I settle on about once every 100 runs.

Designing the test

A GraphQL mutation is the perfectly sized chunk for unit tests. Sure, you’ll still want to mock the occasional function in your mutations, but starting with the mutation as a whole is a great start. If you notice the test suite is getting too unruly, it’s a good cue to ask yourself if your mutation itself is too big.

If you’ve read my tips on using GraphQL in production, then you know about the Auth, Validation, Resolution pattern for GraphQL mutations. Similarly, I break each unit test into Setup, Test, and Verify stages (props to Jordan Husney for the idea).

The Setup stage

Setup is used to get the database to a useful pre-test state. In this example, it means creating a user and organization. Now, there are 2 ways for us to create a user and organization: we could use our pre-existing business logic (presumably createUser and createOrg mutations) or we could directly insert some rows into the database. The former is DRY, but since it depends on other mutations, it turns into a slow integration test rather than a fast unit test. So, I opt for the latter. To DRY it up, I use an app-specific MockDB I built which gives me a nice clean API:

const mockDB = new MockDB(); 
const {user, organization} = await mockDB
  .newUser()
  .newOrganization({creditCard})

The MockDB is nothing fancy: each method call pushes a new document with default values into an in-memory array. If I need to add more fields or override the default values (like I do with creditCard above) I just pass them in. Then, when you stick await in front of it, it magically batch-inserts the in-memory arrays to my database all at once, making for the quickest setup imaginable.

The Test stage

The Test stage is simply preparing the variables from the Setup stage, calling the GraphQL mutation, and awaiting the result to mutate your DB. In this case, await addBilling.resolve(...). It’s rare if this is more than couple lines.

The verify stage

This is where we rip the data from the database and run our assertions on it. That means we need to grab the Organization and make sure it looks exactly right. We could do this by cherry picking a couple fields like creditCard and updatedAt, but in reality we’re gonna update about 20 fields across 3 tables, which is enough cherry picking to make a pie.

Instead, let’s use Jest’s snapshot feature. It’s like a JSON deep equals, but it generates and maintains the expected value for you (why folks never explain it like this & opt for a cute polaroid analogy is beyond me).

So what do we want to snapshot? The Organization doc, any User in that organization, and eventually our Stripe account (yeah, I made a manual mock of Stripe, but let’s save that for another time):

const queriesToSnapshot = {
  organization: db.table('Organization').get(orgId),
  user: db.table('User').getAll(orgId, {index: 'orgId'})
}
const keys = Object.keys(queriesToSnapshot);
const values = Object.values(queriesToSnapshot);
const docs = await Promise.all(values);
const snapshot = docs.map((doc, idx) => {
  return dynamicSerializer.toStatic(doc, fieldsToSerialize[idx])
})

By creating an object full of promises like queriesToSnapshot, we can fetch all the documents concurrently. That means Setup, Test, and Verify each only call await once, keeping our tests screaming fast. Then, we string together all the results into one big JSON so we only run 1 snapshot per DB. But what exactly is that dynamicSerializer?

The Dynamic Serializer

Every time this test is run, it will generate new unique values for things like userId. This is necessary because our tests are going to run in parallel and we don’t want 2 primary keys to collide when the documents are inserted. However, random keys make snapshot testing impossible. Furthermore, it is not enough to just remove those fields. For example, my user document has an orgId foreign key that I want to match to its primary key on Organization.

We could solve this by mocking our random key generator in each test and very carefully stringing together a chain of mockReturnValueOnce, but then our tests get bloaty and brittle. Instead, I solved this the same way webpack did with numbered modules: create a cache of all unique keys, and then replace them with an incrementing integer. But there’s another constraint — what if I have more than 1 database in the same test? For example, if my stripeCustomerId serializes to 5 in my DB, I want it to serialize to 5 in my mock of Stripe. Thankfully, that’s all handled for me in a package called dynamic-serializer, which manages a dynamic value dictionary for the entire test. And just like that, I have deterministic unique IDs!

Conclusion

On my vintage 2013 Macbook Air, a single unit test involving 3 tables takes about 30ms — pretty darn reasonable. Each test is also about 20 LOCs, which makes it easy to grok when I inevitably break my tests and have to revisit my tests in the coming month. More importantly, by testing my actual queries against a real database output, I uncovered a handful of bugs and edge cases that would have otherwise gone unnoticed. If you want to see more, feel free to dig into the code. If you hate what you see, drop me a line in the comments below.

Unit test your DB with GraphQL and Jest was originally published in Parabol Focus on Medium, where people are continuing the conversation by highlighting and responding to this story.