Forem: Julian Garamendy

This post should appear on my blog automatically

Julian Garamendy — Thu, 04 Feb 2021 12:52:06 +0000

My personal site uses a Next.js Incremental Static Regeneration. Posts published on dev.to automatically appear on my blog.

The canonical_url for this post is https://juliangaramendy.dev/blog/cross-posting.

That page should contain the same article, as soon as it's published on dev.to, without re-deploying.

Here's how it works: Using Dev.to as CMS for my Next.js blog

Photo by Manki Kim on Unsplash.

Using Dev.to as CMS for my Next.js blog

Julian Garamendy — Sat, 23 Jan 2021 15:37:10 +0000

My Next.js site fetches my published articles using the dev.to API. It generates all pages at build time, and then individually again on every request. Also new articles can appear in my blog without having to build and deploy. Here's how it works.

I'll assume the reader is somewhat familiar with Data Fetching in Next.js.

There are 2 pages in my blog: one with a list of articles (/pages/blog.ts), and one for individual articles (/pages/[slug].ts) which uses dynamic routing.

For the full source code you can check this repository.

List of Articles

The blog.ts page exports a getStaticProps function. This fetches all of my articles from dev.to using the dev.to API. The list is then passed to the page component and rendered.

Filtering Articles

For some reason, I don't want ALL my published dev.to articles to be listed in my own blog.

Another "problem" to solve is slugs. Dev.to auto-generates slugs using the title and adding some random characters. On my own site I want to be able to choose my own slugs.

I found one solution that may solve both problems. By using the canonical_url frontmatter property to express that I want the article on my blog, and what the slug should be.

For every dev.to article I want to publish in my own blog I specify a cononical_url that starts with my own site url. For example: My blog post at https://dev.to/juliang/react-state-management-in-2020-3c58 has a canonical_url: https://juliangaramendy.dev/blog/react-state-management-2020.

After fetching the entire list, only the articles that are published and have a valid canonical_url pass the filter.

Another benefit is that dev.to will display a nice "Originally published at juliangaramendy.dev" message, with a link to the article on my site.

Article Page

For the individual articles the /[slug].ts page is generated. This module also exports a getStaticProps function that returns a single article, which is sent as props to the React component and rendered.

But I can't fetch the individual article from dev.to API because the slug is not the same. So it would not be found.

https://dev.to/juliang/	https://juliangaramendy.dev/blog/
react-state-management-in-2020-3c58	react-state-management-2020

What I do is: fetch the entire list again, find the article with a canonical_url property matching the slug parameter, and return it.

The /[slug].ts module also exports a getStaticPaths function that returns a list of slugs to be pre-generated at build time.

For this, I fetch the entire list again and return all the slugs.

export async function getStaticPaths() {
  const posts = await getAllPosts()
  const paths = posts.map((post) => ({ params: { slug: post.slug } }))
  return { paths, fallback: true }
}

I set fallback: true so that new articles that didn't exist at build time, can still be found on my blog when requested.

Regenerating article pages

When returning the static props I indicate that the page may be regenerated after 1 second using the revalidate property:

export async function getStaticProps(context) {
  const slug = context.params?.slug
  const post = await getPostBySlug(`${slug}`)
  return post ? { props: { post }, revalidate: 1 } : { notFound: true }
}

This makes use of Next.js Incremental Static Regeneration

Avoiding re-fetching every time

The above implementation is a bit naive.

The Next.js build process would call a function that fetches the entire list of articles multiple times in the span of a few seconds. This is both unnecessary and problematic, because the dev.to API has a usage limit.

Caching the network request in memory

A huge improvement is to wrap the fetch call in a static cache so that subsequent calls will be avoided and the cache returned instead.

The cache has to expire at some point, otherwise new articles may not be "picked up" by the blog. I set to to 1 minute, but may extend it to 10 minutes in the future. I'm sure people can wait 10 minutes to read my posts.

Here's one implementation.

// cache.ts

type CacheEntry = {
  expiresAt: number
  value: unknown
}

const cacheMap: Record<string, CacheEntry> = {}

const EXPIRATION = 1000 * 60 * 1 // 1 minute

export async function getCached<V>(key: string, fn: () => Promise<V>): Promise<V> {
  if (shouldRevalidate(key)) {
    await revalidateKey(key, fn)
  }
  return cacheMap[key].value as V
}

function shouldRevalidate(key: string): boolean {
  return cacheMap[key] ? new Date().getTime() > cacheMap[key].expiresAt : true
}

async function revalidateKey<V>(key: string, fn: () => Promise<V>) {
  const response = await fn()
  cacheMap[key] = {
    value: response,
    expiresAt: new Date().getTime() + EXPIRATION,
  }
  return cacheMap[key].value as V
}

We use it like this:

function fetchAllDevArticles(): Array<Article> {
  return fetch('https://dev.to/api/articles/me/published', { 
    headers: { 'api-key': process.env.DEVTO_API_KEY || '' },
  }).then((r) => r.json())
}

async function getAllDevArticles() {
  const articles = await getCached('dev.to/articles', fetchAllDevArticles)
  return articles.filter(article => !!article.canonical_url)
}

Every time we call getAllDevArticles we either fetch and get the response, or we get the cached value. The first time, of course the value is fetched, then the cache would be used a few times, then after the expiration time, the next request will be result in an API request again.

But this isn't good enough. In my experience this only works some times.

When I build locally on my computer, I can see 4 concurrent Node processes running. This results in 4 network requests and it's usually fine.

But when it's built on Vercel, there are usually 8 concurrent Node processes and the dev.to API fails with an error:

❌ 429 Too Many Requests

One way to solve this is by storing our cache on disk, so that more than one process can benefit from it.

Caching the network request on disk

This works because the Next.js build triggers one network request the first time and then it saves the response to disk.

The next time the request would be made, by any process, the disk cache will be tried first. If one exists and it has not expired, it will be used, otherwise the request will be made again and stored.

Here's one implementation:

import sha from 'sha-1'
import os from 'os'
import { join } from 'path'
import { readJsonFile, writeJsonFile } from './fs-read-write-json'

const getTempPath = (path: string) => join(os.tmpdir(), path)

type CacheEntry<V> =
  | {
      status: 'done'
      expiresAt: number
      value: V
    }
  | {
      status: 'pending'
      expiresAt: number
    }

export function getCached<V>(
  key: string,
  fn: () => Promise<V>,
  cacheDurationMs: number
) {
  const tempFilePath = getTempPath(`./jgdev-cache-${sha(key)}.json`)

  const getEntry = async () =>
    readJsonFile<CacheEntry<V> | undefined>(tempFilePath)

  const writePendingEntry = () =>
    writeJsonFile(tempFilePath, {
      status: 'pending',
      expiresAt: new Date().getTime() + 10000,
    })

  const writeEntry = async (value: V) =>
    writeJsonFile(tempFilePath, {
      status: 'done',
      expiresAt: new Date().getTime() + cacheDurationMs,
      value,
    })

  const wait = (t: number) => new Promise((resolve) => setTimeout(resolve, t))

  const revalidate = async (): Promise<V> => {
    await writePendingEntry()
    const value = await fn()
    await writeEntry(value)
    return value
  }

  const hasExpired = (entry: CacheEntry<V>) =>
    new Date().getTime() > entry.expiresAt

  const getValue = async (): Promise<V> => {
    const entry = await getEntry()
    if (entry) {
      if (entry.status === 'done' && !hasExpired(entry)) {
        return entry.value
      } else if (entry.status === 'pending' && !hasExpired(entry)) {
        await wait(500)
        return getValue()
      }
    }
    return revalidate()
  }

  return getValue()
}

