Forem: Gabriel Nordeborn

Practical uses for abstract types in ReScript

Gabriel Nordeborn — Mon, 27 Feb 2023 17:55:15 +0000

Abstract types are types with no content. They look like this in ReScript:

type email

Just a type definition, but no content. The type is named email, so we can kind of guess it's a string, but there's no way to use it like a string, because it's opaque to the type system - we can't know what's inside.

Looks useless at a first glance? It has quite a large number of use cases. This post will cover a few of them where using abstract types can help you ensure better type safety throughout your application.

Let's dive into an example!

Tracking ID:s coming from an external API

Imagine we have an API from which we retrieve organizations and users. We also have an API for updating a user's email. The type definitions for users and organizations might look something like this:

type user = {
  id: string,
  name: string,
  email: string,
}

type organization = {
  id: string,
  name: string,
  users: array<user>,
}

We've also made up a few API:s that we'll use for illustrative purposes:

@val
external getCurrentOrganization: unit => promise<organization> =
  "getCurrentOrganization"

@val
external setUserEmail: (
  ~email: string,
  ~id: string,
) => promise<result<unit, string>> = "setUserEmail"

@val
external getMe: unit => user = "getMe"

The externals above binds to a few imaginary APIs: getCurrentOrganization for retrieving the current contextual organization, setUserEmail to set the email of a user via a user ID, and getMe to retrieve the current user (me).

Application code for updating the current users email might look something like this:

let me = getMe()
let currentOrganization = await getCurrentOrganization()
let {id, name} = currentOrganization

Console.log(`Trying to update email for "${me.name}", in context of organization "${name}".`)

switch await setUserEmail(~email="some.fine.email@somedomain.com", ~id=id) {
| Ok() => Console.log("Yay, email updated!")
| Error(message) => Console.error(message)
}

This example uses ReScript Core

Excellent, this works well! Or wait... actually, it doesn't. Can you spot the error?

We're accidentally passing the organization id to setUserEmail, not the user id (me.id). Shoot. At some point we destructured the id from currentOrganization, used it for something (probably logging), but then decided it wasn't necessary. But we forgot to remove it from the destructure, and now we're accidentally passing it to setUserEmail.

Solving this is obviously easy - just pass me.id instead. But what can we do to prevent this from happening again?

An id is a string, that's how it comes back from the external API. Well, while it's true that it's a string at runtime, we can tell the type system it's something else, and then have the compiler help us ensure the above cannot happen.

Here's how we can do that.

Leveraging abstract types to control how values are used through your application

Let's restructure our type definitions a bit:

type userId
type organizationId

module Id = {
  type t<'innerId>
}

type user = {
  id: Id.t<userId>,
  name: string,
  email: string,
}

type organization = {
  id: Id.t<organizationId>,
  name: string,
  users: array<user>,
}

We're adding two abstract types for the two types of ID:s we have, userId and organizationId.
We're adding a module called Id, with a single type t<'innerId>. This looks a bit weird, and we could've skipped this and just used userId and organizationId directly. But, this is important for convenience. You'll see why a bit later.
We change the id fields for user and organization to be Id.t<userId> and Id.t<organizationId> respectively.

These changes are all at the type level only. Nothing changes at runtime - every id will still be a string. We're just changing what the type system sees as we compile our application.