Here's the read/write module if you're curious.

It's important to use the os.tmpdir(), if deploying on Vercel, because we can't write to the file system anywhere else.

❌ Error: EROFS: read-only file system

For the full source code you can check this repository.

Please, let me know what you think in the comments. I wonder if there's a library I could use to replace my cache module.

Photo by Fitore F on Unsplash

Persistent REST API with json-server and Glitch

Julian Garamendy — Mon, 31 Aug 2020 07:22:25 +0000

This is the easiest way I know to get a public persistent REST API up and running in under 1 minute, without writing any code.

We'll be using json-server by tipicode hosted on Glitch.

Step 1: Clone/Remix the demo project

Head over to Glitch.com and "remix" my json-server-demo.

Step 2: Use your own data

You can change db.json with your own json "database".

The one in the demo looks like this:

{
  "games": [
    {
      "id": 1,
      "title": "Frogger",
      "year": 1981
      ...
    },
    ...
  ]
}

Step 3: That's it!

While on the Glitch project, click on "Show in a new window", and you'll see the URL/endpoint of your REST API.

In the demo's db.json file, "games" becomes an entity that you can access like this:

GET    https://json-server-demo.glitch.me/games
POST   https://json-server-demo.glitch.me/games
PATCH  https://json-server-demo.glitch.me/games/1
DELETE https://json-server-demo.glitch.me/games/1

How it works

Glitch projects can run Node.js, but in our case we don't need to write a single line of code. We simply declare our dependency to json-server and our "start" script in the package.json file:

{
  ...
  "scripts": {
    "start": "json-server --watch ./db.json"
  },
  "dependencies": {
    "json-server": "^0.16.1"
  },
  ...
}

By default json-server reads and writes to the db.json file, so all changes made by POST, PATCH, PUT, DELETE http methods are persisted in "disk" in the Glitch project. See Do you have built-in persistence or a database? in the FAQ.

The answer is YES!

This means you can: Use files as a flat file database

Warning: Glitch Restrictions

Glitch "projects" seem to take some time to warm up or wake up, and the go back to sleep after a period of inactivity. For this reason I think this quick setup is good for demos or workshops, but not for production.

Please refer to the links below for more information:

Photo by coniferconifer on Wikimedia Commons

Why I never use React.useContext

Julian Garamendy — Mon, 17 Aug 2020 17:57:36 +0000

Instead of using React.createContext directly, we can use a utility function to ensure the component calling useContext is rendered within the correct Context Provider.

// JavaScript:
const [BananaProvider, useBanana] = createStrictContext()

// TypeScript:
const [BananaProvider, useBanana] = createStrictContext<Banana>()

Scroll down for the code, or find it in this gist.

The Problem

We would normally create a React Context like this:

const BananaContext = React.createContext()

// ... later ...

const banana = React.useContext(BananaContext) // banana may be undefined

Our banana will be undefined if our component doesn't have a BananaContext.Provider up in the tree.

This has some drawbacks:

Our component needs to check for undefined, or risk a run-time error at some point.
If banana is some data we need to render, we now need to render something else when it's undefined.
Basically, we cannot consider our banana an invariant within our component.

Adding a custom hook

I learned this from a blog post by Kent C. Dodds.

We can create a custom useBanana hook that asserts that the context is not undefined:

export function useBanana() {
  const context = React.useContext(BananaContext)
  if(context === undefined) {
    throw new Error('The useBanana hook must be used within a BananaContext.Provider')
  return context
}

If we use this, and never directly consume the BananaContext with useContext(BananaContext), we can ensure banana isn't undefined, because it if was, we would throw with the error message above.

We can make this even "safer" by never exporting the BananaContext. Exporting only its provider, like this:

export const BananaProvider = BananaContext.Provider

A generic solution

I used the previous approach for several months; writing a custom hook for each context in my app.

Until one day, I was looking through the source code of Chakra UI, and they have a utility function that is much better.

This is my version of it:

import React from 'react'

export function createStrictContext(options = {}) {
  const Context = React.createContext(undefined)
  Context.displayName = options.name // for DevTools

  function useContext() {
    const context = React.useContext(Context)
    if (context === undefined) {
      throw new Error(
        options.errorMessage || `${name || ''} Context Provider is missing`
      )
    }
    return context
  }

  return [Context.Provider, useContext]
}

This function returns a tuple with a provider and a custom hook. It's impossible to leak the Context, and therefore impossible to consume it directly, skipping the assertion.

We use it like this:

const [BananaProvider, useBanana] = createStrictContext()

Here's the TypeScript version:

import React from 'react'

export function createStrictContext<T>(
  options: {
    errorMessage?: string
    name?: string
  } = {}
) {
  const Context = React.createContext<T | undefined>(undefined)
  Context.displayName = options.name // for DevTools

  function useContext() {
    const context = React.useContext(Context)
    if (context === undefined) {
      throw new Error(
        options.errorMessage || `${name || ''} Context Provider is missing`
      )
    }
    return context
  }

  return [Context.Provider, useContext] as [React.Provider<T>, () => T]
}

We use it like this:

const [BananaProvider, useBanana] = createStrictContext<Banana>()

Conclusion

We can make errors appear earlier (unfortunately still at runtime) when we render a component outside the required Context Provider by using a custom hook that throws when the context is undefined.

Instead of using React.createContext directly, we use a utility function to create providers and hooks automatically for all the contexts in our app.

Comments?

Do you use a similar "pattern"? No? Why not?
In which cases would you NOT use something like this?

References:

How to use React Context effectively by Kent C. Dodds
Original utility function in the Chakra UI repo.
Gist with both JS and TS versions of the function
React Context Documentation

Photo by Engjell Gjepali on Unsplash

React State Management in 2020

Julian Garamendy — Sat, 01 Aug 2020 11:46:50 +0000

Every now and then I see a tweet poll asking what we do for state management in React. In many cases the options are constrained to Redux, MobX and more recently React Context + Hooks.

Of course the only correct answer is it depends.

But here's what I do for medium-sized CRUD-like single-page React applications.

I don't use any state-management library. (no Redux, no MobX, no Recoil).
I try to manage most of the application state with routes. This means having different URLs for different parts of the application, even if it's a single-page application. I use React Router for this.
I differentiate between application/UI state and remote data cache. and use SWR or React Query to keep a cache of remote data.
The rest tends to be small UI state "details" such as which modal popup is open, or the state of a form before submitting it. For this, I prefer to use useState or useReducer hooks, keeping state close to where it's used.

Application state in the URL

The application state must be kept somewhere. I can keep it hidden away in memory or I can expose it in the URL, so our users (and developers) can benefit from it.

Better UX: users can bookmark and share links and search results with others
Better DX: developers don't need to click around to get the app to a certain state every time they refresh the browser.
Better documentation: Help pages can point the user to the exact part of the application they describe.

I try to keep most of the application state in the URL, and I use React Router to handle the routes.

Remote Data is not state: it belongs in a cache

I cannot stress this enough. Fortunately other people can explain this better than me:

UI state should be separate from the server cache (often called "state" as well), and when you do that, you don't need anything more than React for state management.
Kent C. Dodds

Here's an excellent article: Why You Should Be Storing Remote Data in a Cache (and Not in State) by Jason Ankers.

"Remote data is read-only. It doesn’t belong in the same location as our UI state."

In CRUD-like web applications, where the server is authoritative, I don't want the client-side copy of the data to become stale.

Considering all this, in most cases I don't need to customise the way remote data is fetched and stored. I can delegate all that to a library like SWR or React Query.

These libraries store the fetched data in a static cache; and there’s no need to resort to React Context to "share" the data with other components because all components consuming the same data are automatically rerendered when the cache changes.

At work, earlier this year we refactored one of our SPAs to use SWR and the result was a much simpler application logic. In addition, we now benefit from all the nice features that come with SWR such as “focus revalidation” and “refetch on interval”. The app has been up and running for months and we haven't experienced any issues.

Local UI state should be co-located

Almost everything that isn't caught by the above cases is local UI state such as the visibility of modal dialogs or the fields in a form before it's submitted.

For these cases I prefer to keep the state close to where it's used. I usually find myself using useState and occasionally useReducer.

Comments?

I would love to hear your thoughts.

What do you do for state management?
Can you think of a common case that is not covered here?

References:

SWR by Vercel.
React Query by Tanner Linsley.
Why You Should Be Storing Remote Data in a Cache (and Not in State) by Jason Ankers.
State Management with React by Kent C. Dodds.
Lifting State Up. React Blog.
Colocation by Kent C. Dodds.
I first learned about SWR thanks to a video tutorial by Leigh Halliday: "React Data Fetching with Hooks using SWR".

Cover photo by Oshin Khandelwal on Unsplash

What Westworld and React Hooks have in common

Julian Garamendy — Sun, 26 Apr 2020 07:50:13 +0000

⚠️ Spoiler alert! If you haven't watched Westworld perhaps you may want to skip this post.

In the first season of Westworld androids are reset and their memories erased every time they "die" or after each "narrative cycle". Androids cannot take their memories with them (nor learn from them) for the next cycle. In a way they're stateless.

On episode 4 Maeve seems to malfunction and has memories from when the scientists fix her wounds and reset her every time. But this only lasts for one cycle and then she forgets again.

One day, after a daydreaming episode she draws her vision (a man in a hazmat suit) on a piece of paper and starts wondering where to keep the drawing. She suspects everything in her room is carefully reset every time.

She decides to hide the piece of paper under a loose floorboard. When she lifts the board she finds a lot of similar drawings that had been stored in there before.

That's basically React.useState.

Imagine a component with a text input. The user enters some data, but this is a pure function! where do we keep this data for the next time the function is run?

Under a floorboard.

const [drawings, setDrawings] = useFloorboard()

Managing Remote Data with SWR

Julian Garamendy — Thu, 27 Feb 2020 21:29:58 +0000

In this series, instead of using a state-management library or proposing a one-size-fits-all solution, we start from the bare minimum and we build up our state management as we need it.

In the first article we described how we load and display data with hooks.
In the second article we learned how to change remote data with hooks.
In the third article we learned how to share data between components with React Context, without using globals, singletons or resorting to state management libraries like MobX or Redux.
In this fourth article we'll see how to share data between using SWR, which is probably what we should have done from the beginning.

In the previous articles we were storing the loaded data within React, in a useState hook. But since then SWR was released (Oct 2019).

I first learned about SWR thanks to a video tutorial by Leigh Halliday: "React Data Fetching with Hooks using SWR", and I thought it was interesting enough that I could try it on a small internal project at work.

But a few weeks later a Twitter thread took me to this article; something clicked in my head and I realised I wasn't just looking for an excuse to try SWR.

No. I had been doing it wrong all along!

I was storing my remotely fetched data in useReducer or useState and manually mutating (or via a reducer), and then maybe reloading from the server in some cases, but not in others. And I was using React Context to make the data available to unrelated components in my app.

SWR makes this easier and better.

SWR stores the fetched data in a static cache. Therefore there's no need to use React Context to share the data with other components. And all components fetching the same data are updated when the data changes.

I refactored my SPA to use SWR and that resulted in a much simpler application logic. In addition, we now benefit from all the nice features that come with SWR such as "focus revalidation" and "refetch on interval".

Let's refactor our example from the previous three articles to use SWR.

Before SWR

Our demo app before SWR is what we got after our third article. (see repo)

Install SWR

yarn add swr

Refactoring our custom hook

In our demo app we have a custom useFetchedGames hook that loads the games using the useAsyncFunction hook, and then stores them using useState to provida a way to locally mutate the data.

const useFetchedGames = () => {
  const [fetchedGames, error, isPending] = useAsyncFunction(getGames, emptyList);

  const [games, setGames] = React.useState(emptyList);
  React.useEffect(() => {
    setGames(fetchedGames);
  }, [fetchedGames]);

  return { games, setGames, error, isPending };
};

The problem with this approach is:

The list of games is stored twice: first in a useState hook inside useAsyncFunction, and then in a new useState hook.
If the list of games is updated on the server, we never reload it. Here's where SWR shines.

We're going to refactor useFetchedGames to use SWR instead of useState.

const useFetchedGames = () => {
  const { data, error, mutate } = useSWR('getGames', getGames); 

  const games = data || []
  const isPending = !data
  const setGames = mutate

  return { games, setGames, error, isPending };
};

The full diff can be found in this git commit.

Note the "getGames" string literal, just before the getGames function. This is a key to help SWR identify our request. In our case it can be anything as long as it is unique for this resource (the list of games). There's a even simpler way. You can find it in the docs.

Removing React Context

Now that we're using useSWR we don't need a React context, its provider, nor the useContext hook.

In the demo project we make our components consume the useGames hook directly, instead of the useGamesContext one.

For example, GameGrid.tsx:

- import { useGamesContext } from '../GamesContext';
+ import { useGames } from '../useGames';

  export const GameGrid = () => {
-   const { games, error, isPending, markAsFinished } = useGamesContext();
+   const { games, error, isPending, markAsFinished } = useGames();

    return (
      <div className="gamegrid">

You can see the complete diff in this git commit.

Conclusion

With this small refactoring, our app has less code to maintain and we benefit from other great SWR features:

Revalidate on focus.
Revalidate on interval. (optional)
Revalidate on reconnect.
Retry on error.

I think Zeit's SWR (or a similar library) is a much better solution than storing fetched data in a React component using useState or useReducer.

I continue to store my application's UI state using custom hooks that use useReducer and useState but for remote data, I prefer to store it in a cache.

Please let me know what you think in the comments below.

How SWR works behind the scenes

Julian Garamendy — Mon, 24 Feb 2020 21:58:28 +0000

I first learned about SWR thanks to a video tutorial by Leigh Halliday: "React Data Fetching with Hooks using SWR". If you're not familiar with SWR, you can watch Leigh's video, read the official docs or find more on dev.to.

In this post we're going to build our own version of SWR, if only to understand how it works. But first a disclaimer:

⚠️ Warning!
This is is not production code. It's a simplified implementation and it doesn't include all the great features of SWR.

In previous blog posts I had written a useAsyncFunction hook to fetch data in React function components. That hook works not only with fetch, but with any function returning a promise.

Here's the hook:

type State<T> = { data?: T; error?: string }

export function useAsyncFunction<T>(asyncFunction: () => Promise<T>): State<T> {
  const [state, setState] = React.useState<State<T>>({})

  React.useEffect(() => {
    asyncFunction()
      .then(data => setState({ data, error: undefined }))
      .catch(error => setState({ data: undefined, error: error.toString() }))
  }, [asyncFunction])

  return state
}

If we pretend the fetchAllGames is a function returning a promise, here's how we use the hook:

function MyComponent() {
  const { data, error } = useAsyncFunction(fetchAllGames)
  // ...
}

SWR has a similar API, so let's start from this hook, and make changes as needed.

Changing data store

Instead of storing the data in React.useState we can store it in a static variable in the module scope, then we can remove the data property from our state:

const cache: Map<string, unknown> = new Map()

type State<T> = { error?: string }

Our cache is a Map because otherwise different consumers of the hook would overwrite the cache with their unrelated data.

This means we need to add a key parameter to the hook:

export function useAsyncFunction<T>(key: string, asyncFunction: () => Promise<T>) {
  ...
}

Next, we change what happens when the promise resolves:

asyncFunction()
  .then(data => {
    cache.set(key, data) // <<<<<<<<<<<<< setting cache here!
    setState({ error: undefined })
  })
  .catch(error => {
    setState({ error: error.toString() })
  })

Now our "state" is just the error, so we can simplify it. The custom hook now looks like this:

const cache: Map<string, unknown> = new Map()

export function useAsyncFunction<T>(
  key: string,
  asyncFunction: () => Promise<T>
) {
  const [error, setError] = React.useState<string | undefined>(undefined)

  React.useEffect(() => {
    asyncFunction()
      .then(data => {
        cache.set(key, data)
        setError(undefined)
      })
      .catch(error => setError(error.toString()))
  }, [key, asyncFunction])

  const data = cache.get(key) as T | undefined
  return { data, error }
}

Mutating local data

This works but it doesn't provide a mechanism to mutate the local data, or to reload it.

We can create a "mutate" method that will update the data in the cache, and we can expose it by adding it to the return object. We want to memoise it so that the function reference doesn't change on every render. (React docs on useCallback):

  ...
  const mutate = React.useCallback(
    (data: T) => void cache.set(key, data),
    [key]
  );
  return { data, error, mutate };
}

Next, in order to provide a "reload" function we extract the existing "load" implementation which is currently inside our useEffect's anonymous function:

React.useEffect(() => {
  asyncFunction()
    .then(data => {
      cache.set(key, data)
      setError(undefined)
    })
    .catch(error => setError(error.toString()))
}, [key, asyncFunction])

Again, we need to wrap the function in useCallback. (React docs on useCallback):

const load = React.useCallback(() => {
  asyncFunction()
    .then(data => {
      mutate(data); // <<<<<<< we call `mutate` instead of `cache.set`
      setError(undefined);
    })
    .catch(error => setError(error.toString()));
}, [asyncFunction, mutate]);

React.useEffect(load, [load]); // executes when the components mounts, and when props change

...

return { data, error, mutate, reload: load };

Almost there

The entire module now looks like this: (⚠️ but it doesn't work)

const cache: Map<string, unknown> = new Map()

export function useAsyncFunction<T>(
  key: string,
  asyncFunction: () => Promise<T>
) {
  const [error, setError] = React.useState<string | undefined>(undefined)

  const mutate = React.useCallback(
    (data: T) => void cache.set(key, data),
    [key]
  );

  const load = React.useCallback(() => {
    asyncFunction()
      .then(data => {
        mutate(data) 
        setError(undefined)
      })
      .catch(error => setError(error.toString()))
  }, [asyncFunction, mutate])

  React.useEffect(load, [load])

  const data = cache.get(key) as T | undefined
  return { data, error, mutate, reload: load }
}

⚠️ This doesn't work because the first time this executes, data is undefined. After that, the promise resolves and the cache is updated, but since we're not using useState, React doesn't re-render the component.

Shamelessly force-updating

Here's a quick hook to force-update our component.

function useForceUpdate() {
  const [, setState] = React.useState<number[]>([])
  return React.useCallback(() => setState([]), [setState])
}

We use it like this:

...
const forceUpdate = useForceUpdate();

const mutate = React.useCallback(
  (data: T) => {
    cache.set(key, data);
    forceUpdate(); // <<<<<<< calling forceUpdate after setting the cache!
  },
  [key, forceUpdate]
);
...

✅ And now it works! When the promise resolves and the cache is set, the component is force-updated and finally data points to the value in cache.

const data = cache.get(key) as T | undefined
return { data, error, mutate, reload: load }

Notifying other components

This works, but is not good enough.

When more than one React component use this hook, only the one that loads first, or the one that mutates local data gets re-rendered. The other components are not notified of any changes.

One of the benefits of SWR is that we don't need to setup a React Context to share the loaded data. How can we achieve this functionality?

Subscribing to cache updates

We move the cache object to a separate file because it will grow in complexity.

const cache: Map<string, unknown> = new Map();
const subscribers: Map<string, Function[]> = new Map();

export function getCache(key: string): unknown {
  return cache.get(key);
}
export function setCache(key: string, value: unknown) {
  cache.set(key, value);
  getSubscribers(key).forEach(cb => cb());
}

export function subscribe(key: string, callback: Function) {
  getSubscribers(key).push(callback);
}

export function unsubscribe(key: string, callback: Function) {
  const subs = getSubscribers(key);
  const index = subs.indexOf(callback);
  if (index >= 0) {
    subs.splice(index, 1);
  }
}

function getSubscribers(key: string) {
  if (!subscribers.has(key)) subscribers.set(key, []);
  return subscribers.get(key)!;
}

Note that we're not exporting the cache object directly anymore. In its place we have the getCache and setCache functions. But more importantly, we also export the subscribe and unsubscribe functions. These are for our components to subscribe to changes even if those were not initiated by them.

Let's update our custom hook to use these functions. First:

-cache.set(key, data);
+setCache(key, data);
...
-const data = cache.get(key) as T | undefined;
+const data = getCache(key) as T | undefined;

Then, in order to subscribe to changes we need a new useEffect:

React.useEffect(() =>{
  subscribe(key, forceUpdate);
  return () => unsubscribe(key, forceUpdate)
}, [key, forceUpdate])

Here we're subscribing to the cache for our specific key when the component mounts, and we unsubscribe when it unmounts (or if props change) in the returned cleanup function. (React docs on useEffect)

We can clean up our mutate function a bit. We don't need to call forceUpdate from it, because it's now being called as a result of setCache and the subscription:

  const mutate = React.useCallback(
    (data: T) => {
      setCache(key, data);
-     forceUpdate();
    },
-   [key, forceUpdate]
+   [key]
  );

Final version

Our custom hook now looks like this:

import { getCache, setCache, subscribe, unsubscribe } from './cache';

export function useAsyncFunction<T>(key: string, asyncFunction: () => Promise<T>) {
  const [error, setError] = React.useState<string | undefined>(undefined);
  const forceUpdate = useForceUpdate();

  const mutate = React.useCallback((data: T) => setCache(key, data), [key]);

  const load = React.useCallback(() => {
    asyncFunction()
      .then(data => {
        mutate(data);
        setError(undefined);
      })
      .catch(error => setError(error.toString()));
  }, [asyncFunction, mutate]);

  React.useEffect(load, [load]);

  React.useEffect(() =>{
    subscribe(key, forceUpdate);
    return () => unsubscribe(key, forceUpdate)
  }, [key, forceUpdate])

  const data = getCache(key) as T | undefined;
  return { data, error, mutate, reload: load };
}

function useForceUpdate() {
  const [, setState] = React.useState<number[]>([]);
  return React.useCallback(() => setState([]), [setState]);
}

This implementation is not meant to be used in production. It's a basic approximation to what SWR does, but it's lacking many of the great features of the library.

✅ Included	❌ Not included
Return cached value while fetching	Dedupe identical requests
Provide a (revalidate) reload function	Focus revalidation
Local mutation	Refetch on interval
	Scroll Position Recovery and Pagination
	Dependent Fetching
	Suspense

Conclusion

I think SWR (or react-query) is a much better solution than storing fetched data in a React component using useState or useReducer.

I continue to store my application state using custom hooks that use useReducer and useState but for remote data, I prefer to store it in a cache.

Photo by Umberto on Unsplash

Readonly and Better Error Messages

Julian Garamendy — Wed, 05 Feb 2020 15:55:19 +0000

A few weeks ago I learned something about TypeScript errors and utility types.

The following is true in TypeScript v3.7.5. In my experience, error messages in TS improve a lot with each release, so this may soon be irrelevant.

As usual, here's an example with bananas.

I had this Banana type:

type Banana = {
  id: number;
  name: string;
  color: number;
  weight?: number;
  length?: number;
  thumbnail?: string;
  pictures?: Array<string>;
};

I was trying to be clever and I thought I would make my type immutable by using the Readonly utility type like this:

type Banana = Readonly<{
  id: number;
  name: string;
  color: number;
  weight?: number;
  length?: number;
  thumbnails?: string;
  pictures?: ReadonlyArray<string>;
}>;

But this turned out not to be such a great idea.

I had made a (Readonly)Map with a few bananas:

const bananaMap: ReadonlyMap<number, Banana> = new Map([
  [1, { id: 1, name: "yellow banana", color: 0xffff00 }],
  [2, { id: 2, name: "red banana", color: 0xff0000 }],
  [3, { id: 3, name: "green banana", color: 0x00ff00 }]
]);

Then I tried to access an element in this way:

const banana: Banana = bananaMap.get(1);

And I got an error on the banana identifier which looked like this:

Type 'Readonly<{ id: number; name: string; color: number; weight?: number 
| undefined; length?: number | undefined; thumbnails?: string | undefined;
 pictures?: readonly string[] | undefined; }> | undefined' is not 
assignable to type 'Readonly<{ id: number; name: string; color: number; 
weight?: number | undefined; length?: number | undefined; thumbnails?: 
string | undefined; pictures?: readonly string[] | undefined; }>'.
  Type 'undefined' is not assignable to type 'Readonly<{ id: number; 
name: string; color: number; weight?: number | undefined; length?: 
number | undefined; thumbnails?: string | undefined; pictures?: 
readonly string[] | undefined; }>'.

It took me a while to understand what the problem was. The important part was on the second "paragraph" and I had to scroll down to find it, and still stare at it for a while.

You can see this example in the TypeScript Playground

So I changed the type, marking each field as readonly instead:

type Banana = {
  readonly id: number;
  readonly name: string;
  readonly color: number;
  readonly weight?: number;
  readonly length?: number;
  readonly thumbnails?: string;
  readonly pictures?: ReadonlyArray<string>;
};

Then the error message looked a bit better:

Type 'Banana | undefined' is not assignable to type 'Banana'.
  Type 'undefined' is not assignable to type 'Banana'.

And the issue was evident! The get method in the Map class returns an element or undefined. That means we can't annotate const banana with the Banana type.

const banana: Banana = bananaMap.get(1); // ❌ error!

Some possible fixes:

// 1
const banana: Banana | undefined = bananaMap.get(1); // ✅ no error

// 2
const banana: Banana = bananaMap.get(1)!; // ⚠️ no error, but (*)

* I would avoid the non-null assertion operator when possible.

You can see this new example in the TypeScript Playground.

UPDATE:

My friend Albert pointed our that we can get the "nice and short" error message mentioning out Banana type if we use interface instead of type:

interface Banana extends Readonly<{
  id: number;
  name: string;
  color: number;
  weight?: number;
  length?: number;
  thumbnails?: string;
  pictures?: ReadonlyArray<string>;
}> { }