As we try to compile this, we immediately catch the error we previously made:

  39 ┆ switch await setUserEmail(~email="some.fine.email@somedomain.com", ~id=id) {

  This has type: Id.t<organizationId>
  Somewhere wanted: string

It's telling us that we're trying to pass an Id.t<organizationId> where a string is expected. That means two things to us:

We're catching the error we made previously - yay!
setUserEmail is still expecting a string for the user ID, but it should now expect our new Id.t<userId> instead.

Let's change the type definition for the email updating API to expect the correct ID type:

@val
external setUserEmail: (~email: string, ~id: Id.t<userId>) => promise<result<unit, string>> = "setUserEmail"

There! Let's try to compile again:

  39 ┆ switch await setUserEmail(~email="some.fine.email@somedomain.com", ~id=id) {

  This has type: Id.t<organizationId>
  Somewhere wanted: Id.t<userId>

  The incompatible parts:
    organizationId vs userId

Still doesn't compile obviously, but look at that error message. It's telling us exactly what's wrong - we're passing an organizationId where we're supposed to pass a userId!

Fixing this is now a piece of cake:

switch await setUserEmail(~email="some.fine.email@somedomain.com", ~id=me.id) {

...and it compiles!

Notice also that it's now impossible to pass anything else as id to setEmailUser than an Id.t<userId>. And the only way to get an Id.t<userId> is to call your external API retrieving a user. Pretty neat.

Hiding underlying values with abstract types

Let's pause here for a moment. Remember that all changes we've made have been at the type system level. Each id is still just a string at runtime. Doing Console.log(me.id) would log a string. There's no such thing as a Id.t when the code actually runs. We're just instructing the type system to track every type of ID and ensure it can't be used in any place we don't specifically allow.

Also note that it's impossible to create an Id.t yourself, even if you technically know that it's really a string:

let userId: Id.t<userId> = "mock-id"

This produces:

  12 │ let userId: Id.t<userId> = "mock-id"

  This has type: string
  Somewhere wanted: Id.t<userId>

So, again. Only way to get an Id.t<userId> is to fetch a user from your API.

With just a few lines of code we've implemented a mechanism that can ensure that ID:s can't be used in any way we don't control, and that they can't be constructed in the application itself.

Accessing the underlying `string` of the ID:s

Moving on with the example, one question remain: Why have a module Id, when we could just use the abstract types userId and organizationId directly? The error messages would be at least as good, and it'd achieve the same effect.

Let's extend our example with what to do when you do need to access the underlying value of something abstract, and why having a module like the Id module we have is important for ergonomics.

Imagine it suddenly got important for us to log the exact organization and user id values before we attempt updating the email. We want our logging code to look like this:

Console.log(
  `Trying to update email for user with id "${me.id}", in context of organization with id "${currentOrganization.id}".`,
)

But, this doesn't compile:

  37 ┆ Console.log(
  38 ┆   `Trying to update email for user with id "${me.id}", in context of or
     ┆ ganization with id "${currentOrganization.id}".`,
  39 ┆ )
  40 ┆ 

  This has type: Id.t<userId>
  Somewhere wanted: string

Ahh right. We're using the type system to hide the underlying type, but that goes two ways. That also means we can't use the ID by itself where we expect a string.

What if we could hide the fact that it's a string to all of the application, but also have a way of turning any tracked id into a string? That should be safe, because we know that any id comes from the API directly, and is guaranteed to be a string.

Turns out we can, and it's easy!

Let's restructure our Id module a bit again:

module Id: {
  type t<'innerId>
  let toString: t<_> => string
} = {
  type t<'innerId> = string
  let toString = t => t
}

Quite a few new things happening here. Let's break them down one by one:

We've added an inline module signature, by writing module Id: { ... } = { ... }. The signature says what we want the outside to see when they look at this module. After it follows the actual implementation.
The signature has t as an abstract type, but the implementation aliases t to string. Uh-oh, aren't we leaking the underlying string now? We're not, because in the signature t is still abstract, and that's what the outside sees.
We've added a toString function that takes an Id.t and returns a string, which is exactly what we needed. Two things to notice about this. First, the signature says it takes Id.t<_> and produces a string. _ in this case means "I don't care about the inner type" - toString can be used on any Id.t, it doesn't matter what inner type we've said it is, it's still a string under the hood. Second, notice the difference between signature and implementation. The implementation just returns the id it was fed, since it knows it's really a string.

The gist of the above is this:

The outside world doesn't know what an Id.t is (it's abstract), but it does know it can run toString on it to get a string, because the signature says so.
The module itself knows that an Id.t is really a string, and therefore that it's fine to just return itself when converting an Id.t to a string.

Now, with the toString function, we can convert the ID:s in the log to strings:

Console.log(
  `Trying to update email for user with id "${me.id->Id.toString}", in context of organization with id "${currentOrganization.id->Id.toString}".`,
)

There, it compiles! Note that this is only for going the safe way of turning an Id.t into a string. There's still no way to create a potentially unsafe Id.t yourself in your application.

And that's it. We're now fully controlling how the ID:s are used throughout our application. Pretty neat.

Wrapping up

I'm a big believer in the importance of ergonomics - if it's too much hassle to use, people just won't use it. That's why this being easy and straight forward in ReScript is important. This is functionality I use often, and very much so because it's easy to use. Just define an abstract type, put it where you need it, and have the compiler rule out entire classes of potentially erroneous behavior.

This post describes a scenario where I personally find reaching for abstract types very powerful. What use cases do you have where you use abstract types? Write in the comments!

Thank you for reading.

ReScript, React and spread props - it's now possible!

Gabriel Nordeborn — Sun, 19 Feb 2023 10:21:03 +0000

ReScript 10.1 was recently released, bringing a new version of the built in JSX transform in ReScript.

The new JSX transform brings a bunch of new capabilities, and one of those are that you can now do "props spreading".

This post will quickly outline how you can use the new JSX version to bind to APIs that utilize props spreading. We'll assume you know what props spreading is, but if you don't, quickly read through the official React documentation.

More information about the new release, and JSX in ReScript:

The section in JSX v4 in the official blog post.

The official documentation on JSX in ReScript.

Example of using props spreading in bindings - binding `useFocus` from `react-aria`

We'll show how to utilize props spreading in ReScript and React by creating bindings to an actual API that uses props spreading, and porting the official JavaScript example code to ReScript from the documentation for that API.

We're going to bind to useFocus from react-aria.

You're encouraged to skim the useFocus documentation page before continuing.

Setting up the bindings

First, let's set up our bindings for useFocus from react-aria.

Reading the documentation, we see both what the function returns, and the config it takes: https://react-spectrum.adobe.com/react-aria/useFocus.html#usage

Writing the return and input types in ReScript from that documentation page looks like this:

type useFocusConfig = {
  onFocus?: JsxEvent.Focus.t => unit,
  onBlur?: JsxEvent.Focus.t => unit,
  onFocusChange?: bool => unit,
}

type useFocusReturn = {focusProps: JsxDOM.domProps}

Notice 2 things here:

JsxEvent.Focus.t is the equivalent of FocusEvent in TypeScript.
The return type holds one field only, focusProps. That's typed as a JsxDOM.domProps because it's a bag of props that you should apply on the JSX DOM element where you want the focus handlers from useFocus. This is important and is what enables the props spread. More about this further down.

Let's tie together the types with a binding to the hook:

@module("react-aria") external useFocus: useFocusConfig => useFocusReturn = "useFocus"

The finished binding looks like this:

// We're saving this in the file ReactAria.res
type useFocusConfig = {
  onFocus?: JsxEvent.Focus.t => unit,
  onBlur?: JsxEvent.Focus.t => unit,
  onFocusChange?: bool => unit,
}

type useFocusReturn = {focusProps: JsxDOM.domProps}

@module("react-aria") external useFocus: useFocusConfig => useFocusReturn = "useFocus"

Porting the example JavaScript code to ReScript

There! We have the types and the binding to the hook. Let's see if we can implement the same example that the react-aria documentation has. Here's the example, in regular JavaScript, as it's shown in the documentation:

import {useFocus} from 'react-aria';

function Example() {
  let [events, setEvents] = React.useState([]);
  let { focusProps } = useFocus({
    onFocus: (e) =>
      setEvents(
        (events) => [...events, 'focus']
      ),
    onBlur: (e) =>
      setEvents(
        (events) => [...events, 'blur']
      ),
    onFocusChange: (isFocused) =>
      setEvents(
        (events) => [
          ...events,
          `focus change: ${isFocused}`
        ]
      )
  });

  return (
    <>
      <label htmlFor="example">Example</label>
      <input
        {...focusProps}
        id="example"
      />
      <ul
        style={{
          maxHeight: '200px',
          overflow: 'auto'
        }}
      >
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}

Let's implement it in ReScript using our new binding:

module Example = {
  @react.component
  let make = () => {
    let (events, setEvents) = React.useState(() => [])
    // We put the `useFocus` binding code in a `ReactAria.res` file.
    let {focusProps} = ReactAria.useFocus({
      onFocus: _ => setEvents(events => events->Array.copy->Array.concat(["focus"])),
      onBlur: _ => setEvents(events => events->Array.copy->Array.concat(["blur"])),
      onFocusChange: isFocused =>
        setEvents(events =>
          events->Array.copy->Array.concat([`focus change: ${isFocused ? "true" : "false"}`])
        ),
    })

    <>
      <label htmlFor="example"> {"Example"->React.string} </label>
      <input {...focusProps} id="example" />
      <ul style={ReactDOM.Style.make(~maxHeight="200px", ~overflow="auto", ())}>
        {events
        ->Array.mapWithIndex((e, i) => <li key={i->Int.toString}> {e->React.string} </li>)
        ->React.array}
      </ul>
    </>
  }
}

A few things to notice about the ReScript code above:

We moved the binding code to a separate file ReactAria.res, and access our binding via ReactAria.useFocus. This is common practice, grouping your bindings in a separate file when it makes sense.
It uses ReScript Core for the Array functions.
Also notice that there's not a single type annotation in here, but the code is 100% sound/type safe thanks to ReScript's great inference.

As you can see, just like in the JavaScript code, we spread {...focusProps} on the <input />. This works because focusProps has the type JsxDOM.domProps, and that's the same type that <input /> expects its props to have.

This is key to why this works - it's essentially the equivalent of spreading props on a record:

let inputProps: JsxDOM.domProps = {...focusProps, id: "example"}

Wrapping up

Summing up this quick post - whenever you're binding to something that wants you to use spread props on JSX DOM elements, type that as JsxDom.domProps so it matches what JSX DOM elements expect for props.

That's it! Here's a few additional links if you're interested in diving deeper:

Getting rid of your dead code in ReScript

Gabriel Nordeborn — Mon, 24 Oct 2022 16:14:11 +0000

Exploring ReScript's tools for eliminating dead code, keeping your repository clean and without unnecessary distractions.

Dead code is code that's left in your repository but never actually used in your application.

Other than occupying unnecessary space and adding to compilation times, dead code can also be distracting and confusing when you look at it thinking it's used in the application. Like when bending the new thing you're building to work with an existing abstraction that's not in use, and should be deleted instead. Or refactoring a component to work with something new you're working on, but the component itself is unused in the application and should be removed.

ReScript has some quite advanced and convenient tools for dealing with dead code. In this article we're going to explore how you can get started using them to keep your repository clean and free of the potential distractions of left behind dead code.

We'll explore dead code analysis in ReScript by running the analysis on a real, fairly large production code base that's in active development. This will uncover concrete and interesting real life examples of how the analysis can help remove dead code and reduce the complexity of the code base.

Let's get started!

Dead Code Analysis

Dead code analysis is about tracking types and values throughout your program at compile time, figuring out how (and if) they're actually used. Depending on your language and type system, this can be quite tricky, and in many cases impossible to get 100% right.

Whether some piece of code is dead or not can be subtle. Simple cases are easy - a function that is never called, or a value that is never used. The more complicated cases however are much harder. What about record fields that are never read? Or variant cases that are handled in your code, but never actually constructed at runtime?

In ReScript, we're lucky. A bunch of language design decisions and language features come together in a way that makes dead code analysis both effective and accurate.

Baked into the ReScript VSCode extension is the ReScript Code Analyzer. This code analyzer (also called reanalyze) is an advanced statical analysis tool for ReScript built by core team member Cristiano Calcagno. Cristiano has an extensive background in statical analysis, both in academia and in practice.

The code analyzer works by continuously analyzing your entire code base. Any issue found is reported right in the editor's "Problems" pane. It's easy to start, easy to stop, and is really fast given the amount of work it's doing.

Getting started

Enough background, let's get started! You'll need version >=1.8.2 of the VSCode extension.

You activate the analysis in the ReScript VSCode extension by running the command > ReScript: Start Code Analyzer (Cmd/Ctrl + P brings up the command palette).

Stopping the analysis is a matter of either running the command > ReScript: Stop Code Analyzer, or clicking the "Stop Code Analyzer" button in the status bar that's visible when the code analyzer is active.

Once you've started the code analysis, you should see the "Problems" pane being populated with various warnings and errors related to dead code.

It's possible to do fine grained configuration of the analysis if you'd like. You can configure things like suppressing reporting for entire sub folders, and so on. Quite useful, and we'll cover configuration of the analysis at the end of this article.

Examples from real life

Let's look at some concrete cases of dead code that the analysis is finding in the real production code base we're looking in, and how fixing them helps us clean up the code.

Record fields that are never used

Since records are nominal, each defined field will always be available. But what about fields that are never actually read? Let's look at an example.

There's a CheckBoxList.res file. This file has a React hook that returns a record with a bunch of helpers for dealing with the state for a list of check boxes. The return type looks like this:

type useReturn = {
  items: array<item>,
  toggleItemChecked: string => unit,
  setCheckedOnItem: (string, bool) => unit,
  checkAll: unit => unit,
  uncheckAll: unit => unit,
}

Running the analysis tells us: useReturn.toggleItemChecked is a record label never used to read a value

So, toggleItemChecked is never actually used by any of the code using the hook. We can safely remove that. And removing that allows us to remove the underlying code for the function, getting rid of a little bit of complexity in that hook. Nice.

Variant cases that are never used

What about variant cases that are defined, accounted for the in the code, but never actually used in the application? Let's look at a concrete example.

There's a React component called <Menu />. It renders a pop-over menu. The menu takes an array of item, and the type definition of these items look like this:

type textType =
  Text(string) | TextWithIcon({icon: React.element, text: string}) | Render(React.element)

type href =
  | Href(string)
  | Render(HeadlessUi.Menu.itemChildrenRenderProps => React.element)
  | Callback(unit => unit)

type item = {
  disabled: bool,
  text: textType,
  href: href,
}

Essentially, we have an item that can have text to render the text for the menu item, and a href to deal with rendering the link for the menu item.

As we run the analysis, two things are reported:

textType.Render is a variant case which is never constructed
href.Render is a variant case which is never constructed

Interesting! It appears that Render, which is an escape hatch in this component for essentially "rendering what you want" for text and linking, is never actually used in the code base. That means there's no place in the entire app that's configuring a menu item to use Render for text, or for href.

So, I can remove those two variant cases. However, removing them per se isn't the nice thing - it's that I can now remove the code in the component that handles Render. And in this specific case, removing the code handling Render meant being able to reduce the complexity of the component quite a lot.

Notice the level of granularity in the analysis that the code analyzer is capable of doing. It's finding a variant case, and making a distinction between that variant case being consumed (which it is inside of the component, since we account for it as we're rendering) and it being constructed, meaning someone actually using that specific variant case somewhere in the code when defining menu items. Quite powerful.

Unused parts of React state

This one was quite interesting. The app has a form for changing password for the user, ChangePasswordForm.res. That form has its state defined like this:

type validationState = Idle | Invalid | Valid

type state = {
  oldPassword: string,
  newPassword: string,
  newPasswordRepeated: string,
  validationState: validationState,
}

It then uses a reducer to manipulate that state. Notice validationState here. This was all hooked up nicely in the form - validation states were produced as the form was changed, and so on. However, dead code analysis tells us a different story - validationState is a record label never used to read a value.

Hmmm... It turns out that while the component does produce the right validation states for the various scenarios, it's never using the validation state anywhere. It's just setting it.

Apparently producing the validation state was part of how the form used to work. But, it was refactored at some point to not use that validation state, and rather just look at if things were valid via another mechanism on submit. Someone just forgot to remove it from the state and the surrounding logic for producing it.

This, while rather small, is a prime example of distractions and the potentially dangerous confusion that can come from dead code. You won't catch that the validation state isn't used by just looking at this component quickly. And if you don't catch that, refactoring or building out this component means you're likely to take the validation state and its logic into account.

And that might cause you to build a more complicated solution for the thing you're doing, slow you down, and so on. Dangerous.

Unnecessarily exposed functions in an interface file

DrilldownTarget.resi has two reports:

MetricParam.parse is never used
MetricParam.serialize is never used

These both indicate that for the interface file, parse and serialize from the MetricParam sub module is exposed to the outside world, but nobody is actually using them. So, it's safe to remove them from the interface.

A small thing, but helpful to avoid unnecessarily exposing them.

But what if you do want to expose them even if nobody is currently using them? We'll cover how to tell the code analyzer about that later on.

Regular dead code

It's also finding quite a few functions that are just never called.

RouterUtils.res has a bunch of helpers around constructing and handling URL:s. The analysis is telling us the following:

routerUrlToPath is never used
routeUrlStartsWith is never used

Removing them uncovers a number of other helpers in that file that are no longer needed. The end result is a much thinner RouterUtils.res.

Unused React components

It's finding a number of unused React components. Some of them I want to keep because I know they'll be used in the future (more on how to tell the code analyzer below). But, many of them can be removed. They're old and outdated. It's just that nobody had removed them.

Living with the dead

Sometimes removing the dead code isn't what you want. It might be code that happens to be dead at this moment, but that you know will be used later. Or code that while not used right now still serves a purpose in terms of being illustrative of a particular use case. And so on.

The code analyzer understands 2 annotations for suppressing dead code reporting at a more granular level. These are @live and @dead.

We're going to talk a bit about the difference between @live and @dead soon. There's some subtle nuance between them. But, first let's look at a number of examples of how you can add these annotations.

// `Small` is never constructed in the code base as of now, but I know it will be later, so I can annotate just that variant case
type size = XSmall | @dead Small | Medium | Large

// `age` is never read in the code base right now, but I know it will be eventually, so I don't care that it's considered dead as of now
type user = {
  name: string,
  @dead age: int,
}

// This entire type isn't used right now, but I need to keep it around regardless
@live
type pet = {
  isCat: bool,
  owner: user
}

// This function also isn't used right now, but I want to keep it around regardless of that
@live
let getUserName = user => user.name

Notice how you can add these annotations at a granular level.

So, with that out of the way - what's the difference between @live and @dead?

@dead - when something is dead, but you intend to fix it

Adding @dead to something will suppress dead code reports for that piece of code. If that code comes alive (as in it's used again), the code analyzer will tell you that the piece of code you've marked as dead is actually alive now.

This is useful because it'll allow you to remove dead code suppressions when they're no longer useful.
over.

@live - when something is potentially dead but you want to keep it around regardless

The @live annotation will also suppress dead code reports, but it won't tell you if the thing you're suppressing becomes alive again. Additionally, it'll also keep anything using it alive. It'll essentially force the dead code analysis to behave as if the code is alive for real.

Configuration of the analysis

You can configure the analysis in bsconfig.json. Let's examplify by looking at the configuration for the project we just ran the analysis for. Here are the relevant parts of bsconfig.json:

{
  "reanalyze": {
    "analysis": ["dce"],
    "suppress": ["src/bindings", "src/stories", "src/routes"],
    "unsuppress": [],
    "transitive": false
  }
}

Let's go through what we're configuring.

`analysis`

This tells the code analyzer what analysis you want to run. dce means Dead Code Elimination, and is what we'll be focusing on in this article. There are more analysis you can activate (most notably exception). We're going to cover them in later articles.

`suppress`

This lets you suppress dead code reports for entire subfolders and specific files in your project. Note that it's just suppressing the reports, the analysis still takes place. So a suppressed folder might be keeping code alive in a folder where you do want reports.

Useful for ignoring dead code in places where you don't care, or in places where you can't fix the dead code anyway (generated code being a classic example).

We're ignoring our bindings folder with hand rolled bindings. We're also ignoring both stories and routes because those contain things that are either a) mostly generated, or b) irrelevant that they're dead. For example, Storybook stories are considered dead because they're never actually used in the main app. But we don't mind that.

`unsuppress`

There's nothing configured here right now, but this entry allows you to unsuppress reporting for specific files in the suppressed folders. Handy for certain cases.

`transitive`

This one is important, because it controls whether code that's transitively dead is reported or not. "Transitively dead" is a mouthful. It essentially means code that's dead because all of the code that's using it is dead.

Setting this to true means you'll immediately see all the dead code in your repository. That's useful for certain scenarios, like overviewing how much dead code you have in total. However, it's not very user friendly, because you won't know the full story of why the code is dead. So, it's not technically dead by itself because other code is still referencing it, but it's considered dead because the code referencing it is dead itself.

The default is false. That's most useful for when you're going to be working with removing your dead code. Doing that means that you'll only get reports of dead code for things that is dead by itself, and not because everything using it is dead.

That is useful because you'll be able to remove the dead code that's reported, and your program will still compile after. You'll be able to remove "layers" of dead code at a time.

This is important for a number of practical reasons:

It makes it easy to trust the tool - your program will still compile after removing the code the tool is saying is dead
It makes it easy to remove dead code incrementally. This is very important, because this means you can clean up your repository little by little, over time. Much easier than being faced with all the dead code at once, with no clear indication of what to remove first
It helps you not get overwhelmed. Even if you have thousands of cases of dead code, a large majority of them are probably going to be dead only because the code using them is also dead, and you couldn't remove them in isolation anyway. This approach makes sure you don't even need to think about those cases until they're relevant.

Closing thoughts

This type of functionality is in my opinion one of the unique selling points of a language like ReScript. Fine grained, accurate and efficient dead code analysis. It's possible because of the design and simplicity of the language. And because of the type system.

A great example of using the language's strengths to build something pragmatic and useful in the real world. You need help from the computer to do these types of things. Over time it's impossible to not accidentally miss removing code that's no longer in use. Especially in the more complicated cases, like we saw in the example of the form with with the unused validation state.

Tools for dealing with these things need to be pragmatic. What are we trying to get done? Dead code can exist for various reasons, and like we've seen it's not always the right decision to remove it. That's why our focus is on building tools that help you improve your code base and situation one small step at a time.

There, you know all about dead code analysis in ReScript now! Go try it in your own code bases and see what comes out.

Thank you for reading!

A special shout out to Elm review which has inspired how reanalyze reports code that's transitively dead.

Speeding up ReScript compilation using interface files

Gabriel Nordeborn — Thu, 20 Oct 2022 16:18:52 +0000

ReScript compilation speeds are really fast out of the box. But, sometimes editing certain files can take longer to compile than you'd expect it to.

In this article we'll explore a strategy for speeding up compilation by leveraging interface files. We'll also dive into why using interface files can speed up compilation. And, by doing that we'll dig a bit into how the ReScript compiler works internally.

Let's start from the beginning though, with a few concepts that are necessary to understand to be able to follow the rest of the article. You can skip the coming sections if you're already familiar with modules, interfaces and implementation files in ReScript.

TLDR; If you have files that, when edited, cause longer compile times than you'd expect, see if adding interface files for those files help. If you're changing the implementation often, but not the interface, you might see massive speed increases from adding interface files.

Modules and files

Read the official docs on modules: Modules in ReScript

Quoting the official docs, "modules are like mini files!". A module is a collection of types, values, functions, and so on.

For this article's sake, pay special attention to the fact that every file is automatically a module. So, if you have MyFile.res, that file's contents will be available for you to use under the MyFile module globally.

We'll use the words module and file interchangeably, so please keep in mind that every file is a module.

Implementation and interface files

Read the official docs: Interface and implementation files in ReScript

ReScript lets you separate interface and implementation in various ways.

Interface here means a description of what the outside world has access to in your module. This is typically called the signature of the code. It's essentially type information.

Implementation means the code you write to fulfill that description.

A simple example: in your interface, you tell the world there's going to be a value called usernames available that's an array of strings. And in the implementation, you produce that actual array of strings called usernames.

// AllUsers.resi
let usernames: array<string>

// AllUsers.res
let usernames = allUsersInSystem->Belt.Array.map(user => user.name)

Now, the outside world doesn't need to care about how the usernames array is produced. That's the implementation. It just needs to know that that array will be there.

In ReScript, implementation files are suffixed with .res, and interface files are suffixed with .resi. So, if you have AllUsers.res, you add an interface by adding a AllUsers.resi file.

So, how can interface files speed up compilation?

Why does all of this matter to compilation speed? Let's dive into how the ReScript compiler works a bit.

When you make a change to your code and then recompile, the ReScript compiler needs to type check all affected parts of your program to make sure everything still adds up. The ReScript compiler is quite intelligent and mostly knows how to check the minimum set of files needed as you change things. This is a huge part of what makes the compiler so fast.

Type checking is, very simplified, about ensuring that all the types match each other in the project. Is the parts of your program expecting (and receiving) the right things?

The compiler looks at each file (module), and then does one of two things depending on whether that file has an interface file or not.

If it has an interface file, the compiler checks the implementation file to make sure that the implementation matches the interface. Are you delivering what you promised in the interface? If all checks out, it moves on. If not, it errors.
If it doesn't have an interface file, the compiler needs to derive an interface by itself for the file by looking at the implementation file directly. So it looks at the code you've written, infers the signature of that code ("let myArray = ["some string"] is an array of strings"), and then uses that inferred signature as an interface for that file as it moves on.

And this is because the type checker works on the type information from the interface, not on the actual code implementing that interface.

Compilation slows down because the compiler needs to derive the interface again and again

This is what it all comes down to. If there's no interface file, the compiler needs to derive that interface itself by looking at the implementation.

And it needs to do that every time the file changes.

And after it has done that, it needs to recheck all of the modules depending on the file you changed to make sure things still type check.

But, if there is an interface file, all the compiler needs to check is that your implementation still matches the interface. It doesn't need to check anything else. It can safely assume that any other file that's depending on this file and has compiled successfully with the current interface is still valid. Because the interface hasn't changed, just the implementation for that interface.

A good strategy for interface files

How much you make use of interface files or not is largely a philosophical question that I'm going to refrain from discussing here. Some people never use them. Some people use them a lot. I personally use them some, but not a lot.

One strategy I will leave you with though is to be mindful of modules you have that are used by many other modules. Those might be a good idea to use interface files for, not the least because of the speed benefits discussed in this article.

So, be mindful of when editing certain files cause longer compilation times than you'd expect. See if adding an interface file might help.

Editor tooling helps make life with interface files easier

The ReScript VSCode extension has two goodies that help make life with interface files easier that I want to mention.

Automatically generating an interface file from an implementation file

If you have a .res file that you want to create an interface file for, you can use the command > ReScript: Create an interface file for this implementation file (Cmd/Ctrl + P brings up the command prompt). You'll get a fully filled out .resi file right next to your .res file that you can edit to your liking.

Quite convenient.

Switching between interface and implementation files

The extension makes it easy to jump between the .res and .resi file for a module via the command > ReScript: Switch implementation/interface. Running that command will jump to the .resi file if you're in a .res file (and the .resi file exists of course), and running it from a .resi file will jump to the corresponding .res file.

Wrapping up

There's a ton more to say when it comes to what you can use interface files for, both in terms of features, but also in terms of techniques for a good developer workflow. This article focuses on the performance aspects of interface files, but I'm likely going to cover the other points too at some point.

Until then, thank you for reading!

Announcing Relay Meetup, a global, remote meetup for Relay, the GraphQL client

Gabriel Nordeborn — Mon, 05 Oct 2020 18:10:54 +0000

I'm very excited to announce RelayMeetup.com - a remote meetup dedicated to Relay, the GraphQL client.

Every month we'll host an online meetup full of interesting and hands-on content on Relay. Each meetup will feature one or more talks, and a theme.

The talks can be about anything as long as it has some connection to Relay. Presentations, interviews, live demo/coding sessions - anything goes!
The themes will cover aspects of using Relay hands-on. We'll focus on practical knowledge and real life examples - bringing as actionable content as we can.

We want to create a friendly, laid back and natural space where anyone curious about Relay can feel at home. We'll stream live on YouTube, and everyone is welcome to either join live or watch the recorded event afterwards.

The time for Relay is now

People who spend enough time to learn Relay in depth tend to fall in love with it. There's truly no alternative in the GraphQL client space that offers what Relay offers. And, with the upcoming hook APIs, fully leveraging suspense and concurrent mode, Relay is as relevant as ever.

The Relay community is vibrant and full of activity. But it's still small. Adoption isn't where at least I believe it deserves to be. That's because of a number of reasons. Let's sum it up by saying that Relay isn't as accessible to get started with as the alternatives, and not as easy to find good learning material on. This meetup is a first step towards helping tackling that.

Helping to grow the community

I've been involved with the Relay community for a long time now. In addition to using Relay both professionally and personally since it was released, I've built a bunch of projects and experiments related to Relay, written a number of articles on Relay and contributed some to Relay itself.

I'm also a partner at the Swedish consultancy Arizon. We love Relay at Arizon, and we'd like to give back to the community somehow. This meetup is one way of doing that. Relay solves the problems we've been facing in UI development in a way that makes sense, is scalable, and intuitive. We'd love for more people to find their way to Relay, and experience what we've experienced.

21st of October - our first meetup

Our first meetup will be held at the 21st of October at 19:00 GMT+2 (check your timezone here), streamed on YouTube (subscribe to the channel here), and available for anyone to watch both live and afterwards.

Here's what we'll cover in this first meetup.

Using Relay in production

The first meetup will feature Eloy Durán, former Director of Engineering at Artsy. Artsy has been using Relay for a long time, and we'll talk about Eloy's and Artsy's experience of using Relay in production over the years.

Updating the cache after mutations

Our theme for the evening is updating the cache after mutations. We'll dive into strategies for updating the cache after mutations in simple as well as more complex scenarios.

This segment will feature Jan Kassens from the Relay core team at Facebook, as well as Eloy again. Together we'll discuss various approaches for updating the cache, as well as how both Facebook and Artsy, two very different applications with different needs, approach these problems.

Check out the event on our website here, the scheduled YouTube stream here, and the Meetup.com event here.

Get involved!

Again, I'm very excited to finally be able to do something like this in the Relay community. Relay is a passion of mine, and I fully believe that the value of Relay now, with suspense and concurrent mode incoming, is greater than ever. There hasn't been a better and more exciting time to get into Relay.

Please don't hesitate to reach out if you're interested in getting involved. Here's a few things we'd love to see:

There's a lot of businesses and people using Relay outside of Facebook, and we'd like to involve the industry as much as possible. Is your company using Relay? Come on the meetup and talk about your experience!
Have something interesting around Relay to present? Or have a cool demo of something related to Relay you'd like to show? Have a vague feeling that you have something interesting to show or tell, but don't know just how yet? Reach out to us and we'll figure it out together!

Finally, if you want to stay current with what we're up to, don't forget to follow us on Twitter and join our Meetup.com group if you're on there.

Looking forward to seeing you the 21st of October for a fun evening full of interesting content on Relay!

The magic of the Node interface

Gabriel Nordeborn — Thu, 16 Apr 2020 20:46:17 +0000

This series of articles is written by Gabriel Nordeborn and Sean Grove. Gabriel is a frontend developer and partner at the Swedish IT consultancy Arizon, and has been a Relay user for a long time. Sean is a co-founder of OneGraph.com, unifying 3rd-party APIs with GraphQL.

The official GraphQL website recently added a section called “Global Object Identification” to its collection of best practices. In this article, we’ll dive into what global object identification is, why it’s useful and what type of developer experience it enables.

What is Global Object Identification?

Global Object Identification in GraphQL is about two things:

Having each individual object in the graph be identifiable by a globally unique ID, across types. So no two objects can have the same ID, even if they're of different types.
Being able to query any single object that has an id only by that id. This is done via the Node interface which we’ll talk more in depth about below.

This enables libraries to safely automated away several things that are otherwise left up to the developer to implement and manage themselves:

A GraphQL framework can automatically update the cache of any object since all objects have a unique ID.
If we ever need to fetch new or refreshed fields on an object, all we need to know is its GraphQL type and its id.

We’ll go deeper into why these two points enable a great developer experience below.

What’s the `Node` interface anyway?

In schemas implementing the Node interface, you’ll see a top level field on the Query object called node, and it takes a single argument: id, and it returns a single field: id .

Wat?

When you first look at it, it’s indeed a bit strange!

    query NodeInterfaceExample1 {
      gitHub {
        node(id: "MDQ6VXNlcjM1Mjk2") {
          id # As one might expect, this is indeed "MDQ6VXNlcjM1Mjk2"
        }
      }
    }

But because node is an interface, it implements every GraphQL object in the schema that can be fetched via its id:

    query NodeInterfaceExample2 {
      gitHub {
        node(id: "MDQ6VXNlcjM1Mjk2") {
          id
          ... on GitHubUser {
            login # "sgrove"
            followers {
              totalCount # it's over 9000!!!!
            }
          }
        }
      }
    }

But why is it useful?

That means that if we know the id and the GraphQL Type of a thing, then we always know how to look it up. The alternative might be something like:

     query WithoutInterfaceExample {
      gitHub {
        user(login: "sgrove") {
          login
          followers {
            totalCount
          }
        }
      }
    }

There are two challenges with this query that will mean lots of extra work for us as developers, but that means extra chances for us to get things wrong:

Finding a GitHubUser this way doesn’t accept its id, it only accepts a login argument. That means if we ever had, say, an ownerId value, we still need to know the *login* value. This gets trickier and trickier because every kind of object might be looked up by different keys.
Even if we had the login value, we have to build a potentially complicated query with nested selections (gitHub.user in this case) to get the extra fields we want.

Ultimately, both those bits of knowledge are implicit - we know them as developers, we have that knowledge in our head - and that means the computer and our tooling doesn’t know it.

But if our tooling does know how to look up any object given its id, then it can help us in wonderful ways.

This will also relieve some pressure on the backend. Whenever you need to refetch a node that’s deeply nested in a query, the backend will need to resolve all levels above the node in order to get to it. If it’s able to just take the id and resolve a single node directly though, that added pressure goes away.

Why globally unique ids? Aren’t integers good enough?

So with the node interface we can look up any object by its id - great! But that comes with an implication: No two objects in our entire API can have the same id!

Quick aside: This seems daunting for just a moment at first, but there's an easy way to do this for any schema that we’ll see in just a moment

That means that every GraphQL object that has an id field (say, User.id or Post.id) must have a unique ID that no other GraphQL Object has. Take this query for example:

    query FirstUserAndFirstPost {
      user {
        id
      }
      post {
        id
      }
    }

It’s common for lots of databases to use incrementing integers as ids, so you might expect a response like:

    {
      "data": {
        "user": {
          "id": 1
        }
        "post": {
          "id": 1
        }
      }
    }

But combined with the node interface, this just won’t work. Say we have a post id and we want to get some additional fields (like its title). We should be able to run this query:

    query NodeInterfaceExample3 {
      node(id: 1) {
        id
        ... on Post {
          title
        }
      }
    }

But there are two objects that could be looked up with the id of 1! It’s now unclear if the object that will come back will be a User or a Post.

Don’t lose heart! A simple solution is at hand!

So if we want to internally keep using integers for our ID, how can we have globally unique IDs? Let’s look at the example ID used in the GitHub (whose API is beautiful and Relay compatible as well!) query: node(id: "MDQ6VXNlcjM1Mjk2")

    > atob("MDQ6VXNlcjM1Mjk2")
    "04:User35296"

Hey, I see some integers in there!

Basically, the technique is to construct a nodeId, and it looks like:

    `base64Encode(${apiVersion}:${GraphQLObjectTypeName}${ObjectId})

So for our post and our user on version 1 of our API, we would expect to see:

    "MDE6UG9zdDE=" # decodes to "01:Post1"
    "MDE6VXNlcjE=" # decodes to "01:User1"

If we revisit our previous node example that had a conflict and use our new ID:

    query NodeInterfaceExample4 {
      node(id: "MDE6UG9zdDE=") {
        id
        ... on Post {
          title
        }
      }
    }

Now our single node resolver can base64-decode the id, find that it’s looking for a Post object with id of 1, and return the correct object.

The reason we prefix the API version in the global id is to give us a chance to later change how we encode global ids in a non-breaking way, in case we need it. It’s a bit of flexibility we can buy for effectively nothing.

If things aren't quite clicking for you yet (especially if you don't get why an id would be anything but the database id of that object), it might help to think of the id field on a GraphQL type this way - you’re actually looking at a node in GraphQL, an entire graph, and not in your database table. This means that when you’re looking at the id of a GraphQL type, you’re looking at a node in a graph, not a table in a database. In this light, having the id of a GraphQL type be globally unique makes much more sense, since its primary objective is to be an identifier in your graph of objects, not in your database.

What does this enable?

Like demonstrated above, most schemas will already have some way of resolving a single item of most things, even if it’s not via a top level node field. So why does this whole thing matter? Is it just for making the resolution slightly more convenient?

Well, that helps too of course. But the real power comes from standardization.

If you think about it, even if your schema has a top level field called postById(id: ID!), that indeed does resolve a post by an ID, there’s really no way for anyone but the schema creator to know that’s in fact what the field does. Without parsing the semantical meaning of postById and inferring that it in fact does mean “a single post, just by its ID”, any external tooling or framework will not be able to safely assume that that’s what that particular field does. You may have any number of fields resolving a single Post, like postByDatabaseId(id: ID!): Post, mostLikedPost(id: ID!): Post, latestPost(id: ID!): Post and so on. This makes it impossible for external tooling to safely assume which field it can use to refetch a single Post.

The Node interface, however, is an official GraphQL best practice, and this means that frameworks and tooling can build on top of it and anyone who implements it will benefit. And there’s some pretty cool things you can build with it. Let’s look at some concrete examples from Relay:

Autogeneration of pagination queries

The latest iteration of Relay (now called only Relay, but commonly referred to as Relay Modern) can automatically generate queries for refetching or paginating data, since it can refetch any GraphQL object via the Node interface. This is enables a very ergonomic developer experience. Basically, Relay can take something like this:

    fragment UserFriendsList_user on User {
      id
      friends(first: $first, after: $after) {
        edges {
          node {
            firstName
            lastName
          }
        }
      }
    }

And automatically generate a pagination query for that, like this:

    query UserFriendsListPaginationQuery($id: ID!, $first: Int!, $after: String) {
      node(id: $id) {
        ... on User {
          id
          friends(first: $first, after: $after) {
            edges {
              node {
                firstName
                lastName
              }
            }
          }
        }
      }
    }

…just because it knows that User, the type the fragment UserFriendsList_user is on and where the pagination is defined, implements the node interface, and can therefore be re-fetched via its id.

It doesn’t matter where the User whose friends we’re paginating is located in the query, the node interface let Relay refetch any Useras long as it has its id.

We have a whole article on pagination in Relay you’re encouraged to check out here.

Autogeneration of queries for your typical "Show more" functionality

In the same vein, Relay makes it really easy to build a classic "Show more" functionality. Relay can help you take something like this:

    fragment ProfilePage_user on User {
      id
      name
      avatarUrl
      bio @include(if: $showMore)
    }

...and generate a query that'll let you fetch that fragment again, but now including bio by setting $showMore to true.

Your experience of building the "show more" functionality would basically be as simple as running refetch({showMore: true}) when the user presses the "Show more"-button. Relay takes care of the rest, and it can do that because it knows how to refetch that User via its id using the Node interface, regardless of where that User is found.

Wrapping up

Hopefully you’ve now got some insight into why globally unique IDs and the Node interface is a good idea. Relay make great use of it, and since it’s an official GraphQL best practice, any other tooling can build on top of it too.

Pagination with minimal effort in Relay

Gabriel Nordeborn — Thu, 16 Apr 2020 20:46:09 +0000

This series of articles is written by Gabriel Nordeborn and Sean Grove. Gabriel is a frontend developer and partner at the Swedish IT consultancy Arizon, and has been a Relay user for a long time. Sean is a co-founder of OneGraph.com, unifying 3rd-party APIs with GraphQL.

Pagination. Everyone gets there eventually, and - let’s be honest - it’s not fun. In this article we’ll show that when you follow a few conventions, pagination in Relay may not be fun, but it is easy and ergonomic.

This article will focus on simple pagination, without filters, and only paginating forward. But, Relay can paginate backwards just as easily, and handles the filter case beautifully. You can read more about those two things here.

Also, for pagination in Relay to be as sweet as it can, your GraphQL server will need to follow two specific GraphQL best practices:

Global object identification and the Node interface. We also have another article about that you can read here.
Connection based pagination. Again, we have a separate article you're much welcome to read here.

In this article, we’ll lay out a familiar example app first, and then walk through the challenges in implementing the required pagination. Finally, we’ll illustrate Relay’s solution to said problems.

How is pagination typically done in GraphQL clients?

Pagination usually consists of this:

You fetch some form of initial list of items, usually through another query (typically the main query for the view you’re in). This query normally contains a bunch of other things in addition to items from the list you want to paginate.
You define a separate query that can fetch more items for the list.
You use the separate query with the appropriate cursor that you got from the first query in order to paginate forward, specifying the number of items you want
Then you write code to merge the items from the first list with the new items, and re-render your view

Let’s see that in action now, with a typical example that gets all the data for a user’s profile page:

    query ProfileQuery($userLogin: String!) {
      gitHub {
        user(login: $userLogin) {
          name
          avatarUrl
          email
          following {
            totalCount
          }
          followers(first: 5) {
            totalCount
            edges {
              node {
                id
                firstName
                lastName
                avatarUrl
              }
            }
          }
        }
      }
    }

Our query pulls out two groups of data we care about:

Profile information for our user, like name and email
A list of followers with some fields for each one. To start with, we just get the first 5 followers.

Now that we have our first query, let’s paginate to get the next 5 followers (we have some popular users!).

Trying to re-use the original query isn't good enough

The first thing we notice is that we probably shouldn't reuse the first query we defined for pagination. We’ll need a new query, because:

We don’t want to fetch all of the profile information for the user again, since we already have it and fetching it again might be expensive.
We know we want to start off with only the first 5 followers and delegate loading more to actual pagination, so adding variables for pagination in this initial query feels redundant and would add unnecessary complexity.

So, let’s write the new query:

     query UserProfileFollowersPaginationQuery(
      $userLogin: String!, 
      $first: Int!, 
      $after: String
    ) {
      gitHub {
        user(login: $userLogin) {
          followers(first: $first, after: $after) {
            pageInfo {
              hasNextPage
              endCursor
            }
            edges {
              node {
                id
                firstName
                lastName
                avatarUrl
              }
            }
          }
        }
      }
    }

Here we go! We now have all we need to paginate. Great! But, there’s a few things to note here:

We need to write this query by hand
Even though we know what User we want to paginate followers on already, we need to give the query that information again through variables. This also needs to exactly match how our initial query is selecting the user, so we're getting the right one
We’ll need to manually give the query the next cursor to paginate from. Since this will always be the end cursor in this view, this is just manual labor that needs to be done

It’s a shame that we need to do all of this manual work. What if the framework could just generate this pagination query for us, and maybe deal with all the steps that will always be the same anyway…?

Well, using the node interface and connection based pagination, Relay can!

Pagination in Relay

Let’s illustrate how pagination works in Relay with a similar example to the one above - a simple profile page. The profile page lists some information about the user, and then also list the users friends. The list of friends should be possible to paginate.

    // Profile.ts
    import * as React from "react";
    import { useLazyLoadQuery } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import { ProfileQuery } from "./__generated__/ProfileQuery.graphql";
    import { FriendsList } from "./FriendsList";

    interface Props {
      userId: string;
    }

    export const Profile = ({ userId }: Props) => {
      const { userById } = useLazyLoadQuery<ProfileQuery>(
        graphql`
          query ProfileQuery($userId: ID!) {
            userById(id: $userId) {
              firstName
              lastName
              ...FriendsList_user
            }
          }
        `,
        {
          variables: { userId }
        }
      );

      if (!userById) {
        return null;
      }

      return (
        <div>
          <h1>
            {userById.firstName} {userById.lastName}
          </h1>
          <h2>Friends</h2>
          <FriendsList user={userById} />
        </div>
      );
    };

Here’s our root component for showing the profile page. As you can see it makes a query, asks for some information that it’s displaying itself (firstName and lastName), and then includes the FriendsList_user fragment, which contains the data the FriendsList component need on the User type to be able to render.

The power of true modularity of components

No pagination to be seen anywhere so far though, right? Hold on, it’s coming! But, first, notice this: This component doesn’t need to know that <FriendsList /> is doing pagination. That is another strength of Relay. Let’s highlight a few implications this has:

Any component can introduce pagination in isolation without needing any action from components that already render it. Thinking “meh”? You won't when you have a component spread out through a fairly large number of screens that you need to introduce pagination to without it being a 2 week project.
ProfileQuery doesn’t need to define anything unnecessary, like variables, just to ensure that <FriendsList /> can paginate.
Alluding to the points above, this means that no implicit (or explicit) dependencies are created between components, which in turn means that you can safely refactor and maintain your components without risking breaking stuff. It also means you can do said things fast.

Building the component that does the pagination

Below is the FriendsList component, which is what’s actually doing the pagination. This is a bit more dense:

    // FriendsList.ts
    import * as React from "react";
    import { usePaginationFragment } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import { FriendsList_user$key } from "./__generated__/FriendsList_user_graphql";
    import { FriendsListPaginationQuery } from "./__generated__/FriendsListPaginationQuery_graphql";
    import { getConnectionNodes } from "./utils/getConnectionNodes";

    interface Props {
      user: FriendsList_user$key;
    }

    export const FriendsList = ({ user }: Props) => {
      const { data, hasNext, loadNext, isLoadingNext } = usePaginationFragment<
        FriendsListPaginationQuery,
        _
      >(
        graphql`
          fragment FriendsList_user on User
            @argumentDefinitions(
              first: { type: "Int!", defaultValue: 5 }
              after: { type: "String" }
            )
            @refetchable(queryName: "FriendsListPaginationQuery") {
            friends(first: $first, after: $after)
              @connection(key: "FriendsList_user_friends") {
              edges {
                node {
                  id
                  firstName
                }
              }
            }
          }
        `,
        user
      );

      return (
        <div>
          {getConnectionNodes(data.friends).map(friend => (
            <div key={friend.id}>
              <h2>{friend.firstName}</h2>
            </div>
          ))}
          {hasNext ? (
            <button
              disabled={isLoadingNext}
              onClick={() => loadNext(5)}
            >
              {isLoadingNext ? "Loading..." : "Load more"}
            </button>
          ) : null}
        </div>
      );
    };

There’s a lot going on here, and we will break it all down momentarily, but notice how little manual work we’ve needed to do. Here’s a few things to note:

No need to define a custom query to use for paginating. It’s automatically generated for us by Relay.
No need to keep track of what’s the next cursor to paginate from. Relay does it for us, so we can’t mess that up.
No need for any custom logic for merging the pagination results with what’s already in the store. Relay does it for us.
No need to do anything extra to keep track of the loading state or if there are more items I can load. Relay supplies us with that with no additional action needed from our side.

Other than the benefit that less code is nice just by itself, there’s also the benefit of less hand rolled code meaning less things to potentially mess up.

Let’s break down everything in the code snippet above that make that possible, because there’s likely a few things in there making you scratch your head:

    import { FriendsList_user$key } from "./__generated__/FriendsList_user_graphql";
    import { FriendsListPaginationQuery } from "./__generated__/FriendsListPaginationQuery_graphql";

At the top we’re importing a bunch of type definitions from a __generated__ folder. These are to ensure type safety for both for the fragment we’re defining and the for pagination query that is automatically generated for us by the Relay compiler for each GraphQL operation we define in our project.

    import { getConnectionNodes } from "./utils/getConnectionNodes";

We also import a function called getConnectionNodes. This is a custom helper that can extract all nodes from any connection into an array in a type safe way. It’s not from the official Relay packages, but it’s very easy to make one yourself, as you can see an example of here. It’s a great example of the type of tooling you can build easily because of standardization.

      const { data, hasNext, loadNext, isLoadingNext } = usePaginationFragment<
        FriendsListPaginationQuery,
        _
      >(
        graphql`
          fragment FriendsList_user on User
            @argumentDefinitions(
              first: { type: "Int!", defaultValue: 5 }
              after: { type: "String" }
            )
            @refetchable(queryName: "FriendsListPaginationQuery") {
            friends(first: $first, after: $after)
              @connection(key: "FriendsList_user_friends") {
              edges {
                node {
                  id
                  firstName
                }
              }
            }
          }
        `,
        user
      );

We use a hook called usePaginationFragment which gives us back a bunch of props related to pagination. It also gives us data, which is the data for the FriendsList_user fragment we’re defining.

Speaking of the fragment, that’s where most of the good stuff is happening. Let’s go deeper into what’s going on in the fragment definition.

            @argumentDefinitions(
              first: { type: "Int!", defaultValue: 5 }
              after: { type: "String" }
            )

Relay let you define arguments for fragments

The first thing that stands out is that we’ve added a directive to the fragment called @argumentDefinitions, which define two arguments, first (as Int!) and after (as String). first is required, so if no argument is given to the fragment for that, Relay will use the defined default value, which in this case is 5. This is how Relay knows to fetch the first 5 followers in ProfileQuery.

The ability to define arguments for fragments is another feature of Relay that make all the difference for modularity and scalability. We won’t go deeper into exactly how this works, but this would allow any user of the FriendsList_user fragment to override the values of first and after when using that fragment. Like this:

    query SomeUserQuery {
      loggedInUser {
        ...FriendsList_user @arguments(first: 10)
      }
    }

This would fetch the first 10 followers directly in <FriendsList /> instead of just the first 5, which is the default.

Relay writes your pagination query for you

            @refetchable(queryName: "FriendsListPaginationQuery")

After that comes another directive, @refetchable. This is telling Relay that you want to be able to refetch the fragment with new variables, and queryName that’s provided to the directive says that FriendsListPaginationQuery is what you want the generated query to be called.

This would generate a query that looks roughly like this:

    query FriendsListPaginationQuery($id: ID!, $first: Int!, $after: String!) {
      node(id: $id) {
        ... on User {
          friends(first: $first, after: $after) {
            pageInfo {
              endCursor
              hasNextPage
              startCursor
              hasPreviousPage
            }
            edges {
              node {
                id
                firstName
              }
              cursor
            }
          }
        }
      }
    }

But you don’t need to know, think or care about this! Relay will take care of all the plumbing for you, like supplying all needed variables for the query (like id and after, which is the cursor to paginate from next). You only need to say how many more items you want to fetch.

This is the meat of what makes pagination so ergonomic with Relay - Relay will literally write your code and queries for you, hiding all of that complexity of pagination for you!

Let Relay know where it can find your connection, and it’ll do the rest

            friends(first: $first, after: $after)
              @connection(key: "FriendsList_user_friends") {
              edges {
                node {
                  id
                  firstName
                }
              }
            }
          }

**friends(first: $first, after: $after)**
After that comes the field selection. friends is the field with the connection we want to paginate. Notice that we’re passing that the first and after arguments defined in @argumentDefinitions.

**@connection**
Attached to friends is another directive, @connection(key: "FriendsList_user_friends"). This directive tell Relay that here’s the location of the connection you want to paginate. Adding this allow Relay to do a few things, like automatically add the full selection for pageInfo on the connection selection in the query that’s sent to the server. Relay then uses that information both to tell you whether you can load more, and to automatically use the appropriate cursor for paginating. Again, removing manual steps that can go wrong and automating them.

Again, you don’t need to see or think about this as Relay takes care of all of this, but the actual selection on friends that’s sent to the server look something like this:

    friends(first: $first, after: $after) {
      pageInfo {
        endCursor
        hasNextPage
        startCursor
        hasPreviousPage
      }
      egdes {
        node {
          ...
        }
        cursor
      }
    }

By adding the @connection annotation, Relay knows where to add the selections it needs to know how to paginate.

The next thing @connection does is tell Relay what key you want to use if you need to interact with this connection in the cache, like when adding or removing items to the connection through cache updates. Setting a unique key here is important because you may have multiple lists paginating over the same connection at the same time.

It also means that Relay can infer the location of everything it needs to extract from the pagination response and add to the current pagination list.

            <button
              disabled={isLoadingNext}
              onClick={() => loadNext(5)}
            >

Other than that, most of the code that actually use the things Relay give us should be fairly self explanatory.

How can this work?

So, summing up what pagination looks like, you’re basically giving Relay the information it needs through directives in your fragment definition, and in return Relay automates everything it can for you.

But, how can Relay do all of this?

It all boils down to conventions and standardization. If you follow the global identification and node interface specification, Relay can:

Automatically generate a query to refetch the particular node we’re on, and automatically add the fragment we’re refetching to that query
Ensure you won’t need to supply any variables for the generated query at all, since it knows that the id for the object we’re looking at can only lead to that particular object

And, by following the connection specification for pagination, Relay can:

Automatically add whatever metadata selection it needs to the queries, both the initial ProfileQuery and the generated FriendsListPaginationQuery
Automatically merge the pagination results with the existing list, since it knows that the structure of the data is a standardized connection, and therefore it can extract whatever it needs
Automatically keep track of what cursor to use for loading more results, since that will be available on pageInfo in a standardized way. pageInfo which it (as mentioned above) can automatically insert into the query selection without you knowing about it. Again because it’s standardized.

And the result is really sweet. In addition to making pagination much more ergonomic, Relay has also eliminated just about every surface for manual errors we’d otherwise have.

Wrapping up

In this article, we’ve tried to highlight just how much a framework like Relay can automate for you, and how incredible the DX can be, if you follow conventions. This article has tried to shed some light on the following:

Pagination in GraphQL can require a lot of manual work and offer lots of surface for messing up as a developer
By following conventions, a framework like Relay can turn the pagination experience into something incredibly ergonomic and remove most (if not all) surfaces for manual errors

While this is a good primer, there are many more features and capabilities for pagination in Relay that we can explore. You can read all about that in Relay’s official documentation here.

Thank you for reading!

Connection based pagination in GraphQL

Gabriel Nordeborn — Thu, 16 Apr 2020 20:45:52 +0000

This series of articles is written by Gabriel Nordeborn and Sean Grove. Gabriel is a frontend developer and partner at the Swedish IT consultancy Arizon, and has been a Relay user for a long time. Sean is a co-founder of OneGraph.com, unifying 3rd-party APIs with GraphQL.

Connection based pagination is a way of structuring how you do pagination so it caters to both simple and a bit more advanced pagination. It was recently promoted to an official GraphQL best practice, and this article will focus on why it’s a good thing in GraphQL, and what type of tooling it enables.

There are numerous of resources about what connection based pagination is and why it’s useful. If you want to get your feet wet before reading this article, we recommend having a look at the official GraphQL website section on pagination.

Standardization is the win

Connection based pagination is all about using a standardized contract for pagination. Now, why would you care about that? Well, as we’ll show you throughout this article, a standardized contract means tooling and frameworks can integrate deeply with it. And that in turn means that your life as a developer will be a whole lot easier. It also means we can ship a lot faster, as our tooling will be doing some heavy lifting for us.

What is it and what is it suitable for?

Connection based pagination is best suited for infinite scroll type pagination, where you keep adding an arbitrary amount of items to an already existing list as you move through the UI. If you’re looking to implement pagination that fetches an entire page of items in isolation rather than continuously adding to an existing list, you’re better off implementing that separately.

The key here is that connection based pagination is just a way of structuring the contract for pagination. While there may be implications for how you fetch your data backend when using connection based pagination, the primary purpose of using it in the GraphQL world is to provide a standardized structure for paginating, rather than committing your backend to a specific pagination strategy.

A standardized structure for pagination

Now, let’s look at an example of the structure that connection based pagination follows. Imagine we’re building a search feature for finding movies we think you'll like. Our search backend is really smart, so we're able to factor in a bunch of things in our assessment of what we think you'd like to watch. The definition below symbolizes fetching and paginating a list of Movie by an arbitrary search term. The search term could be something like action movies, or romcoms. Our search engine can make sense of it all!

Feel free to skim through the spec - don’t spend time trying to understand it now. It’ll just be good to have the general shape in the back of your mind as you read the rest of the article.

    type Movie {
      id: ID!
      name: String!
      releasedYear: Int!
      coverUrl: String!
    }

    # An edge for the Movie type
    type MovieEdge {
      node: Movie # The node, Movie in this case, for this edge
      cursor: String # The cursor for this edge
    }

    # Metadata for the current pagination
    type PageInfo {
      hasNextPage: Boolean!
      endCursor: String
      hasPreviousPage: Boolean!
      startCursor: String
    }

    # The connection, aka the root type of the pagination.
    type MovieConnection {
      pageInfo: PageInfo!
      edges: [MovieEdge]
    }

    type Query {
      # first, last, after and before can be used to paginate forward and backward
      movies(
        query: String!
        first: Int, 
        last: Int, 
        after: String, 
        before: String
      ): MovieConnection
    }

That’s a lot of structure for something that should be really simple, right? Like mentioned above, just keep the structure in the back of your head, and let’s look at a typical scenario of how pagination is implemented and how it can grow in a project.

A common scenario of how pagination is implemented

Most applications need some form of pagination sooner or later, and it can be implemented in sorts of different ways. Let’s paint a scenario of how implementing the most common, run-of-the-mill pagination in GraphQL might look.

Step 1. The “simplest possible pagination”

Building on our movies example above, we’ll design a search function that can paginate movies by an arbitrary search query, like the wild west or intense action.

Most people (understandably!) start out basic: “We just want some very simple pagination, no need to be fancy”. It usually ends up looking something like this:

    type Query {
      searchMovies(
        query: String!
        limit: Int
        offset: Int
      ): [Movie!]
    }

We’re filtering a simple list of Movie using a search query to find the the best matching movies for that search query. This is all fine and work well!

Step 2. How do we know if there are more results?

The product evolves, and we want to add a nice “See more movies”-button to our UI if there are more movies that can be fetched. But, since we’re just returning a list in the example above, we have no way of knowing whether there are more results to load or not.

Well, we can solve this too quite easily! Let’s extend our example. We don’t want to modify an individual Movie (it wouldn’t make sense to have a hasNextPage property there), so we need searchMovies to return a little wrapper object (MovieSearchResult ) where we can put our metadata:

    type MovieSearchResult {
      hasNext: Boolean
      items: [Movie!]
    }

    type Query {
      searchMovies(
        query: String!
        limit: Int
        offset: Int
      ): MovieSearchResult!
    }

Great, this does everything we need. Problem solved.

Step 3. When using offset break down

Our product evolves and we now need to make sure that we can produce a unique URL for continuing pagination from a specific Movie in our results.

The immediate reaction may be to build a URL like this:
/search?limit=${limit}&offset=${offset}&query=${query}

This should work, right? Sadly, not so well.

What happens when movies are added to the database and would end up before the movie we’re currently looking at in the results? The offset wouldn’t point to the movie we want.

Let’s step back and express our intentions like human-beings talking to a backend API maintainer for a second:

I have all of the movie results up to “Frost 2”. I’d like to get the next 10 movies after Frost 2, please!

We’ve described enough of our intentions so that a human would know, “Oh, there have been a few other movies added and some removed that also match your search query, but here are the 10 after Frost 2 specifically.” That’s the behavior we want in our pagination!

For this to work, we’ll need to be able to paginate from a specific item in the results. So naturally we’ll need a way of identifying a single item in the results. There’s a pre-existing concept for that called cursors - we’ll just use that concept (the best artist steal, and all that), and tweak our search query to support it.

    type MovieSearchResultWrapper {
      movie: Movie
      cursor: String
    }

    type MovieSearchResult {
      hasNext: Boolean
      items: [MovieSearchResultWrapper!]
    }

    type Query {
      searchMovies(
        query: String!
        limit: Int
        cursor: String
      ): MovieSearchResult!
    }

We can now query movie's by a cursor instead of just offset, and we’ll have access to the cursor for each result. This will ensure that our pagination is stable (items added before the current item won’t mess up the listing as before). We can now produce a URL like this:

/search?limit=${limit}&cursor=${cursor}&query=${query}

This URL will be stable, and always point to search results starting from the item in the results list (even if several have been added or removed in the meantime). Excellent!

Step 4. Metadata relevant for each individual item in the search result

A new feature request comes in - since we have all this fancy knowledge about how well we think each result both matches your taste and how relevant it is to your query, we naturally want to flex our muscles as show that to the user!

However, this is data that's only really valid for a specific result item with a specific search query. Our search engine also automatically produces that information for us in an efficient way for each search result (since that's what it's already using to order the results). But, where would it be logical to put that information for each result if we don’t want to extend the root Movie type (because that wouldn't really make sense)? Well, we just introduced MovieSearchResultWrapper for our cursor needs, and it happens to keep metadata only relevant to this particular search. Let’s put it there:

    type MovieSearchResultWrapper {
      movie: Movie
      cursor: String
      relevanceFactor: Float
    }

Excellent, we now have a nice number we can turn into some fancy gauge meter and everyone will be happy!

Wait - didn’t we just implement connection based pagination organically?

If you look at what we’ve produced organically here and compare it to the initial structure we drew up with connection based pagination, aren’t these two virtually the same? Yes they are! Let’s fit the model above into a connection structure:

    type Movie {
      id: ID!
      name: String!
      releasedYear: Int!
      coverUrl: String!
    }

    type MovieEdge {
      node: Movie # "node" is a generalized name for an item in a collection
      cursor: String # The cursor for this result item fits naturally here
      relevanceFactor: Float # More metadata only relevant to this result fits here too
    }

    # All the meta data we'll need to continue paginating
    type PageInfo {
      hasNextPage: Boolean!
      endCursor: String
      hasPreviousPage: Boolean!
      startCursor: String
    }

    # The root type for the pagination. Again, generalized/standardized name
    type MovieConnection {
      pageInfo: PageInfo!
      edges: [MovieEdge]
    }

    type Query {
      searchMovies(
        query: String!
        first: Int, 
        last: Int, 
        after: String, 
        before: String
      ): MovieConnection
    }

So, instead of using our own naming schemes, we can easily fit our pagination into the connection based model. But what’s the benefit of doing that? Maybe you disagree with the naming, think it’s too complicated, or you’re at the stage where simple pagination’s the only thing that’s needed for the foreseeable future. Why care?

Templating removes decisions so you can focus on other stuff that sparks joy(tm)

It turns our we can take our schema above and template-ize it, so any time we want to paginate a list of Grungle, we can just fill in the holes:

    type `${nounWeWantToPaginate} {
      ${...noun fields}
    }

    type ${noun}Edge {
      node: ${noun} # "node" is a generalized name for an item in a collection - it's our noun!
      cursor: String # The cursor for this result item fits naturally here
      ${... any bits of pagination metadata for our noun}
    }
    # All the meta data we'll need to continue paginating
    # This stays the same!
    type PageInfo {
      hasNextPage: Boolean!
      endCursor: String
      hasPreviousPage: Boolean!
      startCursor: String
    }

    # The root type for the pagination. Again, generalized/standardized name
    type ${noun}Connection {
      pageInfo: PageInfo!
      edges: [${noun}Edge]
    }

    type Query {
      ${noun}s(
        first: Int, 
        last: Int, 
        after: String, 
        before: String
      ): ${noun}Connection
    }

Having a template like this makes it much easier to just drop in pagination for a list of our ${noun}

Standardization == tooling can make your life much easier

More importantly though, conventions what we’ve just built up make it easy for tooling to simplify our lives. Here are a few benefits that connection based pagination bring, and what tooling can do for you:

Future proofed pagination
Because the structure provided for connection based pagination give you a logical place to put the things you might eventually need when paginating (like cursors, metadata about additional results and metadata about this specific result item in this specific search), you’re actually future proofing your API when implementing connection based pagination. Even if you don’t need any of the more advanced features we've talked about initially, adding them when you do will be easy since the structure is already there.

Generalized tooling
It’s easy to write generalized tooling. For example, a function that take any ${noun}Connection and return a list of the nodes in the connection, letting you avoid dealing with the somewhat complex structure of connections manually.

It’s also easy to build tooling on the backend. The same thing applies there - it’s standardized, so you can build generic tooling for it. For example, the template we saw above can be turned into a single makeNounPaginator(…) so even making pagination on the backend is easier!

Allow frameworks to do all the heavy lifting for you
But, as frontend developers, perhaps the best part of it all is that if it’s standardized, a framework can build on top of it. Relay is an excellent example of this. Pagination in Relay is incredibly ergonomic and easy when you follow the connection spec. Here’s an article explaining pagination in Relay and what make it great that we really encourage you to read.

Wrapping up

We hope you’ve gotten a feel for what connection based pagination is and why it makes sense by reading this article. Please feel free to drop us a line in the comments below if you have any questions or comments.

Also, as mentioned above, you should really continue by reading our article on pagination in Relay. Relay leverages what we've talked about here to create a superb developer experience for doing pagination, and is a great example of exactly the type of benefits we mean a standardized structure like connection based pagination enables.

If you're a member on Egghead and want to see this article in an 11-minute video form, check out Nik Graf's excellent Paginate Entries using the Connection Specification lesson!

Relay: the GraphQL client that wants to do the dirty work for you

Gabriel Nordeborn — Thu, 16 Apr 2020 20:44:10 +0000

This series of articles is written by Gabriel Nordeborn and Sean Grove. Gabriel is a frontend developer and partner at the Swedish IT consultancy Arizon and has been using Relay for a long time. Sean is a co-founder of OneGraph.com, unifying 3rd-party APIs with GraphQL.

This is a series of articles that will dive juuuuust deep enough into Relay to answer - definitively - one question:

Why in the world would I care about Relay, Facebook’s JavaScript client framework for building applications using GraphQL?

It’s a good question, no doubt. In order to answer it, we’ll take you through parts of building a simple page rendering a blog. When building the page, we’ll see two main themes emerge:

Relay is, in fact, an utter workhorse that wants to do the dirty work for you.
If you follow the conventions Relay lays out, Relay will give you back a fantastic developer experience for building client side applications using GraphQL.

We’ll also show you that Relay applications are scalable, performant, modular, and resilient to change by default, and apps built with it are future proofed for the new features in development for React right now.

Relay comes with a (relatively minor) set of costs, which we’ll examine honestly and up-front, so the tradeoffs are well understood.

Setting the stage

This article is intended to showcase the ideas and philosophy of Relay. While we occasionally contrast how Relay does things against other GraphQL frameworks, this article is not primarily intended as a comparison of Relay and other frameworks. We want to talk about and dive deep into Relay all by itself, explain its philosophy and the concepts involved in building applications with it.

This also means that the code samples in this article (there are a few!) are only here to illustrate how Relay works, meaning they can be a bit shallow and simplified at times.

We’ll also focus exclusively on the new hooks-based APIs for Relay, which come fully-ready for React’s Suspense and Concurrent Mode. While the new APIs are still marked as experimental, Facebook is rebuilding facebook.com using Relay and said APIs exclusively for the data layer.

Also, before we start - this article will assume basic familiarity with GraphQL and building client side JavaScript applications. Here’s an excellent introduction to GraphQL if you feel you’re not quite up to speed. Code samples will be in TypeScript, so a basic understanding of that will help too.

Finally, this article is pretty long. See this as a reference article you can come back to over time.

With all the disclaimers out of the way, let’s get going!

Quick overview of Relay

Relay is made up of a compiler that optimizes your GraphQL code, and a library you use with React.

Before we dive into the deep end of the pool, let’s start with a quick overview of Relay. Relay can be divided into two parts:

The compiler: responsible for all sorts of optimizations, type generation, and enabling the great developer experience. You keep it running in the background as you develop.
The library: the core of Relay, and bindings to use Relay with React.

At this point, all you need to know about the compiler is that it’s a separate process you start that watches and compiles all of your GraphQL operations. You'll hear more about it soon though.

In addition to this, for Relay to work optimally, it wants your schema to follow three conventions:

All id fields on types should be globally unique (i.e. no two objects - even two different kinds of objects - may share the same id value).
The Node interface, meaning: objects in the graph should be fetchable via their id field using a top level node field. Read more about globally unique id’s and the Node interface (and why it’s nice!) here.
Pagination should follow the connection based pagination standard. Read more about what connection based pagination is and why it is a good idea in this article.

We won’t dive into the conventions any deeper at this point, but you’re encouraged to check out the articles linked above if you’re interested.

At the heart of Relay: the fragment

Let’s first talk about a concept that's at the core of how Relay integrates with GraphQL: Fragments. It’s one of the main keys to Relay (and GraphQL!)'s powers, after all.

Simply put, fragments in GraphQL are a way to group together common selections on a specific GraphQL type. Here’s an example:

    fragment Avatar_user on User {
      avatarUrl
      firstName
      lastName
    }

For the curious: Naming the fragment Avatar_user is a convention that Relay enforces. Relay wants all fragment names to be globally unique, and to follow the structure of <moduleName>_<propertyName>. You can read more about naming conventions for fragments here, and we'll talk about why this is useful soon.

This defines a fragment called Avatar_user that can be used with the GraphQL type User. The fragment selects what’s typically needed to render an avatar. You can then re-use that fragment throughout your queries instead of explicitly selecting all fields needed for rendering the avatar at each place where you need them:

    # Instead of doing this when you want to render the avatar for the author 
    # and the first two who liked the blog post...
    query BlogPostQuery($blogPostId: ID!) {
      blogPostById(id: $blogPostId) {
        author {
          firstName
          lastName
          avatarUrl
        }
        likedBy(first: 2) {
          edges {
            node {
              firstName
              lastName
              avatarUrl
            }
          }
        }
      }
    }

    # ...you can do this
    query BlogPostQuery($blogPostId: ID!) {
      blogPostById(id: $blogPostId) {
        author {
          ...Avatar_user
        }
        likedBy(first: 2) {
          edges {
            node {
              ...Avatar_user
            }
          }
        }
      }
    }

This is convenient because it allows reusing the definition, but more importantly it lets you add and remove fields that are needed to render your avatar as your application evolves in a single place.

Fragments allow you to define reusable selections of fields on GraphQL types.

Relay doubles down on fragments

To scale a GraphQL client application over time, it’s a good practice to try and co-locate your data requirements with the components that render said data. This will make maintenance and extending your components much easier, as reasoning about your component and what data it uses is done in a single place.

Since GraphQL fragments allow you to define sub-selections of fields on specific GraphQL types (as outlined above), they fit the co-location idea perfectly.

So, a great practice is to define one or more fragments describing the data your component needs to render. This means that a component can say, “I depend on these 3 field from the User type, regardless of who my parent component is.” In the example above, there would be a component called <Avatar /> that would show an avatar using the fields defined in the Avatar_user fragment.

Now, most frameworks let you use GraphQL fragments one way or another. But Relay takes this further. In Relay, almost everything revolves around fragments.

How Relay supercharges the GraphQL fragment

At its core, Relay wants every component to have a complete, explicit list of all of its data requirements listed alongside the component itself. This allows Relay to integrate deeply with fragments. Let’s break down what this means, and what it enables.

Co-located data requirements and modularity

With Relay, you use fragments to put the component’s data requirements right next to the code that’s actually using it. Following Relay's conventions guarantees that every component explicitly lists every field it needs access to. This means that no component will depend on data it doesn't explicitly ask for, making components modular, self-contained and resilient in the face of reuse and refactoring.

Relay does a bunch of additional things to enable modularity through using fragments too, which we'll visit a bit later in this article.

Performance

In Relay, components will only re-render when the exact fields they're using change - with no work on your part! This is because each fragment will subscribe to updates only for the data it selects.

That lets Relay optimize how your view is updated by default, ensuring that performance isn’t unnecessary degraded as your app grows. This is quite different to how other GraphQL clients operate. Don’t worry if that didn’t make much sense yet, we’ll show off some great examples of this below and how important it is for scalability.

With all that in mind, let’s start building our page!

Relay doubles down on the concept of fragments, and uses them to enable co-location of data requirements, modularity and great performance.

Building the page to render the blog post

Here’s a wireframe of what our page showing a single blog post will look like:

First, let’s think of how we’d approach this with getting all the data for this view through a single top-level query. A very reasonable query to fulfill the wireframe’s need might look something like this:

    query BlogPostQuery($blogPostId: ID!) {
      blogPostById(id: $blogPostId) {
        author {
          firstName
          lastName
          avatarUrl
          shortBio
        }
        title
        coverImgUrl
        createdAt
        tags {
          slug
          shortName
        }
        body
        likedByMe
        likedBy(first: 2) {
          totalCount
          edges {
            node {
              firstName
              lastName
              avatarUrl
            }
          }
        }
      }
    }

One query to fetch all the data we need! Nice!

And, in turn, the structure of UI components might look something like this:

    <BlogPost>
      <BlogPostHeader>
        <BlogPostAuthor>
          <Avatar />
        </BlogPostAuthor>
      </BlogPostHeader>
      <BlogPostBody>
        <BlogPostTitle />
        <BlogPostMeta>
          <CreatedAtDisplayer />
          <TagsDisplayer />
        </BlogPostMeta>
        <BlogPostContent />
        <LikeButton>
          <LikedByDisplayer />
        </LikeButton>
      </BlogPostBody>
    </BlogPost>

Let’s have a look at how we’d build this in Relay.

Querying for data in Relay

In Relay, the root component rendering the blog post would typically look something like this:

    // BlogPost.ts
    import * as React from "react";
    import { useLazyLoadQuery } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import { BlogPostQuery } from "./__generated__/BlogPostQuery.graphql";
    import { BlogPostHeader } from "./BlogPostHeader";
    import { BlogPostBody } from "./BlogPostBody";

    interface Props {
      blogPostId: string;
    }

    export const BlogPost = ({ blogPostId }: Props) => {
      const { blogPostById } = useLazyLoadQuery<BlogPostQuery>(
        graphql`
          query BlogPostQuery($blogPostId: ID!) {
            blogPostById(id: $blogPostId) {
              ...BlogPostHeader_blogPost
              ...BlogPostBody_blogPost
            }
          }
        `,
        {
          variables: { blogPostId }
        }
      );

      if (!blogPostById) {
        return null;
      }

      return (
        <div>
          <BlogPostHeader blogPost={blogPostById} />
          <BlogPostBody blogPost={blogPostById} />
        </div>
      );
    };

Let’s break down what’s going on here, step by step.

      const { blogPostById } = useLazyLoadQuery<BlogPostQuery>(
        graphql`
          query BlogPostQuery($blogPostId: ID!) {
            blogPostById(id: $blogPostId) {
              ...BlogPostHeader_blogPost
              ...BlogPostBody_blogPost
            }
          }
        `,
        {
          variables: { blogPostId }
        }
      );

The first thing to note is the React hook useLazyLoadQuery from Relay:
const { blogPostById } = useLazyLoadQuery<BlogPostQuery>. useLazyLoadQuery will start fetching BlogPostQuery as soon as the component renders.

For type safety, we’re annotating useLazyLoadQuery to explicitly state the type, BlogPostQuery, which we import from ./__generated__/BlogPostQuery.graphql. That file is automatically generated (and kept in sync with changes to the query definition) by the Relay compiler, and has all the type information needed for the query - how the data coming back looks, and what variables the query wants.

Disclaimer time!: As mentioned, useLazyLoadQuery will start fetching the query as soon as it renders. However, note that Relay actually doesn’t want you to lazily fetch data on render like this. Rather, Relay wants you to start loading your queries as soon as you can, like right when the user is clicking the link to a new page, instead of as the page renders. Why this is so important is talked about at length in this blog post, and in this talk, which we warmly recommend you to read and watch.
We’re still using the lazy load variant in this article though because it's a more familiar mental model for most people, and to keep things as simple and easy to follow as possible. But, please do note that as mentioned above this isn't how you should fetch your query data when building for real with Relay.

Next, we have our actual query:

    graphql`
      query BlogPostQuery($blogPostId: ID!) {
        blogPostById(id: $blogPostId) {
          ...BlogPostHeader_blogPost
          ...BlogPostBody_blogPost
      }
    }`

Defining our query, there’s really not a whole lot left of the example query we demonstrated above. Other than selecting a blog post by its id, there’s only two more selections - the fragments for <BlogPostHeader /> and <BlogPostBody /> on BlogPost.

Notice that we don’t have to import the fragments we’re using. These are included automatically by the Relay compiler. More about that in a second.

Building your query by composing fragments together like this is very important. Another approach would be to let components define their own queries and be fully responsible for fetching their own data. While there are a few valid use cases for this, this comes with two major problems:

A ton of queries are sent to your server instead of just one.
Each component making their own query would need to wait until they’re actually rendered to start fetching their data. This means your view will likely load quite a lot slower than needed, as requests would probably be made in a waterfall.

In Relay, we build UIs by composing components together. These components define what data they need themselves in an opaque way.

How Relay enforces modularity

Here’s the mental model to keep in mind with the code above:

As the BlogPost component, I only know I want to render two children components, BlogPostHeader and BlogPostBody. I don’t know what data they need (why would I? That’s their responsibility to know!).
Instead, they’ve told me all the data they need is in a fragment called BlogPostHeader_blogPost and BlogPostBody_blogPost on the BlogPost GraphQL type. As long as I include their fragments in my query, I know I’m guaranteed to get the data they need, even though I don’t know any of the specifics. And when I have the data they need, I'm allowed to render them.

We build our UI by composing components that define their own data requirements in isolation. These components can then be composed together with other components with their own data requirements. However, no component really knows anything about what data other components need, other than from what GraphQL source (type) the component needs data. Relay takes care of the dirty work, making sure the right component gets the right data, and that all data needed is selected in the query that gets sent to the server.

This allows you, the developer, to think in terms of components and fragments in isolation, while Relay handles all the plumbing for you.

Moving on!

The Relay compiler knows all GraphQL code you’ve defined in your project

Notice that while the query is referencing two fragments, there’s no need to tell it where or in what file those fragments are defined, or to import them manually to the query. This is because Relay enforces globally unique names for every fragment, so that the Relay compiler can automatically include the fragment definitions in any query that's being sent to the server.

Referencing fragment definitions by hand, another inconvenient, manual, potentially error-prone step, is no longer the developer’s responsibility with Relay.

Using fragments tightly coupled to components allows Relay to hide the data requirements of a component from the outside world, which leads to great modularity and safe refactoring.

Finally, we get to rendering our results:

      // Because we spread both fragments on this object
      // it's guaranteed to satisfy both `BlogPostHeader`
      // and `BlogPostBody` components.
      if (!blogPostById) {
        return null;
      }

      return (
        <div>
          <BlogPostHeader blogPost={blogPostById} />
          <BlogPostBody blogPost={blogPostById} />
        </div>
      );

Here we render <BlogPostHeader /> and <BlogPostBody />. Looking carefully, you may see that we render both by passing them the blogPostById object. This is the object in the query where we spread their fragments. This is the way fragment data is transferred with Relay - passing the object where the fragment has been spread to the component using the fragment, which the component then uses to get the actual fragment data. Don't worry, Relay doesn't leave you hanging. Through the type system Relay will ensure that you're passing the right object with the right fragment spread on it. More on this in a bit.

Whew, that’s a few new things right there! But we’ve already seen and expanded on a number of things Relay does to help us - things that we would normally have to do manually for no additional gain.

Following Relay’s conventions ensures that a component cannot be renderer without it having the data it asks for. This means you’ll have a hard time shipping broken code to production.

Let’s continue moving down the tree of components.

Building a component using fragments

Here's the code for <BlogPostHeader />:

    // BlogPostHeader.ts
    import * as React from "react";
    import { useFragment } from "react-relay/hooks";
    import { graphql } from "react-relay";
    import {
      BlogPostHeader_blogPost$key,
      BlogPostHeader_blogPost
    } from "./__generated__/BlogPostHeader_blogPost.graphql";
    import { BlogPostAuthor } from "./BlogPostAuthor";
    import { BlogPostLikeControls } from "./BlogPostLikeControls";

    interface Props {
      blogPost: BlogPostHeader_blogPost$key;
    }

    export const BlogPostHeader = ({ blogPost }: Props) => {
      const blogPostData = useFragment<BlogPostHeader_blogPost>(
        graphql`
          fragment BlogPostHeader_blogPost on BlogPost {
            title
            coverImgUrl
            ...BlogPostAuthor_blogPost
            ...BlogPostLikeControls_blogPost
          }
        `,
        blogPost
      );

      return (
        <div>
          <img src={blogPostData.coverImgUrl} />
          <h1>{blogPostData.title}</h1>
          <BlogPostAuthor blogPost={blogPostData} />
          <BlogPostLikeControls blogPost={blogPostData} />
        </div>
      );
    };

Our examples here only define one fragment per component, but a component could define any number of fragments, on any number of GraphQL types, including multiple fragments on the same type.

Let’s break it down.

    import {
      BlogPostHeader_blogPost$key,
      BlogPostHeader_blogPost
    } from "./__generated__/BlogPostHeader_blogPost.graphql";

We import two type definitions from the file BlogPostHeader_blogPost.graphql, autogenerated by the Relay compiler for us.

The Relay compiler will extract the GraphQL fragment code from this file and generate type definitions from it. In fact, it will do that for all the GraphQL code you write in your project and use with Relay - queries, mutations, subscriptions and fragments. This also means that the types will be kept in sync with any change to the fragment definition automatically by the compiler.

BlogPostHeader_blogPost contains the type definitions for the fragment, and we pass that to useFragment (useFragment which we'll talk more about soon) ensuring that interaction with the data from the fragment is type safe.

But what on earth is BlogPostHeader_blogPost$key on line 12 in interface Props { … }?! Well, it has to do with the type safety. You really really don’t have to worry about this right now, but for the curious we’ll break it down anyway (the rest of you can just skip to the next heading):

That type definition ensures, via some dark type magic, that you can only pass the right object (where the BlogPostHeader_blogPost fragment has been spread) to useFragment, or you’ll have a type error at build time (in your editor!). As you can see, we take blogPost from props and pass it to useFragment as the second parameter. And if blogPost does not have the right fragment (BlogPostHeader_blogPost) spread on it, we’ll get a type error.

It doesn't matter if another fragment with the exact same data selections has been spread on that object, Relay will make sure it's the exactly right fragment you want to use with useFragment. This is important, because it's another way Relay guarantees you can change your fragment definitions without any other component being affected implicitly.

Relay eliminates another source of potential errors: passing the exact right object containing the right fragment.

You can only use data you’ve explicitly asked for

We define our fragment BlogPostHeader_blogPost on BlogPost. Notice that we explicitly select two fields for this component:

- `title`
- `coverImgUrl`

That’s because we’re using these fields in this specific component. This highlights another important feature of Relay - data masking. Even if BlogPostAuthor_blogPost, the next fragment we’re spreading, also selects title and coverImgUrl (meaning they must be available in the query on that exact place where we'll get them from), we won’t get access to them unless we explicitly ask for them via our own fragment.

This is enforced both at the type level (the generated types won’t contain them) and at runtime - the values simply won’t be there even if you bypass your type system.

This can feel slightly weird at first, but it’s in fact another one of Relay’s safety mechanisms. If you know it’s impossible for other components to implicitly depend on the data you select, you can refactor your components without risking breaking other components in weird, unexpected ways. This is great as your app grows - again, every component and its data requirements become entirely self-contained.

Enforcing that all data a component requires is explicitly defined means you can’t accidentally break your UI by removing a field selection from a query or fragment that some other component was depending on.

      const blogPostData = useFragment<BlogPostHeader_blogPost>(
        graphql`
          fragment BlogPostHeader_blogPost on BlogPost {
            title
            coverImgUrl
            ...BlogPostAuthor_blogPost
            ...BlogPostLikeControls_blogPost
          }
        `,
        blogPost
      );

Here we're using the React hook useFragment to get the data for our fragment. useFragment knows how to take a fragment definition (the one defined inside the graphql tag) and an object where that fragment has been spread (blogPost here, which comes from props), and use that to get the data for this particular fragment.

Just to reiterate that point - no data for this fragment (title/coverImgUrl) will be available on blogPost coming from props - that data will only be available as we call useFragment with the fragment definition and blogPost, the object where the fragment has been spread.

And, just like before, we spread the fragments for the components we want to render - in this case, BlogPostAuthor_blogPost and BlogPostLikeControls_blogPost since we're renderering <BlogPostAuthor /> and <BlogPostLikeControls />.

For the curious: since fragments only describes what fields to select, useFragment won’t make an actual request for data to your GraphQL API. Rather, a fragment must end up in a query (or other GraphQL operation) at some point in order for its data to be fetched. With that said, Relay has some really cool features which will let you refetch a fragment all by itself. This is possible because Relay can generate queries automatically for you to refetch specific GraphQL objects by their id. Anyway, we digress...

Also, if you know Redux, you can liken useFragment to a selector that lets you grab only what you need from the state tree.

      return (
        <div>
          <img src={blogPostData.coverImgUrl} />
          <h1>{blogPostData.title}</h1>
          <BlogPostAuthor blogPost={blogPostData} />
          <BlogPostLikeControls blogPost={blogPostData} />
        </div>
      );

We then render the data we explicitly asked for (coverImgUrl and title), and pass the data for the two children components along so they can render. Notice again that we pass the object to the components where we spread their fragments, which is at the root of the fragment BlogPostHeader_blogPost this component defines and uses.

How Relay ensures you stay performant

When you use fragments, each fragment will subscribe to updates only for the data it’s actually using. This means that our <BlogPostHeader /> component above will only re-render by itself if coverImgUrl or title on the specific blog post it’s rendering is updated. If BlogPostAuthor_blogPost selects other fields and those update, this component still won’t re-render. Changes to data is subscribed to at the fragment level.

This may sound a bit confusing and perhaps not that useful at first, but it’s incredibly important for performance. Let’s take a deeper look at this by contrasting it to how this type of thing is typically done in when dealing with GraphQL data on the client.

With Relay, only the components using the data that was updated will re-render when data updates.

Where does the data come from in your view? Contrasting Relay to other frameworks

All data you use in your views must originate from an actual operation that gets data from the server, like a query. You define a query, have your framework fetch it from the server, and then render whatever components you want in your view, passing down the the data they need. The source of the data for most GraphQL frameworks is the query. Data flows from the query down into components. Here’s an example of how that’s typically done in other GraphQL frameworks (arrows symbolize how data flows):

Note: framework data store is what’s usually referred to as the cache in a lot of frameworks. For this article, assume that "framework data store" === cache.

The flow looks something like:

<Profile /> makes the query ProfileQuery and a request is issued to the GraphQL API
The response is stored in some fashion in a framework-specific data store (read: cache)
The data is delivered to the view for rendering
The view then continues to pass down pieces of the data to whatever descendant components needs it (Avatar, Name, Bio, etc.). Finally, your view is rendered

How Relay does it

Now, Relay does this quite differently. Let’s look at how this illustration looks for Relay:

What’s different?

Most of the initial flow is the same - the query is issued to the GraphQL API and the data ends up in the framework data store. But then things start to differ.
Notice that all components which use data get it directly from the data store (cache). This is due to Relay’s deep integration with fragments - in your UI, each fragment gets its own data from the framework data store directly, and does not rely on the actual data being passed down to it from the query where its data originated.
The arrow is gone from the query component down to the other components. We’re still passing some information from the query to the fragment that it uses to look up the data it needs from the data store. But we’re passing no real data to the fragment, all the real data is retrieved by the fragment itself from the data store.

So, that’s quite in depth into how Relay and other GraphQL frameworks tend to work. Why should you care about this? Well, this setup enables some pretty neat features.

Other frameworks typically use a query as the source of data, and rely on you passing the data down the tree to other components. Relay flips this around, and lets each component take the data it needs from the data store itself.

Performance for free

Think about it: When the query is the source of the data, any update to the data store that affects any data that query has forces a re-render for the component holding the query, so the updated data can flow down to any component that might use it. This means updates to the data store causes re-renders that must cascade through any number of layers of components that don’t really have anything to do with the update, other than taking data from parent components in order to pass on to children components.

Relay's approach of each component getting the data it needs from the store directly, and subscribing to updates only for the exact data it uses, ensures that we stay performant even as our app grows in size and complexity.

This is also important when using subscriptions. Relay makes sure that updated data coming in from the subscription only causes re-renders of the components actually using that updated data.

Using a Query as the source of data means your entire component tree will be forced to re-render when the GraphQL cache is updated.

Modularity and isolation means you can safely refactor

Removing the responsibility from the developer of routing the data from the query down to whichever component actually needs said data also removes another chance for developers to mess things up. There’s simply no way to accidentally (or worse, intentionally) depend on data that should just be passing through down the component tree if you can't access it. Relay again makes sure it does the heavy work for you when it can.

Using Relay and its fragment-first approach means it's really hard to mess up the data flow in a component tree.

It should of course be noted though that most of the cons of the “query as the source of data” approach can be somewhat mitigated by old fashioned manual optimization - React.memo, shouldComponentUpdate and so on. But that’s both potentially a performance problem in itself, and also prone to mistakes (the more fiddly a task, the more likely humans are to eventually mess it up). Relay on the other hand will make sure you stay performant without needing to think about it.

Each component receiving its own data from the cache also enables some really cool advanced features of Relay, like partially rendering views with the data that’s already available in the store while waiting for the full data for the view to come back.

Summarizing fragments

Let’s stop here for a bit and digest what type of work Relay is doing for us:

Through the type system, Relay is making sure this component cannot be rendered without the exact right object from GraphQL, containing its data. One less thing we can mess up.
Since each component using fragments will only update if the exact data it uses updates, updates to the cache is performant by default in Relay.
Through type generation, Relay is ensuring that any interaction with this fragment's data is type safe. Worth highlighting here is that type generation is a core feature of the Relay compiler.

Relay’s architecture and philosophy takes advantage of how much information is available about your components to the computer, from the data dependencies of components, to the data and its types offered by the server. It uses all this and more to do all sorts of work that normally we - the developers who have plenty to do already - are required to deal with.

It's easy to underestimate how quickly views become complex. Complexity and performance is handled by default through the conventions Relay force you to follow.

This brings some real power to you as a developer:

You can build composable components that are almost completely isolated.
Refactoring your components will be fully safe, and Relay will ensure you’re not missing anything or messing this up.

The importance of this once you start building a number of reusable components cannot be overstated. It’s crucial for developer velocity to have refactoring components used in large parts of the code base be safe.

As your app grows, the ease and safety of refactoring becomes crucial to continue moving fast.

Wrapping up our introduction to Relay

We’ve covered a lot of ground in this article. If you take anything with you, let it be that Relay forces you to build scalable, performant, type safe applications that will be easy and safe to maintain and refactor.

Relay really does do your dirty work for you, and while a lot of what we’ve shown will be possible to achieve through heroic effort with other frameworks, we hope we’ve shown the powerful benefits that enforcing these patterns can bring. Their importance cannot be overstated.

A remarkable piece of software

Relay is really a remarkable piece of software, built from the blood, sweat, tears, and most importantly - experience and deep insight - of shipping and maintaining products using GraphQL for a long time.

Even though this article is pretty long and fairly dense, we've barely scratched the surface of what Relay can do. Let's end this article with a list detailing some of what more Relay can do that we haven't covered in this article:

Mutations with optimistic and complex cache updates
Subscriptions
Fully integrated with (and heavily leveraging) Suspense and Concurrent Mode - ready for the next generation of React
Use Relay to manage your local state through Relay, enjoying the general benefits of using Relay also for local state management (like integration with Suspense and Concurrent Mode!)
Streaming list results via @stream
Deferring parts of the server response that might take a long time to load via @defer, so the rest of the UI can render faster
Automatic generation of queries for refetching fragments and pagination
Complex cache management; control how large the cache is allowed to get, and if data for your view should be resolved from the cache or the network (or both, or first the cache and then the network)
A stable, mature and flexible cache that Just Works (tm)
Preload queries for new views as soon as the user indicates navigation is about to happen _ Partially render views with any data already available in the store, while waiting for the query data to arrive
Define arguments for fragments (think like props for a component), taking composability of your components to the next level
Teach Relay more about how the data in your graph is connected than what can be derived from your schema, so it can resolve more data from the cache (think "these top-level fields with these variables resolve the same User")

This article ends here, but we really encourage you to go on and read the article on pagination in Relay. Pagination in Relay bring together the powerful features of Relay in a beautiful way, showcasing just how much automation and what incredible DX is possible when you let a framework do all the heavy lifting. Read it here

Here’s a few other articles you can continue with too:

The magic of the Node interface. An article about the Node interface, globally unique IDs and what power those things bring.
Connection based pagination. An introduction to why doing connection based pagination is a good idea.

Thank you for reading!

Special thanks

Many thanks to Xavier Cazalot, Arnar Þór Sveinsson, Jaap Frolich, Joe Previte, Stepan Parunashvili, and Ben Sangster for thorough feedback on the drafts of this article!

Forem: Gabriel Nordeborn

Practical uses for abstract types in ReScript

Tracking ID:s coming from an external API

Leveraging abstract types to control how values are used through your application

Hiding underlying values with abstract types

Accessing the underlying string of the ID:s

Wrapping up

ReScript, React and spread props - it's now possible!

Example of using props spreading in bindings - binding useFocus from react-aria

Setting up the bindings

Porting the example JavaScript code to ReScript

Wrapping up

Getting rid of your dead code in ReScript

Dead Code Analysis

Getting started

Examples from real life

Record fields that are never used

Variant cases that are never used

Unused parts of React state

Unnecessarily exposed functions in an interface file

Regular dead code

Unused React components

Living with the dead

@dead - when something is dead, but you intend to fix it

@live - when something is potentially dead but you want to keep it around regardless

Configuration of the analysis

analysis

suppress

unsuppress

transitive

Closing thoughts

Speeding up ReScript compilation using interface files

Modules and files

Implementation and interface files

So, how can interface files speed up compilation?

Compilation slows down because the compiler needs to derive the interface again and again

A good strategy for interface files

Editor tooling helps make life with interface files easier

Automatically generating an interface file from an implementation file

Switching between interface and implementation files

Wrapping up

Announcing Relay Meetup, a global, remote meetup for Relay, the GraphQL client

The time for Relay is now

Helping to grow the community

21st of October - our first meetup

Using Relay in production

Updating the cache after mutations

Get involved!

The magic of the Node interface

What is Global Object Identification?

What’s the Node interface anyway?

But why is it useful?

Why globally unique ids? Aren’t integers good enough?

What does this enable?

Autogeneration of pagination queries

Autogeneration of queries for your typical "Show more" functionality

Wrapping up

Pagination with minimal effort in Relay

How is pagination typically done in GraphQL clients?

Trying to re-use the original query isn't good enough

Pagination in Relay

The power of true modularity of components

Building the component that does the pagination

Relay let you define arguments for fragments

Relay writes your pagination query for you

Let Relay know where it can find your connection, and it’ll do the rest

How can this work?

Wrapping up

Connection based pagination in GraphQL

Standardization is the win

What is it and what is it suitable for?

A standardized structure for pagination

A common scenario of how pagination is implemented

Step 1. The “simplest possible pagination”

Step 2. How do we know if there are more results?

Step 3. When using offset break down

Step 4. Metadata relevant for each individual item in the search result

Wait - didn’t we just implement connection based pagination organically?

Templating removes decisions so you can focus on other stuff that sparks joy(tm)

Standardization == tooling can make your life much easier

Accessing the underlying `string` of the ID:s

Example of using props spreading in bindings - binding `useFocus` from `react-aria`

`analysis`

`suppress`

`unsuppress`

`transitive`

What’s the `Node` interface anyway?