You can see this last example in TypeScript Playground

I would love to hear what you use to declare immutability in your code.

Please comment!

Photo by v2osk on Unsplash

Sharing Remote Data with React Context

Julian Garamendy — Tue, 17 Sep 2019 14:32:38 +0000

In this series, instead of using a state-management library or proposing a one-size-fits-all solution, we start from the bare minimum and we build up our state management as we need it.

In the first article we described how we load and display data with hooks.
In the second article we learned how to change remote data with hooks.
In this third article we'll see how to share data between components with React Context, without using globals, singletons or resorting to state management libraries like MobX or Redux.
In the fourth article we'll see how to share data between components using SWR, which is probably what we should have done from the beginning.

The final code can be found in this GitHub repo. It's TypeScript, but the type annotations are minimal. Also, please note this is not production code. In order to focus on state management, many other aspects have not been considered (e.g. Dependency Inversion, testing or optimisations).

Sharing Remote Data with React Context

⚠️ Before we begin, you may want to check out this tag from the repo. The project has been improved from the last article with some styling and game screenshots.

Remember our list of games? There's a third requirement: We want to display a sign near the top of the page, indicating the total number of games, how many are finished and how many are in progress. Something like this:

Lifting State to a common ancestor

But first let's imagine our application is getting a bit more complex and we decide to break it into separate components. We'll create a GamesScreen and a GameGrid component.

App
 +- GamesScreen (useGames hook here)
         +- Totals
         +- GameGrid

Now our App component is not responsible for fetching the games list. We do that in GamesScreen.

export const App = () => {
  return (
    <>
      <h1>My Favourite Commodore 64 Games</h1>
      <GamesScreen />
    </>
  );
};

The new GamesScreen component uses our useGames custom hook to keep state and handle the error and pending states and eventually rendering two children components.

export const GamesScreen = () => {
  const { games, error, isPending, markAsFinished } = useGames();

  return (
    <>
      {error && <pre>ERROR! {error}...</pre>}
      {isPending && <pre>LOADING...</pre>}
      <Totals games={games} />
      <GameGrid games={games} markAsFinished={markAsFinished} />
    </>
  );
};

We extracted some code to a GameGrid compoent.

type GameGridProps = { games: Game[]; markAsFinished: (id: number) => void };

export const GameGrid = ({ games, markAsFinished }: GameGridProps) => {
  return (
    <div className="gamegrid">
      {games.map(game => (
        <GameComponent key={game.id} game={game} markAsFinished={markAsFinished} />
      ))}
    </div>
  );
};

And finally we can create a new Totals component:

type TotalsProps = { games: Game[] };

export const Totals = ({ games }: TotalsProps) => {
  const totalGames = games.length;
  const inProgress = games.filter(g => g.status === 'in-progress').length;
  const finished = games.filter(g => g.status === 'finished').length;

  return (
    <div className="card">
      total games: {totalGames}<br />
      in progress️: {inProgress}<br />
      finished: {finished}
    </div>
  );
};

The resulting code can be found in the repo under the 08-lifting-state tag.

Sharing State using hooks (the wrong way)

That's all we need to know if two sibling components need access to the same state.

But what if it we have a more complex component tree?

If the components sharing state are far apart, getting the required props to each of them may result in prop drilling. Let's imagine an even more complex structure:

App
 +- GamesScreen (useGames hook here)
     +- MenuBar❗
         +- SomeOtherMenuComponent ❗
             +- Totals (requires the list of games)
     +- GamesPageContent❗
         +- SomeOtherComponent❗
             +- GameGrid (requires the list of games and the markAsFinished function)

With the above structure we would need to keep the state in GamesScreen because it's the closest common ancestor of GameGrid and Totals.

The problem is that in order to pass the required props, MenuBar, SomeOtherMenuComponent, GamesPageContent and SomeOtherComponent would require props with the list of games and the markAsFinished function, only to pass it down to some children component.

We don't want to do that. We can use React Context to solve this problem.

Note: To keep the demo repository and this article simple we won't create any of those intermediate components marked with ❗️.

We're going to pretend that the GameGrid and Total components are far apart.

Our current GamesScreen.tsx

export const GamesScreen = () => {
  const { games, error, isPending, markAsFinished } = useGames(); ❌

  return (
    <>
      {error && <pre>ERROR! {error}...</pre>} ❌
      {isPending && <pre>LOADING...</pre>} ❌
      <Totals games={games} />
      <GameGrid games={games} markAsFinished={markAsFinished} />
    </>
  );
};

If Totals and GameGrid are far apart they don't share a common parent (only a common ancestor higher up in the tree). That means we can't call the useGames hook here and pass some props down without resorting to prop-drilling, as explained above.

For now we're going to call useGames inside each of our components:

Updated GamesScreen.tsx

export const GamesScreen = () => {
  return (
    <>
      <Totals />
      <GameGrid />
    </>
  );
};

Updated GameGrid.tsx

export const GameGrid = () => {
  const { games, error, isPending, markAsFinished } = useGames();

  return (
    <div className="gamegrid">
      {error && <pre>ERROR! {error}...</pre>}
      {isPending && <pre>LOADING...</pre>}
      {games.map(game => (
        <GameComponent key={game.id} game={game} markAsFinished={markAsFinished} />
      ))}
    </div>
  );
};

The updated GameGrid component does not receive any props, but now it has to handle the error and pending states itself.

Updated Totals.tsx

export const Totals = () => {
  const { games } = useGames();

  const totalGames = games.length;
  const inProgress = games.filter(g => g.status === 'in-progress').length;
  const finished = games.filter(g => g.status === 'finished').length;

  return (
    <div className="card">
      total games: {totalGames}
      <br />
      in progress️: {inProgress}
      <br />
      finished: {finished}
    </div>
  );
};

In the Totals component we only use {games} from the custom hook, because we don't need markAsFinished function and we don't worry about error and pending states for this small component.

You can inspect the code from the repo using the 09-duplicating-state tag.

Wait wasn't this about React Context?

The above code works because both components now access the same server API and request the same list of games. Twice. However, when we mark some games as finished, only the GameGrid component reflects this. The Totals component is not updated.

For example, after marking two games as finished, the GameGrid component shows them as finished, as expected, but the Totals component continues to report zero finished games.

This is why we need to fetch and update only one list of games.

Sharing state using React Context (the right way)

OK. Let's see how we do this with React Context.

We're going to update our GamesScreen component.

export const GamesScreen = () => {
  return (
    <GamesContextProvider>
      <Totals />
      <GameGrid />
    </GamesContextProvider>
  );
};

Instead of wrapping Totals and GameGrid in a fragment <>, we wrap them in a new GamesContextProvider component which we'll create next.

GamesContext.tsx

type GamesContext = ReturnType<typeof useGames>;

export const gamesContext = React.createContext<GamesContext>({
  games: [],
  error: null,
  isPending: true,
  markAsFinished: () => {}
});

export const GamesContextProvider: React.FC = ({ children }) => {
  return <gamesContext.Provider value={useGames()}>{children}</gamesContext.Provider>;
};

For more information see Using React Context and React Hooks Reference: useContext.

This is the simplest thing we could do. Then we update our GameGrid and Totals components to use the context like this:

import { gamesContext } from '../GamesContext';

export const GameGrid = () => {
//const { games, error, isPending, markAsFinished } = useGames();
  const { games, error, isPending, markAsFinished } = React.useContext(gamesContext);

But there's a problem. If we forget to wrap this component in GamesContextProvider or if someone in the future accidentally removes it, there won't be any errors. The list of games will never be loaded, and the context will never change its value.

You can try it. Check out the 10-minimal-context tag and edit GamesScreen.tsx removing the context provider to see that the games never load.

A better approach is to use undefined as a default value for our context.

type GamesContext = ReturnType<typeof useGames>;

const gamesContext = React.createContext<GamesContext | undefined>(undefined);

export const useGamesContext = (): GamesContext => {
  const context = React.useContext(gamesContext);
  if (!context) {
    throw new Error(
      'useGameContext must be used in a component within a GameContextProvider.'
    );
  }
  return context;
};

We also create a custom useGamesContext hook that throws if the context is undefined, which can only happen if the provider is missing.

import { useGamesContext } from '../GamesContext';

export const GameGrid = () => {
//const { games, error, isPending, markAsFinished } = React.useContext(gamesContext);
  const { games, error, isPending, markAsFinished } = useGamesContext();

We do the same in the Totals component.

import { useGamesContext } from '../GamesContext';

export const Totals = () => {
//const { games } = React.useContext(gamesContext);
  const { games } = useGamesContext();

That's it! The final version of code can be found in the 11-safe-context tag.

Conclusion

We have managed to share state in our aplication without making it global and without suffering from prop drilling. Any component requiring access to the games list can use the custom hook provided. This hooks exposes a function to mutate such data in a safe way, while immediately persisting it on the server according to our business logic.

Resources

Changing Remote Data with Hooks

Julian Garamendy — Tue, 17 Sep 2019 14:31:53 +0000

In this series, instead of using a state-management library or proposing a one-size-fits-all solution, we start from the bare minimum and we build up our state management as we need it.

In the first article we described how we load and display data with hooks.
In this second article we'll learn how to change remote data with hooks.
In the third article we'll see how to share data between components with React Context without using globals, singletons or resorting to state management libraries like MobX or Redux.
In the fourth article we'll see how to share data between components using SWR, which is probably what we should have done from the beginning.

Changing Remote Data with Hooks

We have our list of games from the previous article. Now there's a new requirement: We want to let the user mark each game as "finished". When they do, we send the changes to the server right away.

In order to change the value of "status" from "in-progress" to "finished" we make a PATCH request:

const setGameStatus = (id: number, status: Game['status']): Promise<Game> => {
  return fetch('http://localhost:3001/games/' + id, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ status: status })
    })
    .then(response => response.json());
}

Which we can use like this:

const promise = setGameStatus(7, "finished");

But, where do we put this code?

We can approach the problem from the other end: How would we like to use our hook?

Let's create a GameComponent to render a single game with an onClick handler to mark it as finished.

Note: To keep this simple we'll make a quick <pre> with everything in it, including the onClick handler.

type GameComponentProps = { game: Game; markAsFinished: (id:number) => void };

const GameComponent = ({ game, markAsFinished }: GameComponentProps) => {
  return (
    <pre onClick={() => markAsFinished(game.id)}>
      Title: {game.title}
      Year: {game.year}
      Status: {game.status}
    </pre>
  );
};

This new component needs a game object and a markAsFinished function. So our custom hook should return a function along with the list of games, error and pending:

//const { games, error, isPending } = useGames();
  const { games, error, isPending, markAsFinished } = useGames();

This would allow us to render the list of games like this:

export const App = () => {
  const { games, error, isPending, markAsFinished } = useGames();

  return (
    <>
      {error && <pre>ERROR! {error}...</pre>}
      {isPending && <pre>LOADING...</pre>}
      <ol>
        {games.map(game => (
          <li key={game.id}>
            <GameComponent game={game} markAsFinished={markAsFinished} />
          </li>
        ))}
      </ol>
    </>
  );
};

That's what we would like to use. Let's change our useGames hook implementation.

Here's what it looks like so far:

export const useGames = () => {
  const [games, error, isPending] = useAsyncFunction(getGames, emptyList);
  return { games, error, isPending };
};

We need to return a markAsFinished function.

export const useGames = () => {
  const [games, error, isPending] = useAsyncFunction(getGames, emptyList);

  const markAsFinished = (id: number) => {
    setGameStatus(id, 'finished'); // setGameStatus is already defined outside the hook
  };

  return { games, error, isPending, markAsFinished };
};

With this code (see repo) we are now sending our changes to the server, but unless we reload the page and fetch the list of games again, our client-side data is not affected.

Updating client-side data

Now the server has the updated value, but the client does not: The list is not updated after a change.

const markAsFinished = (id: number) => {
  setGameStatus(id, 'finished')
    .then(game => ?????); // 🤔
};

Our server's PATCH request returns a promise with the modified game object which we can use to update our client-side list. There's no need to re-fetch the list of games or even the affected game after "patching".

const markAsFinished = (id: number) => {
  setGameStatus(id, 'finished')
    .then(updateGame); // 🤔 we need to define updateGame
};

Our updateGame function will make a copy of the array of games, find the game by id and replace it with the new one.

export const useGames = () => {
  const [games, error, isPending] = useAsyncFunction(getGames, emptyList);

  const updateGame = (game: Game) => {
    const index = games.findIndex(g => g.id === game.id);
    if (index >= 0) {
      const gamesCopy = games.slice();
      gamesCopy[index] = game;
      setGames(gamesCopy); // 🤔 I don't see setGames declared anywhere...
    }
  }
  const markAsFinished = (id: number) => {
    setGameStatus(id, 'finished').then(updateGame);
  };

  return { games, error, isPending, markAsFinished };
};

Oh! We don't have a setGames function. Our useAsyncFunction does not provide a way to set the value externally. But we don't want to modify it because in a real world project we'd probably replace its functionality with react-async.

We can change our useGames custom hook to keep state, and update it whenever the fetchedGames change (or when we call setGames, of course).

export const useGames = () => {
  const [fetchedGames, error, isPending] = useAsyncFunction(getGames, emptyList);

  const [games, setGames] = React.useState(emptyList); // 😎 now we have setGames!
  React.useEffect(() => {
    setGames(fetchedGames);
  }, [fetchedGames]);

  ...

Our useGame hook file now looks like this (see the entire file in the repo)

export const useGames = () => {
  const [fetchedGames, error, isPending] = useAsyncFunction(getGames, emptyList);

  const [games, setGames] = React.useState(emptyList);
  React.useEffect(() => {
    setGames(fetchedGames);
  }, [fetchedGames]);

  const updateGame = (game: Game) => {
    const index = games.findIndex(g => g.id === game.id);
    if (index >= 0) {
      const gamesCopy = games.slice();
      gamesCopy[index] = game;
      setGames(gamesCopy);
    }
  };
  const markAsFinished = (id: number) => {
    setGameStatus(id, 'finished').then(updateGame);
  };

  return { games, error, isPending, markAsFinished };
};

Refactoring

That looks a bit messy. We can extract it to a custom hook:

const useFetchedGames = () => {
  const [fetchedGames, error, isPending] = useAsyncFunction(getGames, emptyList);

  const [games, setGames] = React.useState(emptyList);
  React.useEffect(() => {
    setGames(fetchedGames);
  }, [fetchedGames]);

  return {games, setGames, error, isPending};
}

export const useGames = () => {
  const { games, error, isPending, setGames } = useFetchedGames();
    ...
}

(see the entire file in the repo)

Handling errors

❌ 404 Not Found

Just like before, we've forgotten about handling errors. What happens when the PATCH request fails?

First of all, we have two functions calling the server but only one (getGames) checks the status code of the response.

const getGames = (): Promise<Game[]> => {
  return fetch('http://localhost:3001/games/').then(response => {
    if (response.status !== 200) {
      throw new Error(`${response.status} ${response.statusText}`);
    }
    return response.json();
  });
};

export const setGameStatus = (id: number, status: Game['status']): Promise<Game> => {
  return fetch('http://localhost:3001/games/' + id, {
    method: 'PATCH',
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ status: status })
  }).then(response => response.json()); // 😰 no error handling
};

We don't want to repeat ourselves so we'll extract the error handling to a new function and use it in both cases.

function parseResponse<T>(response: Response): Promise<T> {
  if (response.status !== 200) {
    throw new Error(`${response.status} ${response.statusText}`);
  }
  return response.json();
}

export const getGames = (): Promise<Game[]> => {
  return fetch('http://localhost:3001/games/').then(response =>
    parseResponse(response)
  );
};

export const setGameStatus = (id: number, status: Game['status']): Promise<Game> => {
  return fetch('http://localhost:3001/games/' + id, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: status })
  }).then(response => parseResponse(response));
};

To keep things tidy, we move these functions to a new gameClientAPI.ts file (see repo). Our useGames hook imports the functions from it. We're separating concerns and keep our files short.

Now we can catch errors from markAsFinished:

const markAsFinished = (id: number) => {
  setGameStatus(id, 'finished')
    .then(updateGame)
    .catch(error =>
      alert(
        `There was a problem updating this game.\n` +
          `Please try again later.\n\n` +
          `(${error.toString()})`
      )
    );
};

(see repo)

Conclusion

We have successfully wrapped an imperative API in a more declarative API in the form of a custom React hook so it can be used in React function components. When a component needs to access the list of games and make changes to it, it can simply import the useGames hook.

What's next?

This is fine as long as the data is used by only one component. There is no need to have a global(ish) store, or use Redux or MobX. But if more than one component require access to the same data, we should "lift" it to a common ancestor component.

In cases where that common ancestor is not directly the parent of the consimung components, we can avoid prop-drilling by using React Context.

We'll see how we do that in the next article of this series.

Resources

Loading and Displaying Data with Hooks

Julian Garamendy — Tue, 17 Sep 2019 14:31:06 +0000

In this series, instead of using a state-management library or proposing a one-size-fits-all solution, we start from the bare minimum and we build up our state management as we need it.

In this first article we'll describe how we load and display data with hooks.
In the second article we'll learn how to change remote data with hooks.
In the third article we'll see how to share data between components with React Context without using globals, singletons or resorting to state management libraries like MobX or Redux.
In the fourth article we'll see how to share data between components using SWR, which is probably what we should have done from the beginning.

Loading Data with Hooks

Let's say we have a REST API with a list of Commodore 64 games. I mean, why not?

Requirement: We want to load the list and display the games.

1. Basic Fetching

Here's how we retrieve our list of games from the server:

const getGames = () => {
  return fetch('http://localhost:3001/games/').then(response => response.json());
};

We can use this in a React app. Our first iteration looks like this:

App.tsx (rendered by index.tsx) (see repo)

import React from 'react';

const getGames = () => {
  return fetch('http://localhost:3001/games/').then(response => response.json());
};

export const App = () => {
  const [games, setGames] = React.useState([]);

  React.useEffect(() => {
    getGames().then(games => setGames(games));
  }, []);

  return <pre>{JSON.stringify(games, null, 2)}</pre>;
};

On the first render of our App component, the games array will be empty. Then when the promise returned by getGames resolves, the games array contains all our games, and they will be displayed in a very basic manner.

2. Custom React Hook

We can easily extract this to a custom React Hook in a separate file.

useGames.ts (see repo)

import React from 'react';

const getGames = () => {
  return fetch('http://localhost:3001/games/').then(response => response.json());
};

export const useGames = () => {
  const [games, setGames] = React.useState([]);

  React.useEffect(() => {
    getGames().then(games => setGames(games));
  }, []);

  return games;
};

App.tsx (see repo)

import React from 'react';
import { useGames } from './useGames';

export const App = () => {
  const games = useGames();
  return <pre>{JSON.stringify(games, null, 2)}</pre>;
};

3. Handling errors and pending state

Our custom hook is not handling pending and error states. There is no visual feedback while the data is loading from the server, and even worse: there's no error message when it fails. If the server is down, the list of games will remain empty, without errors.

We can fix this. There are libraries for this, the most popular being react-async; but I don't want to add dependencies just yet. Let's see what's the minimum code needed to handle the error and pending states.

useAsyncFunction

We write a custom hook that takes an async function (which returns a Promise) and a default value.

This hook returns a tuple with 3 elements: [value, error, isPending]. It calls the async function once*, and it updates the value when it resolves, unless there's an error, of course.

function useAsyncFunction<T>(asyncFunction: () => Promise<T>, defaultValue: T) {
  const [state, setState] = React.useState({
    value: defaultValue,
    error: null,
    isPending: true
  });

  React.useEffect(() => {
    asyncFunction()
      .then(value => setState({ value, error: null, isPending: false }))
      .catch(error => setState({ ...state, error: error.toString(), isPending: false }));
  }, [asyncFunction]); // *

  const { value, error, isPending } = state;
  return [value, error, isPending];
}

* The useEffect inside our useAsyncFunction will call the async function once and then every time the asyncFunction changes. For more details: Using the State Hook, Using the Effect Hook, Hooks API Reference.

Now in useGames.ts we can simply use this new custom hook, passing the getGames function and the initial value of an empty array as arguments.

...
export const useGames = () => {
  const games = useAsyncFunction(getGames, []); // 🤔 new array on every render?
  return games;
};

There's a small problem, though. We're passing a new empty array every time useGames is called, which is every time our App component renders. This causes our data to be re-fetched on every render, but each fetch results in a new render so it results in an infinite loop.

We can avoid this by storing the initial value in a constant outside the hook:

...
const emptyList = [];

export const useGames = () => {
  const [games] = useAsyncFunction(getGames, emptyList);
  return games;
};

Small TypeScript Interlude

You can skip this section if you're using plain JavaScript.

If you're using strict TypeScript, the above code will not work because of the "noImplicitAny" compiler option. This is because const emptyList = []; is implicitly an array of any.

We can annotate it like const emptyList: any[] = []; and move on. But we're using TypeScript for a reason. That explicit any can (and should) be more specific.

What are the elements of this list? Games! It's a list of games.

const emptyList: Game[] = [];

Of course, now we have to define a Game type. But do not despair! We have our JSON response from the server where each game object looks like this:

{
  "id": 5,
  "title": "Kung-Fu Master",
  "year": 1984,
  "genre": "beat'em up",
  "url": "https://en.wikipedia.org/wiki/Kung-Fu_Master_(video_game)",
  "status": "in-progress",
  "img": "http://localhost:3001/img/kung-fu-master.gif"
}

We can use transform.tools to convert that to a TypeScript interface (or type).

type Game = {
  id: number;
  title: string;
  year: number;
  genre: string;
  url: string;
  status: 'not-started' | 'in-progress' | 'finished';
  img: string;
};

One more thing:

We said useAsyncFunction returned a tuple, but TypeScript's inference (@3.6.2) does not understand that. It inferes the return type as Array<(boolean | Game[] | null)>. We can explicitly annotate the return type of the function to be [T, string | null, boolean] where T is the (generic) type of the value, (string | null) is the type of the error and boolean is isPending.

export function useAsyncFunction<T>(
  asyncFunction: () => Promise<T>,
  defaultValue: T
): [T, string | null, boolean] {
  ...
}

Now when we use the function, TypeScript suggests the proper types.

const [games] = useAsyncFunction(getGames, emptyList); // games is of type Game[]

End of TypeScript interlude.

Composing our custom hooks

useAsyncFunction.ts now looks like this: (see repo)

import React from 'react';

export function useAsyncFunction<T>(
  asyncFunction: () => Promise<T>,
  defaultValue: T
): [T, string | null, boolean] {
  const [state, setState] = React.useState({
    value: defaultValue,
    error: null,
    isPending: true
  });

  React.useEffect(() => {
    asyncFunction()
      .then(value => setState({ value, error: null, isPending: false }))
      .catch(error =>
        setState({ value: defaultValue, error: error.toString(), isPending: false })
      );
  }, [asyncFunction, defaultValue]);

  const { value, error, isPending } = state;
  return [value, error, isPending];
}

And we use it in our useGames hook:

useGames.ts (see repo)

import { useAsyncFunction } from './useAsyncFunction';

const getGames = (): Promise<Game[]> => {
  return fetch('http://localhost:3001/games/').then(response => response.json());
};

type Game = {
  id: number;
  title: string;
  year: number;
  genre: string;
  url: string;
  status: 'not-started' | 'in-progress' | 'finished';
  img: string;
};

const emptyList: Game[] = [];

export const useGames = () => {
  const [games] = useAsyncFunction(getGames, emptyList);
  return games;
};

Changing UI to display errors and pending states

Great! But we're stil not handling the error and pending states. We need to change our App component:

import React from 'react';
import { useGames } from './useGames';

export const App = () => {
  const { games, error, isPending } = useGames();

  return (
    <>
      {error && <pre>ERROR! {error}...</pre>}
      {isPending && <pre>LOADING...</pre>}
      <pre>{JSON.stringify(games, null, 2)}</pre>
    </>
  );
};

And our useGames hook should return an object with three keys: games, error, isPending.

export const useGames = () => {
  const [games, error, isPending] = useAsyncFunction(getGames, emptyList);
  return { games, error, isPending };
};

We're also improving our getGames function to handle HTTP status codes different from 200 as errors:

const getGames = (): Promise<Game[]> => {
  return fetch('http://localhost:3001/games/').then(response => {
    if (response.status !== 200) {
      throw new Error(`${response.status} ${response.statusText}`);
    }
    return response.json();
  });
};

Our code so far looks like this: (see repo).

Conclusion

We've seen how to load data from a REST API using React hooks.

In the next article we'll see how to change remote data using an HTTP PATCH request, and how to update our client-side data when the request is successful.