Posts on Building Better Software Slower

Components Are Just Sparkling Hooks

Mon, 10 Mar 2025 00:00:00 +0000

Here’s a question you might encounter while interviewing for React developer roles:

“What is the difference between a component and a hook?”

The answer that the interviewer is likely looking for is along the lines of “A component is a building block for the UI, and hooks are utility functions for managing state and side-effects 😴”.

It’s a satisfactory answer if your goal is to find employment. But if you want to make an impression, the more daring answer is: “There is no difference 🔥”.

Disclaimer: Daring answers to simple questions is an unwise strategy on screening rounds.

First, What is a Component?

The very technical answer is that it is a function that returns a ReactNode, which is anything that makes sense to render on-screen (including JSX, strings, numbers, nulls, and so on).

Below is a valid React component:

const MyComponent = () => {
  return "Hello World!";
};

Components can render dynamic inputs using props…

const MyComponent = ({ name, onClick }) => {
  return <button onClick={onClick}>Hello {name}!</button>;
};

…and implement stateful behaviors using hooks.

const MyCounter = () => {
  const [count, increment] = useReducer((state) => state + 1, 0);

  return <button onClick={increment}>Counter {count}</button>;
};

From there, the sky is the limit!

const MyFancyCounter = () => {
  const [count, increment] = useReducer((state) => state + 1, 0);

  // Add fancy styles every time `count` doubles
  const fancyClass = useMemo(() => {
    const orderOfMagnitude = Math.floor(Math.log2(count));

    if (orderOfMagnitude <= 0) return "";

    switch (orderOfMagnitude) {
      case 1:
        return "fancy-1";
      case 2:
        return "fancy-2";
      case 3:
        return "fancy-3";
      default:
        // Beyond 255
        return "fanciest";
    }
  }, [count]);

  return (
    <button onClick={increment} className={fancyClass}>
      Counter {count}
    </button>
  );
};

No matter what we do in the implementation, we can use it as a black box in another component by mixing it into the JSX.

const FancyCounterApp = () => {
  return (
    <div>
      <h1>My Counter App</h1>
      <MyFancyCounter />
    </div>
  );
};

Second, What are Hooks?

Hooks are React built-in functions to manage state and effects. You can create new hooks by wrapping the React-provided hooks in a function.

Hooks can accept any input and return any value. The only restrictions are the rules of hooks, which dictate that hooks must not be called conditionally. Critically, those rules are transitive, meaning that anything that calls a hook is a hook itself and must follow those rules until it is used in a component.

This is where we get to the crux of the story: given that Components transitively inherit all restrictions of hooks (rules of hooks), and are more restrictive in their output (can only return ReactNodes): Components are indeed a subtype of hooks. Any component can be used as a hook!

Case in point, our most complex component from earlier can become a hook effortlessly:

// It's prefixed by `use` now, its a hook!
const useFancyCounter = () => {
  const [count, increment] = useReducer((state) => state + 1, 0);

  // Add fancy styles every time `count` doubles
  const fancyClass = useMemo(() => {
    const orderOfMagnitude = Math.floor(Math.log2(count));

    if (orderOfMagnitude <= 0) return "";

    switch (orderOfMagnitude) {
      case 1:
        return "fancy-1";
      case 2:
        return "fancy-2";
      case 3:
        return "fancy-3";
      default:
        // Beyond 255
        return "fanciest";
    }
  }, [count]);

  return (
    <button onClick={increment} className={fancyClass}>
      Counter {count}
    </button>
  );
};

const FancyCounterApp = () => {
  const myFancyCounter = useFancyCounter();
  return (
    <div>
      <h1>My Counter App</h1>
      {myFancyCounter}
    </div>
  );
};

So far, this might seem like uninteresting semantics, but there is a practical side to this exercise.

Headless Components

As previously noted, the distinguishing trait of a component is that it returns a ReactNode. For API purposes, the ReactNode is a black box. Since useFancyCounter() still returns a ReactNode, its internal state is opaque and not consumable.

The limitation matters because it prevents FancyCounterApp from easily implementing features such as:

rendering the {count} outside of the <button>
extending button styling
adding another button to increment the count by two
performing some event once the count reaches 10

Since useFancyCounter is a hook, instead of returning a ReactNode, it can expose its event handlers and state, which FancyCounterApp can leverage into a more flexible output.

// It's prefixed by `use` now, its a hook!
const useFancyCounter = () => {
  const [count, increment] = useReducer((state) => state + 1, 0);

  // Add fancy styles every time `count` doubles
  const fancyClass = useMemo(() => {
    const orderOfMagnitude = Math.floor(Math.log2(count));

    if (orderOfMagnitude <= 0) return "";

    switch (orderOfMagnitude) {
      case 1:
        return "fancy-1";
      case 2:
        return "fancy-2";
      case 3:
        return "fancy-3";
      default:
        // Beyond 255
        return "fanciest";
    }
  }, [count]);

  return { fancyClass, increment, count };
};

useFancyCounter is now a headless component because it implements all Component-adjacent functionality (event handling, state management, styling) but allows its caller to distill it into JSX instead of returning a pre-baked ReactNode.

Headless Components are hooks that implement component-level logic

The flexibility of this pattern is unparalleled, with none of the boilerplate that a composition-based solution would’ve brought.

const FancyCounterApp = () => {
  const { fancyClass, increment, count } = useFancyCounter();

  // performing some event once the count reaches 10
  useEffect(() => {
    if (count === 10) {
      showFireworks();
    }
  }, [count]);

  return (
    <div>
      <h1>My Counter App</h1>
      {/* rendering the `{count}` outside of the `<button>` */}
      <h2>Count is at {count}</h2>
      <button
        onClick={increment}
        // extend button styling
        className={clsx(fancyClass, "some-other-class")}
      >
        Increment by 1
      </button>
      {/* adding another button to increment the count by two */}
      <button
        onClick={() => {
          increment();
          increment();
        }}
      >
        Increment by 2
      </button>
    </div>
  );
};

Unit Testing

Headless components effectively decouple the view from the view model, making them testable individually.

// Testing full component
describe("FancyCounterApp", () => {
  it("increments", () => {
    render(<FancyCounterApp />);

    const incrementBtn = screen.findByLabel("Increment by 1");

    fireEvent.click(incrementBtn);
    fireEvent.click(incrementBtn);
    fireEvent.click(incrementBtn);

    expect("Count is at 3").toBeInDocument();
  });
});

// Testing component logic only
describe("useFancyCounter", () => {
  it("increments", () => {
    const { result } = renderHook(() => useFancyCounter());

    act(() => result.current.increment());
    act(() => result.current.increment());
    act(() => result.current.increment());

    expect(result.current.count).toBe(3);
  });
});

Composition + Headless Components

While headless components often solve the same kind of challenges as composition, the two patterns are compatible (the implementation of the new components is left as an exercise to the reader):

const FancyCounterApp = () => {
  return (
    <FancyCounter.Context value={useFancyCounter()}>
      <FancyCounter.Fireworks at={10} />
      <div>
        <h1>My Counter App</h1>
        <h2>
          Count is at <FancyCounter.Count />
        </h2>
        <FancyCounter.IncrementBtn by={1}>
          Increment by 1
        </FancyCounter.IncrementBtn>
        <FancyCounter.IncrementBtn by={2}>
          Increment by 2
        </FancyCounter.IncrementBtn>
      </div>
    </FancyCounterContext>
  );
};

This combined pattern is helpful if you want inversion of control while keeping the controller as an individual unit. The added benefit is the ability to reuse view-model logic between components that use context and those that don’t.

Go Deeper: A future article will be covering advanced composition patterns. Subscribe to the BBSS newsletter to be the first to read it!

State of the Art

A few real-world libraries implement headless components (see: jxom/awesome-react-headless-components).

Some implement headless components exactly as described, using hooks and pushing them to their full potential (see: React Aria):

// https://react-spectrum.adobe.com/react-aria/useMenu.html#menubutton
function MenuButton<T extends object>(props: MenuButtonProps<T>) {
  // Create state based on the incoming props
  let state = useMenuTriggerState(props);

  // Get props for the button and menu elements
  let ref = React.useRef(null);
  let { menuTriggerProps, menuProps } = useMenuTrigger<T>({}, state, ref);

  return (
    <>
      <Button
        {...menuTriggerProps}
        buttonRef={ref}
        style={{ height: 30, fontSize: 14 }}
      >
        {props.label}
        <span aria-hidden="true" style={{ paddingLeft: 5 }}>
          ▼
        </span>
      </Button>
      {state.isOpen && (
        <Popover state={state} triggerRef={ref} placement="bottom start">
          <Menu {...props} {...menuProps} />
        </Popover>
      )}
    </>
  );
}

Others treat “headless” as a synonym for “unstyled”, and instead expose their state through through children callbacks (see: Headless UI):

// https://headlessui.com/react/menu#using-render-props
function Example() {
  return (
    <Menu>
      <MenuButton as={Fragment}>
        {({ active }) => (
          <button className={clsx(active && "bg-blue-200")}>My account</button>
        )}
      </MenuButton>
      <MenuItems anchor="bottom">
        {links.map((link) => (
          <MenuItem key={link.href} as={Fragment}>
            {({ focus }) => (
              <a
                className={clsx("block", focus && "bg-blue-100")}
                href={link.href}
              >
                {link.label}
              </a>
            )}
          </MenuItem>
        ))}
      </MenuItems>
    </Menu>
  );
}

The above is different because a UI component’s “head” is a renderable chunk. An unstyled ReactNode is convenient for some purposes but does not address the same challenges as a hook-based headless component.

Conclusion

It is easy to overlook the idea that components and hooks are not separate concepts, as they are always presented as distinct primitives.

Once accepted, headless components emerge as an obvious pattern that enables greater logic reusability, flexibility, and superior testing patterns.

If you enjoyed this article, you might also enjoy diving into the previous React article: Learning Suspense by Building a Suspense-Enabled Library.

Default Audio Input (or Output) Device for MacOS

Sun, 29 Dec 2024 16:18:43 -0500

As a recent Apple convert, I enjoy a lot about Macbooks. My main gripe, however, is that anything I don’t appreciate is often difficult-to-impossible to fix to my liking.

A particular pain point for me has been around my wireless headphones (Sony WH-1000XM4, by the way) which come with a mediocre microphone built-in.

Usually, I wouldn’t care about a suboptimal headset microphone because the Macbook Pro microphone is perfectly fine for my needs. My ideal solution has previously been disabling the headset microphone at the operating system level. On Windows and Linux, this is usually a few clicks away.

Disable microphone on Windows via sound settings

On MacOS? No such equivalent. There is no way to set a default or preference order either.

MacOS generally prefers to switch to whatever input (or output) was most recently connected, and there is no way to configure that behavior. Ugh!

From my searches to find a way to tweak it to my liking (i.e. prefer the laptop’s microphone over the headset microphone), it seems like I’m far from alone.

I’ve come away unsatisfied by every solution I’ve found so far, so I ended up coming up with my own.

brew install switchaudio-osx

As expected, there is a solution for managing input/output devices from the CLI. I figured that I could use it to watch the selected input device and switch it to the MacBook’s microphone whenever my headset’s microphone is selected.

SwitchAudioSource provides a solution for both parts of the problem quite elegantly!

To follow along, install it via

brew install switchaudio-osx

Next, take a look at the available input devices. You should see some familiar names:

SwitchAudioSource -t input -a

# Output:
# Slava’s iPhone Microphone
# WH-1000XM4
# MacBook Pro Microphone
# Default microphone

The next two pieces of the puzzle will check the selected input device and update it conditionally. It looks like this as a one-liner:

# Switch to the built-in Microphone if the headset is selected as the input
[[ `SwitchAudioSource -t input -c` = "WH-1000XM4" ]] && \
    SwitchAudioSource -t input -s "MacBook Pro Microphone"

Behold the power of the CLI

Given that we can observe the command working well, we can wrap it in an infinite loop and throw it into an sh file.

#!/bin/sh

while true;
do
 [[ `/opt/homebrew/bin/SwitchAudioSource -t input -c` = "WH-1000XM4" ]] && \
 /opt/homebrew/bin/SwitchAudioSource -t input -s "MacBook Pro Microphone" || \
 sleep 1;
done

Now with an infinite loop. ^C to exit.

Registering a Service (Agent)

Of course, the entire point of this exercise is convenience. Running a bash script in your terminal is not it. MacOS has an init service called launchd which allows us to run programs in the background on startup.

First, put the script file in /usr/local/bin/no-xm4-input-service.sh. Feel free to use another name, but pay attention to the references.

Make sure it has the right permissions:

sudo chown root:wheel /usr/local/bin/no-xm4-input-service.sh
sudo chmod 755 /usr/local/bin/no-xm4-input-service.sh

Next, create a service file in ~/Library/LaunchAgents. I called mine localhost.no-xm4-input.plist.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>localhost.no-xm4-input</string>
        <key>Program</key>
        <string>/usr/local/bin/no-xm4-input-service.sh</string>
        <key>RunAtLoad</key>
        <true/>
    </dict>
</plist>

Applying the correct permissions here is important, or else launchd will refuse to register the service:

sudo chown root:wheel ./localhost.no-xm4-input.plist
sudo chmod 640 ./localhost.no-xm4-input.plist

Lastly, you can register it to launchd via the following commands:

launchctl load ./localhost.no-xm4-input.plist
launchctl start localhost.no-xm4-input

You can confirm that it is running correctly via launchctl list, the second number is the status code. It should be 0:

launchctl list | grep localhost.no-xm4-input
# Output:
# 73035	0	localhost.no-xm4-input

It should also appear in your system settings

Go Further

Our service is extremely simple: a loop with a sleep. It doesn’t matter much in this case, but it’s not an ideal design. If you want to go further, consider that there is a small set of specific events that SwitchAudioSource could be invoked in response to.

It’s possible to turn the service into something more event-driven. I suspect there might be interesting challenges here (mainly race conditions), which I didn’t want to spend time figuring out.

Learn Suspense by Building a Suspense-Enabled Library

Sat, 06 Jul 2024 20:41:00 -0400

Suspense (along with concurrent rendering) has been a feature in React since v16.6.0. Despite this, I haven’t seen much of it in action beyond React.lazy and limited applications of “suspense-enabled libraries”.

What’s going on?

As of the impending React v19 release, Suspense is still not quite ready for primetime. The story of its APIs and internals still seems incomplete. In fact, the React team seems to think it’s so incomplete that the Suspense API is entirely undocumented. The Suspense documentation insists that the only way of using Suspense is via “Suspense-enabled frameworks”.

I think that purposefully hiding APIs in documentation is silly, but fine! I’ll play their game! Let’s build a Suspense-enabled library, and use it.

We will peel back the curtain of Suspense along the way.

The Philosophy

Before jumping straight into Suspense, let’s build a simple data-fetching component to see where we are without it.

If you take a React 101 course, it will generally teach you to write code like this when fetching data:

const Artist = ({ artistName }) => {
    const [artistInfo, setArtistInfo] = useState(null)
    
    useEffect(() => {
        fetch(`https://api/artists/${artistName}`)
            .then(res => res.json())
            .then(json => setArtistInfo(json))
    }, [artistName])

    return (
        <div>
            <h2>{artistName}</h2>
            <p>{artistInfo.bio}</p>
        </div>
    )
}

The next thing that course will teach you is that this code is actually bad. It’s missing a bunch of things like:

Error state handling
Pending state handling
Race condition handling
Shared caching (this will be covered later)

Once implemented, our component looks more like this:

const Artist = ({ artistName }) => {
    const [artistInfo, setArtistInfo] = useState(null)
    const [error, setError] = useState(null)
    const [isPending, setIsPending] = useState(false)

    useEffect(() => {
        let stale = false
        setIsPending(true)
        setError(null)

        fetch(`https://api/artists/${artistName}`)
            .then(res => res.json())
            .then(json => {
                if (!stale) {
                    setIsPending(false)
                    setArtistInfo(json)
                }
            })
            .catch(err => setError(err))

        // This is basically what AbortController does
        return () => { stale = true }
    }, [artistName])

    if (isPending) return <SpinnerFallback />
    if (error !== null) return <ErrorFallback />

    return (
        <div>
            <h2>{artistName}</h2>
            <p>{artistInfo?.bio}</p>
        </div>
    )
}

At this point, the course instructor will usually tell you that this is good, but you’re bound to be repeating this code every time you need to fetch data, and will then proceed to teach you about writing your first hook.

While I respect the pedagogical needs, that is actually not the best way to approach it. The problem with tracking pending and error states is that even if you bury it in a hook, you will still need to handle those states at the component level.

const Artist = ({ artistName }) => {
    const [artistInfo, isPending, error] = useFetch(`https://api/artists/${artistName}`)

    // This isn't much, but you will need to do this every time
    if (isPending) return <SpinnerFallback />
    if (error !== null) return <ErrorFallback />

    return (
        <div>
            <h2>{artistName}</h2>
            <p>{artistInfo.bio}</p>
            <Album albumName={artistInfo.lastAlbumName}>
        </div>
    )
}

const Album = ({ albumName }) => {
     const [albumInfo, isPending, error] = useFetch(`https://api/artists/${albumName}`)

    // This isn't much, but you will need to do this every time
    if (isPending) return <SpinnerFallback />
    if (error !== null) return <ErrorFallback />

    return ...
}

Imagine if useFetch could handle returning SpinnerFallback and ErrorFallback for us.

In the case of ErrorFallback, we have error boundaries:

const Artist = ({ artistName }) => {
    const [artistInfo, isPending, error] = useFetch(`https://api/artists/${artistName}`)

    if (isPending) return <SpinnerFallback />
    // Handle at the nearest error boundary (you can move this into useFetch)
    if (error !== null) return throw error

    return (
        <div>
            <h2>{artistName}</h2>
            <p>{artistInfo.bio}</p>
            <Album albumName={artistInfo.lastAlbumName}>
        </div>
    )
}

const App = () => {
    return (
        <ErrorBoundary fallback={<ErrorFallback />}>
            <Artist artistName="Julian Casablanca" />
        </ErrorBoundary>
    )
}

As for SpinnerFallback, that is actually what Suspense is for. We’ll eschew the implementation that triggers the fallback mechanism to avoid distractions (we’ll come back to it later, don’t worry!), but it looks like this from the component perspective:

const Artist = ({ artistName }) => {
    // Wow! Our hook implicitly handles both errors, and loading states now!
    const [artistInfo] = useFetch(`https://api/artists/${artistName}`)

    return (
        <div>
            <h2>{artistName}</h2>
            <p>{artistInfo.bio}</p>
            <Album albumName={artistInfo.lastAlbumName}>
        </div>
    )
}

const App = () => {
    return (
        <ErrorBoundary fallback={<ErrorFallback />}>
            <Suspense fallback={<SpinnerFallback />}>
                <Artist artistName="Julian Casablanca" />
            </Supense>
        </ErrorBoundary>
    )
}

At this point, don’t dwell on how useFetch is implemented. We have a long way to go before it’s usable.

Beware: Boundaries Reset State

A side-effect of using boundaries for handling pending and error states is that when a boundary is hit, all its children are discarded in favor of the fallback. The result is that their state is lost.

const Counter = () => {
    // All state will be reset once an error boundary is hit
    const [count, setCount] = useState(0)
    const [error, setError] = useState<null | Error>(null)

    // trigger error boundary
    if (error) throw error

    const increment = () => setCount((n) => n + 1)
    return (
        <div>
            <p>Counter: {count}</p>
            <button onClick={increment}>Increment</button>
            <button onClick={() => {
                    // To trigger an error boundary, an error MUST be
                    // thrown during the render cycle.
                    // Throwing an error in an event handler or effect
                    // will not trigger an error boundary!
                    setError(new Error("Whoops something went wrong!"))
                }}
            >Throw Error</button>
        </div>
    )
}

Try it out:

This is often desirable. For example, if your component entered a bad state, the surest way of getting it out is a complete reset.

Tip: by strategically placing your boundaries, you can control which parts of your application are reset together.
Remember that you can wrap more than just your root, but you also don’t need to wrap every single component.
This is true for both error boundaries and suspense boundaries.

In terms of tracking pending states, this poses a challenge. On the initial render, the state is pending. This will trigger the Suspense boundary. If the Suspense boundary is reset, then the component will remount, send a new request, and trigger the boundary again. As such, successfully displaying data is not possible under such a paradigm without having a continuous reference to the same request.

Correction: A nuance of Suspense boundaries is that they will only reset state for initial renders (i.e.: they will prevent the initial render). Subsequent renders have the component are merely temporarily hidden from the DOM and preserve their state. CodeSandbox for proof.

A cache that lives longer than the component lifetime is necessary.

Building a Shared Cache

Shared caching is important. It’s essential to avoid out-of-sync data, sending too many requests, and implementing advanced data management features. In our case, it’s also critical to make components dumber, and not responsible for managing the state of their requests, which would otherwise be lost.

Caching is hard to do right. In truth, it’s hard enough that data-fetching libraries are mostly caching libraries.

We’ll avoid going down the “how to write a cache” rabbit hole by keeping our cache intentionally simplistic. Its API will allow us to request a specific URL from it, and it will give us back values for data, pending, and error just like before. The only difference will be that the request lifecycle will be managed within the cache – not within the component making the request.

We will then turn the cache into a real Suspense-enabled library.

FetchCache Class

You can get creative with the exact APIs, and features your cache has. Here’s a minimal implementation:

class FetchCache {
    // Container for all-things-requests
    requestMap = new Map()

    // Tracking callbacks for broadcasting state updates
    subscribers = new Set()

    fetchUrl(url, refetch) {
        const currentData = this.requestMap.get(url)

        if (currentData) {
            // This request is already in flight. 
            if (currentData.status === 'pending') 
                return currentData
            // If data is already in cache and has not been 
            // explicitly re-requested. Return it.
            // status is either fulfilled or rejected.
            if (!refetch) return currentData
        }

        // Set status to pending to avoid competing requests
        const pendingState = { status: 'pending' }
        this.requestMap.set(url, pendingState)

        const broadcastUpdate = () => {
            // Delay notification in order to not run
            // during render cycle
            // https://reactjs.org/link/setstate-in-render
            setTimeout(() => {
                for (const callback of this.subscribers) {
                    callback()
                }
            }, 0)
        }
        
        // Dispatch request and observe it
        fetch(url)
            .then(res => res.json())
            .then(data => {
                // Put success state into cache
                this.requestMap.set(url, { status: 'fulfilled', value: data })
            })
            .catch(error => {
                // Put error state into cache
                this.requestMap.set(url, { status: 'rejected', reason: error })
            })
            .finally(() => {
                // Whatever happens, notify subscribers 
                // that state should be refreshed
                broadcastUpdate()
            })

        // Report that a request is now pending
        broadcastUpdate()

        // Report that a request is now pending
        return pendingState
    }

    subscribe(callback) {
        this.subscribers.add(callback)
        return () => this.subscribers.delete(callback)
    }
}

This FetchCache has 2 methods:

fetchUrl(url, refetch)

Request a URL.
Returns its current state in the cache.

subscribe(callback)

FetchCache Provider

Now that we have a cache, we require the means to expose it to our React tree: a Context Provider.

const fetchCacheContext = createContext(null)

const FetchCacheProvider = ({ children, fetchCache }) => {
    // This state hook is only used to trigger re-renders
    const [,setEmptyState] = useState({})
    const rerender = useCallback(() => setEmptyState({}), [])

    // Effect to register subscriber onto fetchCache
    useEffect(() => {
        const unsubscribe = fetchCache.subscribe(() => rerender())
        return unsubscribe
    }, [fetchCache, rerender])

    return (
        <fetchCacheContext.Provider value={{
            // Pop quiz: why is `bind` necessary here?
            fetchUrl: fetchCache.fetchUrl.bind(fetchCache)
        }}>
            {children}
        </fetchCacheContext.Provider>
    )
}

useFetch Hook

Lastly, we will write a useFetch hook to leverage the FetchCacheProvider:

const useFetch = (url) => {
    const { fetchUrl } = useContext(fetchCacheContext)
    const state = fetchUrl(url)
    const isPending = state.status === 'pending'
    const error = state.reason
    const data = state.value
    
    // Allow refreshing data
    const reload = () => fetchUrl(url, true)

    return [data, isPending, error, reload]
}

Note that we’re keeping the API consistent with our initial example.

In Action!

This demo uses Users and Posts instead of Artists and Albums. Powered by https://jsonplaceholder.typicode.com

Try clicking the Refresh buttons and see what happens. Break the URLs to make the request purposefully fail.

Feel free to explore the codebase, and make sure you have a good understanding of what’s going on until we continue. Re-read previous sections if something doesn’t make sense.

Tracking Data as Promises

So far, we’ve been consistently using promises without thinking too much about them. Remember that Promises have 3 possible states:

Pending
Fulfilled with value (where value could also be undefined or null)
Rejected with reason (where the reason is typically an Error, but doesn’t need to be)

In principle, we don’t need to track this information separately from the Promise, as we do in FetchCache. We could just track the promise by itself while using a special function to read information from it.

The challenge here is that Promises only allow for asynchronous data access (even if they are already settled):

// Created settled promise
const promise = Promise.resolve()
console.log("1")
promise.then(() => {
  console.log("3")
})
console.log("2")

// Outputs: 
1
2
3

We need a way to read its state synchronously to extract the data. We can do this by adding extra properties to the Promise object to track its state.

function readPromiseState(promise) {
    switch (promise.status) {
        case 'pending':
            return { status: 'pending' }
        case 'fulfilled':
            return { status: 'fulfilled', value: promise.value }
        case 'rejected':
            return { status: 'rejected', reason: promise.reason }
        default:
            promise.status = 'pending'
            promise.then(value => {
                promise.status = 'fulfilled'
                promise.value = value
            })
            promise.catch(reason => {
                promise.status = 'rejected'
                promise.reason = reason
            })
            return readPromiseState(promise)
    }
}

The first time we call readPromiseState with a Promise, it will return pending. But once it settles, it will update its own state in a way that is accessible to us.

Try in your REPL of choice:

> const promise1 = Promise.resolve("Hello World!")
> readPromiseState(promise1)
{ status: 'pending' }
> readPromiseState(promise1)
{ status: 'fulfilled', value: 'Hello World!' }

> const promise2 = Promise.reject(new Error("Whoops!"))
> readPromiseState(promise2)
{ status: 'pending' }
> readPromiseState(promise2)
{ status: 'rejected', reason: [Error: Whoops!] }

> const promise3 = new Promise(res => setTimeout(res, 5000))
> readPromiseState(promise3)
{ status: 'pending' }
> readPromiseState(promise3)
{ status: 'pending' }
> readPromiseState(promise3)
{ status: 'pending' }
> readPromiseState(promise3)
{ status: 'fulfilled', value: undefined }

Spoiler: You might think that this is improper, but this is exactly what React v19’s use does under the hood.

Using Promises in the Cache

In this section, we will lightly modify our FetchCache to track Promises using readPromiseState instead of state objects. The changes are fairly light.

class FetchCache {
    // Container for all-things-requests
    requestMap = new Map()

    // Tracking callbacks for broadcasting state updates
    subscribers = new Set()

    fetchUrl(url, refetch) {
        const currentData = this.requestMap.get(url)

        if (currentData) {
            // This request is already in flight. 
            if (readPromiseState(currentData).status === 'pending') 
                return readPromiseState(currentData)
            // If data is already in cache and has not been 
            // explicitly re-requested. Return it.
            // status is either fulfilled or rejected.
            if (!refetch) return readPromiseState(currentData)
        }

        

        const broadcastUpdate = () => {
            // Delay notification in order to not run
            // during render cycle
            // https://reactjs.org/link/setstate-in-render
            setTimeout(() => {
                for (const callback of this.subscribers) {
                    callback()
                }
            }, 0)
        }
        
        // Dispatch request and observe it
        const newPromise = fetch(url)
            .then(res => res.json())


        newPromise.finally(() => {
            // Whatever happens, notify subscribers 
            // that state should be refreshed
            broadcastUpdate()
        })

        this.requestMap.set(url, newPromise)

        // Report that a request is now pending
        broadcastUpdate()

        // Report that a request is now pending
        return readPromiseState(newPromise)
    }

    subscribe(callback) {
        this.subscribers.add(callback)
        return () => this.subscribers.delete(callback)
    }
}

You can paste it into your fork of the previous CodeSandbox to see that no other changes are necessary. This demonstrates that we have all the data we need in the Promise itself.

We will now make one more change, where instead of using readPromiseState in the FetchCache, we will move to the useFetch hook.

class FetchCache {
    // Container for all-things-requests
    requestMap = new Map()

    // Tracking callbacks for broadcasting state updates
    subscribers = new Set()

    fetchUrl(url, refetch) {
        const currentData = this.requestMap.get(url)

        if (currentData) {
            // This request is already in flight. 
            // We need to keep this `readPromiseState` check
            if (readPromiseState(currentData.status) === 'pending') 
                return currentData
            // If data is already in cache and has not been 
            // explicitly re-requested. Return it.
            // status is either fulfilled or rejected.
            if (!refetch) return currentData
        }

        

        const broadcastUpdate = () => {
            // Delay notification in order to not run
            // during render cycle
            // https://reactjs.org/link/setstate-in-render
            setTimeout(() => {
                for (const callback of this.subscribers) {
                    callback()
                }
            }, 0)
        }
        
        // Dispatch request and observe it
        const newPromise = fetch(url)
            .then(res => res.json())


        newPromise.finally(() => {
            // Whatever happens, notify subscribers 
            // that state should be refreshed
            broadcastUpdate()
        })

        this.requestMap.set(url, newPromise)

        // Report that a request is now pending
        broadcastUpdate()

        // Report that a request is now pending
        return newPromise
    }

    subscribe(callback) {
        this.subscribers.add(callback)
        return () => this.subscribers.delete(callback)
    }
}

const useFetch = (url) => {
    const { fetchUrl } = useContext(fetchCacheContext)
    const state = readPromiseState(fetchUrl(url))
    const isPending = state.status === 'pending'
    const error = state.reason
    const data = state.value
    
    // Allow refreshing data
    const reload = () => fetchUrl(url, true)

    return [data, isPending, error, reload]
}

Enable Suspense 🎉

The final change we’re going to make is to turn useFetch into a Suspense hook.

Remember how we would trigger the error boundary by throwing an Error? Triggering a Suspense boundary is the same, except you throw a Promise.

To escape an error boundary, you need to have some code that makes the call to reset it. The Suspense boundary on the other hand will automatically reset itself when the Promise is resolved (or will trigger an error boundary if it’s rejected).

Enabling Suspense for useFetch will require 2 changes.

First, it will need to throw the Promise if it’s pending.

Second, it will need to throw the reason (which is an Error) if the Promise is rejected.

If the Promise has been fulfilled, it can simply return the data. The consuming component no longer needs to consider error or pending states.

const useFetch = (url) => {
  const { fetchUrl } = useContext(fetchCacheContext)
  const promise = fetchUrl(url)
  const state = readPromiseState(promise)

  // Throw pending promise
  const isPending = state.status === "pending"
  if (isPending) throw promise

  // Throw rejection reason
  const error = state.reason
  if (error) throw error

  const data = state.value

  // Allow refreshing data
  const reload = () => fetchUrl(url, true)

  // Only return data now
  return [data, reload]
}

Next, update the components that use useFetch to consume the data directly…

export const User = ({ userId }) => {
  const [data, reload] = useFetch(
    `https://jsonplaceholder.typicode.com/users/${userId}`
  );
// ...

…and wrap the application in a Suspense and ErrorBoundary.

function App() {
    return (
        <div className="App">
            <FetchCacheProvider fetchCache={fetchCache}>
                <ErrorBoundary fallback={<ErrorFallback />}>
                    <Suspense fallback={<Spinner />}>
                        <h1>My App</h1>
                        <User userId={1} />
                    </Suspense>
                </ErrorBoundary>
            </FetchCacheProvider>
        </div>
    )
}

A best practice here is to always wrap your application root in both ErrorBoundary and Suspense. Remember to be mindful that anything contained in either of them will have their local state reset when the boundary is triggered.

Try it on the CodeSandbox:

Exercise for the reader: This time, when you click the refresh buttons, the entire app turns into a loading state. Why is this, and how can you restore the previous behavior?
Hint: throwing an error or a promise triggers the nearest boundary.

Whoops. We Just Re-Invented `use()`!

React v19 is introducing a new hook: use. It can consume data from a context (similar to useContext) or a Promise. Let’s see what it looks like when we introduce use to useFetch:

const useFetch = (url) => {
  const { fetchUrl } = useContext(fetchCacheContext)
  const promise = fetchUrl(url)

  // Handles throwing for pending and rejected promises
  const data = use(promise)

  // Allow refreshing data
  const reload = () => fetchUrl(url, true)

  // Only return data now
  return [data, reload]
}

Neat!

Review

In this post, we have learned:

How Suspense helps with writing shorter component functions
How to persist state when a boundary is triggered
How to read from a Promise “synchronously”
How to write a “Suspense-enabled” hook
What the use() hook does to Promises

Ending Notes

Congratulations on finishing reading! If you followed along, you should now have the knowledge needed to build your own Suspense-enabled hooks. More importantly, you should now feel empowered in debugging Suspense when things go wrong.

While some of the implementations featured in the post might seem awkward; everything is broadly representative of how real Suspense-enabled libraries work.

For example, if you look at TanStack Query, the mappings should be pretty clear:

useQuery -> useFetch
QueryClient -> FetchCache
QueryClientProvider -> FetchCacheProvider

The practical differences are in the features available.

FetchCacheProvider Implementation

While we used a global instance of FetchCache for persisting the fetch states, it could’ve been a locally initialized instance within the context, as long as it was outside the Suspense and Error boundaries, which would otherwise reset it:

const FetchCacheProvider = ({ children }) => {
    const [fetchCache] = useState(() => new FetchCache())
    // This state hook is only used to trigger re-renders
    const [,setEmptyState] = useState({})
    const rerender = useCallback(() => setEmptyState({}), [])

    // Effect to register subscriber onto fetchCache
    useEffect(() => {
        const unsubscribe = fetchCache.subscribe(() => rerender())
        return unsubscribe
    }, [fetchCache, rerender])

    return (
        <fetchCacheContext.Provider value={{
            // Pop quiz: why is `bind` necessary here?
            fetchUrl: fetchCache.fetchUrl.bind(fetchCache)
        }}>
            {children}
        </fetchCacheContext.Provider>
    )
}

This implementation of the provider would’ve worked just as well. It is, however, bad practice.

Writing the FetchCacheProvider in this way creates a tight coupling between it and the specific FetchCache implementation. In turn, this makes FetchCacheProvider unable to accept alternative implementations that use a different fetching mechanism (Axios, GraphQL, mocks for unit tests, etc).

What is missing from Suspense?

Render-level caching is something that the React team has previously alluded to delivering. The idea is that we could cache data (like Promises) within some internal React context, which would survive state resets.

This could allow Suspense implementations based on “local” state, that doesn’t require a context or global cache. It’s still a moving target in terms of implementation, so there’s not much else to say.

Aside from that, Suspense API seems pretty complete to me. I don’t understand the React team’s aversion to documenting it.

Transitions

I won’t be going into specifics in this post, but the documentation is pretty good as far as Suspense-Transition interactions go. If you’re building on Suspense, that page is mandatory reading.

Especially with the upcoming v19 changes, there is much more to useTransition than just Suspense. I’ll be covering the hook in its entirety in a future post after the official v19 release.

Subscribe to the newsletter to be the first to the complete guide to useTransition.

Understanding React Concurrency

Sat, 20 May 2023 00:00:00 +0000

React v18.0 has broken ground by introducing a long-awaited feature: Concurrency!

Unfortunately, despite a deluge of resources explaining how to use it, explanations of how it works are sparse.

As it is a low-level feature, it’s not critical to understand React’s idea of concurrency, but it doesn’t hurt!

This post does not attempt to exhaustively document React’s Concurrent API and best practices. It is best read alongside React’s documentation pages which are linked throughout.

What is React Concurrency?

The basic premise of React concurrency is to re-work the rendering process such that while rendering the next view, the current view is kept responsive.

Concurrent Mode was a proposal the React team had to improve application performance. The idea was to break up the rendering process into interruptible units of work.

Under the hood, this would be implemented by wrapping component renders in a requestIdleCallback() call, keeping applications responsive during the rendering process.

So hypothetically, if Blocking Mode were implemented like this:

function renderBlocking(Component) {
    for (let Child of Component) {
        renderBlocking(Child);
    }
}

Then Concurrent Mode would be implemented like this:

function renderConcurrent(Component) {
    // Interrupt rendering process if state out-dated
    if (isCancelled) return;

    for (let Child of Component) {
        // Wait until browser isn't busy (no inputs to process)
        requestIdleCallback(() => renderConcurrent(Child));
    }
}

Read the Practical Guide To Not Blocking The Event Loop to understand why this keeps the application responsive!

If you’re curious how React does this in reality, take a peek at the implementation of React’s scheduler package. After initially using requestIdleCallback, React switched to requestAnimationFrame, and later to a user-space timer.

No Mode, Only Features

The Concurrent Mode plan did not materialize for backward-compatibility reasons.

Instead, the React team pivoted to Concurrent Features, a set of new APIs selectively enabling concurrent rendering. So far, React has introduced two new hooks to opt into a concurrent render.

`useTransition`

The useTransition hook returns two items:

Boolean flag isPending, which is true if a concurrent render is in progress
Function startTransition, which dispatches a new concurrent render

To use it, wrap setState calls in a startTransition callback.

function MyCounter() {
    const [isPending, startTransition] = useTransition();
    const [count, setCount] = useState(0);
    const increment = useCallback(() => {
        startTransition(() => {
            // Run this update concurrently
            setCount(count => count + 1);
        });
    }, []);
 
    return (
        <>
            <button onClick={increment}>Count {count}</button>
            <span>{isPending ? "Pending" : "Not Pending"}</span>
            // Component which benefits from concurrency
            <ManySlowComponents count={count} />
        </>
    )
}

Try it out:

Conceptually, state updates detect if they are wrapped in a startTransition to decide whether to schedule a blocking or concurrent render.

function startTransition(stateUpdates) {
  isInsideTransition = true;
  stateUpdates();
  isInsideTransition = false;
}

function setState() {
  if (isInsideTransition) {
    // Schedule concurrent render
  } else {
    // Schedule blocking render
  }
}

An important caveat of useTransition is that it cannot be used for controlled inputs. For those cases, it is best to use useDeferredValue.

`useDeferredValue`

The useDeferredValue hook is a convenient hook for cases where you do not have the opportunity to wrap the state update in startTransition but still wish to run the update concurrently.

An example of where this occurs is child components receiving a new value from the parent.

Conceptually, useDeferredValue is a debounce effect and can be implemented as such:

function useDeferredValue<T>(value: T) {
    const [isPending, startTransition] = useTransition();
    const [state, setState] = useState(value);
    useEffect(() => {
        // Dispatch concurrent render
        // when input changes
        startTransition(() => {
            setState(value);
        });
    }, [value])

    return state;
}

It is used the same way as an input debounce hook:

function Child({ value }) {
    const deferredValue = useDeferredValue(value);
    // ...
}

Concurrent Features & Suspense

The useTransition and useDeferredValue hooks have a purpose beyond opting in concurrent rendering: they also wait for Suspense components to complete.

A future post will cover the topic of Suspense and their roles in it. Subscribe to the newsletter to be the first to read it.

In the meantime, you can learn the basic principles of Suspense by reading a newer BBSS post: Learn Suspense by Building a Suspense-Enabled Library.

Practical Guide To Not Blocking The Event Loop

Mon, 01 May 2023 02:34:14 +0000

JavaScript runs in a single-threaded environment with an event loop, an architecture that is very easy to reason about. It’s a continuous loop executing incoming work. Said work can schedule more of it for the future.

while (hasWorkToDo) {
  /* Run timers, I/O callbacks,
       check for incoming connections,
       and so on... */
  doWork();
}

Synchronous work runs immediately; asynchronous work runs when there is no synchronous work to left to perform (or simply, “later”). Ideally, the execution profile of the your application should allow the event loop to run frequently in order to perform background work (e.g. accepting new connections, running timers, etc).

  
gantt
title Ideal Execution Profile
dateFormat HH
axisFormat %H
todayMarker off
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 02
Background Work :milestone, crit, 02, sameline
doWork() :02, 03
Background Work :milestone, crit, 03, sameline
doWork() :03, 04

This design implies that performing synchronous work is a Big Deal: for every continuous moment it runs, the event loop cannot perform any work – none!

/* setImmediate registers a
   callback on the event loop */
setImmediate(() => {
  console.log("This will at some point in the future");
});

/* synchronous work that you 
   will never see the end of */
findNthPrime(9999999);

  
gantt
title Blocking Event Loop For a Long Time
dateFormat HH
axisFormat %H
todayMarker off
section User Code
setImmediate() :01, 03
findNthPrime(9999999) :03, 10
console.log(...) :10, 12
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 10
Background Work :milestone, crit, 10, sameline
doWork() :10, 12

In server contexts, one such request can block all others indefinitely.

/* If a request to /computePrimes
   has been sent, this route will
   never respond. It will timeout. */
app.get("/home", () => {
  return response("Welcome Home!");
});

app.get("/computePrimes", () => {
  /* synchronous work that you 
       will never see the end of. */
  return response(findNthPrime(9999999));
});

  
gantt
title One Request Blocking Other Requests
dateFormat HH
axisFormat %H
todayMarker off
section Client
GET /home :01, 03
GET /computePrimes :crit, 02, 10
GET /home :active, 04, 12
GET /home :05, 14
section User Code
handle /home :01, 03
handle /computePrimes :crit, 03, 10
findNthPrime(9999999) :crit, 04, 09
handle /home :active, 10, 12
handle /home :12, 14
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 03
Background Work :milestone, crit, 03, sameline
doWork() :crit, 03, 10
Background Work :milestone, crit, 10, sameline
doWork() :active, 10, 12
Background Work :milestone, crit, 12, sameline
doWork() :12, 14

There are three solutions to these scenarios.

Throw more nodes at it
Refactoring findNthPrime to perform work asynchronously
Off-loading findNthPrime to another thread

Throw More Nodes At It!

The industry term for “throw more resources at it” is Horizontal Scaling (as opposed to Vertical Scaling, where the name of the game is “throw better resources at it”). One of the features of Node.js that had people excited was built-in support for easy horizontal scaling via Clusters.

The general idea is to run multiple servers in parallel such that if one server is busy, another can take the incoming request. A pitfall with this approach is that it can bury the issue until the load catches up.

In our server implementation, the synchronous is slow to complete. If there is one node, it takes one request to put it out of commission. Scaling up the number of nodes will increase the capacity for those requests by the same number.

This approach is straightforward to implement but doesn’t avoid blocking the event loop; it simply adds more event loops into the mix. As a strategy, it works as long as the rate of incoming requests does not exceed the time it takes to process them.

Refactoring to Perform Work Asynchronously

Asynchronous work is usually not CPU-bound. For example, if it takes 10ms to read a file, it is likely that less than 1ms was spent waiting for the CPU, and the rest was waiting for the disk.

Calculating primes, on the other hand, is entirely CPU-bound: it’s just basic mathematical operations.

On an event loop architecture, a long-running algorithm can be converted to an asynchronous job by chunking the work onto the event loop.

Consider the following findNthPrime implementation:

const findNthPrime = (num) => {
  let i,
    primes = [2, 3],
    n = 5;
  const isPrime = (n) => {
    let i = 1,
      p = primes[i],
      limit = Math.ceil(Math.sqrt(n));
    while (p <= limit) {
      if (n % p === 0) {
        return false;
      }
      i += 1;
      p = primes[i];
    }
    return true;
  };
  for (i = 2; i <= num; i += 1) {
    while (!isPrime(n)) {
      n += 2;
    }
    primes.push(n);
    n += 2;
  }
  return primes[num - 1];
};

  
gantt
title Execution Profile Of findNthPrime()
dateFormat HH
axisFormat %H
todayMarker off
section User Code
findNthPrime() :01, 09
isPrime() :01, 03
isPrime() :03, 05
isPrime() :05, 07
isPrime() :07, 09
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 09
Background Work :milestone, crit, 09, sameline

The fundamental goal of this approach is to add gaps between blocks of synchronous execution, allowing the event loop to run while your algorithm executes. Where you want those gaps to appear depends on the performance profile you are looking for. If your algorithm blocks the event loop for over a second, adding gaps anywhere is worthwhile.

In this case, isPrime() does most of the work over multiple iterations. It is already conveniently isolated in a function, which makes it a prime candidate to defer it on the event loop.

  
gantt
title Target Execution Profile of findNthPrimeAsync()
dateFormat HH
axisFormat %H
todayMarker off
section User Code
findNthPrime() :01, 09
isPrime() :01, 03
isPrime() :03, 05
isPrime() :05, 07
isPrime() :07, 09
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 03
Background Work :milestone, crit, 03, sameline
doWork() :03, 05
Background Work :milestone, crit, 05, sameline
doWork() :05, 07
Background Work :milestone, crit, 07, sameline
doWork() :07, 09
Background Work :milestone, crit, 09, sameline

Promisify

The first step is to isolate the portion of the code to move onto the event loop into a Promise:

  const isPrime = n => new Promise(
    resolve => {
      let i = 1, p = primes[i],
        limit = Math.ceil(Math.sqrt(n));
      while (p <= limit) {
        if (n % p === 0) {
          return resolve(false);
        }
        i += 1;
        p = primes[i];
      }
      return resolve(true);
    }
  )
  // ...
  while (!await isPrime(n)) {
  //...

Turning sync code into a Promise does not make code asynchronous. For code to be asynchronous, it must be called from the event loop. setImmediate accepts a callback to do precisely that:

const isPrime = (n) =>
  new Promise((resolve) =>
    setImmediate(() => {
      let i = 1,
        p = primes[i],
        limit = Math.ceil(Math.sqrt(n));
      while (p <= limit) {
        if (n % p === 0) {
          return resolve(false);
        }
        i += 1;
        p = primes[i];
      }
      return resolve(true);
    })
  );

Complete Implementation

const asyncInterval = setInterval(() => {
  console.log("Event loop executed");
  exCount++;
}, 1);
const findNthPrimeAsync = async (num) => {
  let i,
    primes = [2, 3],
    n = 5;
  const isPrime = (n) =>
    new Promise((resolve) =>
      setImmediate(() => {
        let i = 1,
          p = primes[i],
          limit = Math.ceil(Math.sqrt(n));
        while (p <= limit) {
          if (n % p === 0) {
            return resolve(false);
          }
          i += 1;
          p = primes[i];
        }
        return resolve(true);
      })
    );
  for (i = 2; i <= num; i += 1) {
    while (!(await isPrime(n))) {
      n += 2;
    }
    primes.push(n);
    n += 2;
  }
  return primes[num - 1];
};

To prove that the code is now indeed on event loop, we can try scheduling on tasks on the event loop to see if they get executed:

console.log("Calculating Sync Prime...");
let syncCount = 0;
const syncInterval = setInterval(() => {
  console.log("Event loop executed");
  exCount++;
}, 1);

const sync = findNthPrime(nth);
console.log("Sync Prime is", sync);
clearInterval(syncInterval);
console.log("Intervals on event loop:", syncCount);

console.log("Calculating Async Prime...");
let asyncCount = 0;
const asyncInterval = setInterval(() => {
  console.log("Event loop executed");
  asyncCount++;
}, 1);

findNthPrimeAsync(nth)
  .then((n) => console.log("Async Prime is", n))
  .then(() => clearInterval(asyncInterval))
  .then(() => console.log("Intervals on event loop:", asyncCount));

It outputs:

Calculating Sync Prime...
Sync Prime is 541
Intervals on event loop: 0
Calculating Async Prime...
Event loop executed
Event loop executed
Event loop executed
Event loop executed
Event loop executed
Event loop executed
Async Prime is 541
Intervals on event loop: 6

For a visual, the execution profile looks like this:

  
gantt
title Execution Profile Of findNthPrime vs findNthPrimeAsync()
dateFormat HH
axisFormat %H
todayMarker off
section User Code
findNthPrime() :01, 09
isPrime() :01, 03
isPrime() :03, 05
isPrime() :05, 07
isPrime() :07, 09
findNthPrimeAsync() :09, 17
isPrime() :09, 11
isPrime() :11, 13
isPrime() :13, 15
isPrime() :15, 17
section Timers
interval :milestone, active, 11, sameline
interval :milestone, active, 13, sameline
interval :milestone, active, 15, sameline
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 09
Background Work :milestone, crit, 09, sameline
doWork() :09, 11
Background Work :milestone, crit, 11, sameline
doWork() :11, 13
Background Work :milestone, crit, 13, sameline
doWork() :13, 15
Background Work :milestone, crit, 15, sameline
doWork() :15, 17
Background Work :milestone, crit, 17, sameline

Replit Interactive Demo

Off-Loading to Another Thread

The last approach to processing a synchronous job without blocking the main thread is offloading it to another thread entirely. Worker pools optimize this strategy further.

The premise is to have a main thread dispatch a worker:

const nth = 100; // play with this value

const findNthPrimeWorker = (num) =>
  new Promise((resolve) => {
    const worker = new Worker(require.resolve("./worker.js"), {
      workerData: num,
    });

    worker.on("message", (d) => resolve(d));
  });

findNthPrimeWorker(nth);

with the worker performing the computation and sending the result:

// worker.js

const findNthPrime = (num) => {
  // ...
};

parentPort.postMessage(findNthPrime(workerData));

  
gantt
title Execution Profile of findNthPrimeWorker()
dateFormat HH
axisFormat %H
todayMarker off
section User Code
findNthPrimeWorker() :01, 09
section Event Loop
Background Work :milestone, crit, 01, sameline
doWork() :01, 02
Background Work :milestone, crit, 02, sameline
doWork() :02, 03
Background Work :milestone, crit, 03, sameline
doWork() :03, 04
Background Work :milestone, crit, 04, sameline
doWork() :04, 05
Background Work :milestone, crit, 05, sameline
doWork() :05, 06
Background Work :milestone, crit, 06, sameline
doWork() :06, 07
Background Work :milestone, crit, 07, sameline
doWork() :07, 08
Background Work :milestone, crit, 08, sameline
doWork() :08, 09
Background Work :milestone, crit, 09, sameline
section Worker Thread
findNthPrime() :01, 09
isPrime() :01, 03
isPrime() :03, 05
isPrime() :05, 07
isPrime() :07, 09

Replit Interactive Demo

Workers Limitations

Workers are ideal for moving long-running, CPU-bound tasks off the main thread but are not a silver bullet. Their primary limitation is the data that can be sent to them. The restrictions are documented in port.postMessage()

Workers != Magic!

An important callout with Workers is that by dedicating them to CPU-bound tasks, they are limited to the number of available threads. If your server has eight threads, running over eight workers will not make them run faster.

The benefit of Workers isn’t infinite parallelism but the guarantee that your main thread will always be free to perform quick work by off-loading non-so-quick work.

Effective Higher-Order Components

Thu, 02 Feb 2023 00:00:00 +0000

Before the introduction of contexts and hooks in React v16.8, Higher-Order Components (or HOCs for short) were a common sight. Today, it is an under-used pattern.

HOCs are Wrappers

A Higher-Order Component is a play on the functional programming concept of a High-Order Function. It is a function that accepts a component and returns it wrapped in additional logic.

While the concept presents infinite possibilities, practical applications should be limited to transparently adding wrappers or logic. Transparently means that HOCs should avoid surprising behavior: no modifying the component or the props it receives.

Conventions

HOC conventions suggest three general rules:

A HOC should not change the API of a provided component

A prop passed from the parent should reach the underlying component. Forwardining props is easy to do by using {...props} after any additional props.
HOCs should have a name following the withNoun pattern

For example withPropsLogger or withThemeProvider.
HOCs should not have any parameters aside from the Component itself. HOCs can handle additional parameters via currying.

A consistent HOC signature is important for their composability.
👍 Correct signature withNoun("some data")(MyComponent)
👎 Wrong order of calls withNoun(MyComponent)("some data")
👎 Missing currying withNoun("some data", MyComponent)

(Bonus) Provide a DisplayName:

While not a necessary development pattern, providing a custom DisplayName is a useful pattern for debugging. Adding it will make error messages and React Dev Tools more helpful in identifying issues in HOCs.

function withSubscription(WrappedComponent) {
  class WithSubscription extends React.Component {
    /* ... */
  }
  WithSubscription.displayName = `WithSubscription(${getDisplayName(
    WrappedComponent
  )})`;
  return WithSubscription;
}

function getDisplayName(WrappedComponent) {
  return (
    WrappedComponent.displayName || WrappedComponent.name || "Component"
  );
}

HOCs are Easy

The type signature of a HOC is generic: it accepts the same props as the component it wraps.

interface HOC<T> {
  (Component: React.ComponentType<T>): (props: T) => JSX.Element;
}

Some of the most common examples of HOCs involve…

Props logging:

const withPropsLogger = (Component) => (
  (props) => {
    console.log(props);
    return <Component {...props}/>
  };
);

Adding formatting, notice the currying pattern:

const withExtraPadding = (padding) => (Component) => (props) =>
  (
    <div styles={{ padding }}>
      <Component {...props} />
    </div>
  );

Adding Context Providers, once more with the currying pattern:

const withMyContext = (myContextValue) => (Component) => (props) =>
  (
    <MyContext.Provider value={myContextValue}>
      <Component {...props} />
    </MyContext.Provider>
  );

HOCs are Composable

Each of the HOCs above can be used on a component both individually or in combination.

const MyWrappedComponent = withPropsLogger(
  withMyContext(5)(withExtraPadding(20)(MyComponent))
);

Combining them without functional tools makes it difficult to read. Importing reduceHOCs and applyHOCs functions helps a lot with clarity.

const MyWrappedComponent = applyHOCs(
  withPropsLogger,
  withMyContext(5),
  withExtraPadding(20)
)(MyComponent);

The Don’ts

Don’t use HOCs Inline

React keeps track of the component state using a combination of component object identity and its location in the React virtual DOM. Changing either the identity or the location will cause a loss of state.

export default function App() {
  // Create a function with a new identity on every render
  // which makes it lose state track of internal
  const ClickCounterWithLogger = withPropsLogger(ClickCounter);
  return <ClickCounterWithLogger />;
}

Interactive example on CodeSandbox

Don’t use Conditional Wrappers

Similar to inline HOCs, if the tree produced by a component changes in structure, such as a wrapper removal, React will be unable to persist child states.

Don’t use HOCs for Data

Another example of situations for which HOCs are not suitable for are data providers:

function withData(Component) {
  const { data, isLoading } = useApi();
  return (props) => <Component data={data} isLoading={isLoading} {...props} />;
}

The data provider HOC pattern was formerly a common use case for HOCs in React. The highest profile example is Redux’s connect HOC, which now has a Tip at the top of the page containing the following:

connect still works and is supported in React-Redux 8.x. However, we recommend using the hooks API as the default.

At the time, it was a pattern that gathered mixed feelings and metaphorical discussions on whether “tails should wag dogs.” Hooks have superceded this practice.

Don’t be Clever

Armed with a refreshed interest in HOCs, remember that HOCs are a tool to lessen the mental load of JSX. They are not an opportunity to show off your functional programming skills.

Deciding when is an appropriate time for HOCs is a judgment call<> much like determining when to use contexts, and often comes down to opinion. With that said, I am firm on a few cases when you should not use HOCs.

One such case is when HOCs implement logic that should be owned by either the component itself or its parent. For example, defaulting props:

// A parent component is responsible for supplying
// default props, or the child component should
// be handling it.
withDefaultValueForProp(MyComponent)({
  field: "data",
  defaultData: [1, 2, 3],
});

The above creates logic gaps that are difficult to modify if you end up needing something more granular. What if MyComponent is changed to either accept a data={...} or an isLoading prop? The HOC will need to go. Any HOC doing too much is destined do nothing at all.

A more dramatic case is implementing dynamic logic in the HOC call.

withPropTransformation(MyComponent)((props) => {
  return {
    ...props,
    name: props.name.toUpperCase(),
  };
});

HOCs should be reserved when the logic is so minimal that you feel comfortable approaching with an “out of sight, out of mind” mentality.

Additional Information for Library Components

I received comments about this post telling me that I didn’t go deep enough into the weeds of HOCs that could potentially bite library authors. I didn’t because this post is Effective HOCs, not Everything You Need To Know About HOCs (maybe one day).

Nonetheless, I will go through some of the more common edge-cases HOC authors need to think about. By no means is the following exhaustive!

A Note on Refs

If you need to wrap a component that uses ref in a HOC, including a React.forwardRef call will make it work.

const withPropsLogger = (Component) => {
  return React.forwardRef((props, ref) => {
    console.log(props);
    return <Component {...props} ref={ref} />;
  });
};

I haven’t found a method to add types to a HOC while supporting components simultaneously with and without forwardRef.

type HOCForRefComponent<T, P extends {}> = React.ForwardRefExoticComponent<
  React.PropsWithoutRef<P> & React.RefAttributes<T>
>;
const withPropsLoggerWithRef = <T, P extends {}>(
  Component: HOCForRefComponent<T, P>
): HOCForRefComponent<T, P> =>
  React.forwardRef<T, P>((props, ref) => (
    <Component {...(props as React.PropsWithoutRef<P>)} ref={ref} />
  ));

Another approach is avoiding the ref keyword altogether when it comes to HOCs and using a prop name like innerRef.

There are a few other edge cases discussed in the React documentation on refs and HOCs, but it focuses on class components.

A Note on Static Properties

In my eyes, static properties are an anti-pattern but I digress. In the context of HOCs, static properties are not automatically passed along.

You need explicitly pass each static property to your HOC’d component.

Addressing Comments

This post has received some traction on Reddit. I’m pretty happy about the attention, but most of the commenters are clearly not very happy about HOCs. Many believe some variation of “hooks good, HOCs bad”.

Hooks > HOCs

While I appreciate this post keeping the art of the HOC alive and I really like their dos and donts, I still think hooks are a significantly better option 99.9% of the time. HOCs a very easy way to add surprising behavior to components that might confound future developers. Hooks basically killed them because they are a more predictable, explicit pattern. – /u/sickcodebruh420

I agree: hooks did kill HOCs but only because HOCs used to be the only way of providing app-level data without prop-drilling. Data-provider HOCs were “99.9%” of them and seemingly traumatized developers to the point that they never want to see a HOC again.

Good HOCs exist, and provide powerful patterns which can help write clear and succinct expressions in lieu of JSX.

const withCommon = reduceHOCs(withErrorBoundary, withThemeProvider);

const withGlobal = reduceHOCs(withQueryClientProvider, withStoreProvider);

applyHOCs(withCommon, withGlobal)(App);

applyHOCs(withCommon)(Page);

(Not Quite) Everything About HOCs

Another comment suggested that I didn’t cover HOCs thoroughly enough and brought up a few points:

Just wanted to add my two cents if somebody is making library that is built around HOC (not sure why?) is to ensure these things:

- HOC must pass static properties (use `hoist-non-react-statics`)
- HOC must have two versions: one that passes ref and other that is not.
- It would be nice if HOC would set nice `displayName`
-- [/u/Reeywhaar](https://www.reddit.com/r/javascript/comments/10rxfv5/comment/j6z0aas/?context=3)

The post has been updated to reflect these points. I suggest reading the whole thread with /u/Reeywhaar.

Skipping Outdated Refs with GitHub Actions

Tue, 31 Jan 2023 02:23:24 +0000

If you use GitHub Actions for deployments in a “push to master, deploy to prod” sort of flow, you’ve likely wanted to avoid deploying conflicting refs.

By default, GitHub Actions will want to run a deployment for every commit as soon as you push it:

name: Deploy on Push

on:
  push:
    branches: [ master ]
  workflow_dispatch:

jobs:
  deploy-public:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
            fetch-depth: 0  
            
      - name: Run Deployment
        uses: knyzorg/deploy

The above workflow will often be sufficient. Case in point, it’s pasted from the workflow file of this blog.

The flaws only begin to surface when you push code faster than it can be deployed. What do you expect to happen if you push a new commit to master before the Run Deployment step has completed?

It will typically break in some way depending on how sophisticated your deployment target is. In the case of Dokku, the second deployment will fail because it was locked by the first. In the case of lockless system, there is a chance that the later commit will be overridden by the first.

Enter: Concurrency Groups

GitHub Actions have a feature called Concurrency Groups. It lets you declare a string template which groups multiple workflow runs together, and guarantees that only one of them will run at a time.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

GitHub enforces this guarantee in one of two ways:

Queuing: Every workflow requested only begins execution if no other workflow is active in the concurrency group. If one is, it will wait its turn and remain in a pending state.
Canceling: When a workflow is requested while another workflow within the same concurrency group is already running, the older workflow is aborted.

Both of these approaches are flawed.

Canceling an in-progress job is always dangerous given the possibility of leaving your deployment target in an unknown state. It can work fine if you’re using a cloud provider which has figured out every failure mode, but going around killing processes is not a practice I recommend.

Queuing, on the other hand is very technically sound but not always convenient. Imagine if your deployment takes 10 minutes, and you have commits every 5 minutes: How long will take to deploy your 10th commit?

Bridging the Gap

It’s possible to capture the best of both by refining what exactly we are looking for: How do ensure that every deployment only deploys the latest code?

One idea, is to ensure we checkout the latest code on every run instead of the default $GITHUB_SHA ref. This would make many of the runs redundant, wasting GitHub Actions minutes and will break workflows where you wish to deploy a specific ref via a workflow-dispatch.

A better approach is to add a check validating if the requested ref’s SHA matches the latest SHA of that ref and failing the step if it isn’t.

I have it implemented as such:

name: Deploy on Push

on:
  push:
    branches: [ master ]
  workflow_dispatch:

# `GH_TOKEN` is needed to use the `gh` cli
env:
  GH_TOKEN: ${{ github.token }}

  # Don't run multiple deployments at once
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}


jobs:
  uptodate:
    name: Fail if out of date
    runs-on: ubuntu-latest
    steps:
      - name: Verify if ref is up-to-date
        run: |
          CURRENT=$GITHUB_SHA
          # Get SHA of latest commit
          LATEST=$(gh browse -c -n -R ${{ github.repository }} | cut -d '/' -f7)
          echo "Current: $CURRENT"
          echo "Latest: $LATEST"
          # Exit code 1 if mismatches
          [ "$CURRENT" = "$LATEST" ]          

  deploy-public:
    runs-on: ubuntu-latest
    # Wait for uptodate check
    # Will not run if it fails
    needs: [ uptodate ]
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
            fetch-depth: 0  
            
      - name: Run Deployment
        uses: knyzorg/deploy

The idea is that all the workflows will be queued on a per-ref basis, but the members of the queue will not be processed if it is not the latest. At any given moment, it will be deploying the latest code.

The only exception to this will be if the commits are frequent to the point that by the time the uptodate check runs, it will already be out-of-date.

If that is case, the goals change: you’re no longer looking for a push-to-deploy workflow but rather a truly continuous deployment:

while (true) {
    deploy();
}

I haven’t explored what GitHub Actions offer in this domain, but a frequently recurring workflow could suit your needs.

Writing a Recursive Utility Type in TypeScript

Sat, 28 May 2022 00:00:00 +0000

I recently dealt with a tricky TypeScript situation. GraphQL servers have a feature where for any response it returns, it adds a __typename within every object corresponding to its type’s name.

This is what a typical response looks like:

{
  "__typename": "SolarSystem",
  "id": 123,
  "name": "The Solar System",
  "star": {
    "__typename": "Planet",
    "id": 123,
    "name": "Sun",
    "size": 12345,
    "inhabitants": null
  },
  "planets": [
    {
      "__typename": "Planet",
      "id": 123,
      "name": "Earth",
      "size": 12345,
      "inhabitants": [
        {
          "__typename": "LifeForm",
          "id": 123,
          "name": "Human"
        }
      ]
    }
  ]
}

When a GraphQL codegen script runs, this __typename field gets eventually imported into TypeScript world and makes its way into the generated schema:

interface SolarSystem {
  __typename: "SolarSystem";
  id: number;
  name: string;
  star: Planet;
  planets: Planet[];
}

interface Planet {
  __typename: "Planet";
  id: number;
  name: string;
  size: number;
  inhabitants: LifeForm[] | null;
}

interface LifeForm {
  __typename: "LifeForm";
  id: number;
  name: string;
}

Here is a component we have to display a LifeForm entity using the schema types:

interface EntityProps<T> {
  entity: T;
}
function LifeForm({ entity }: EntityProps<LifeForm>) {
  return <>{entity.name}</>;
}

In production, we will typically invoke it using a GraphQL query:

const { data } = useLifeFormQuery();
return <LifeForm entity={data} />;

But what if we want to mock it?

<LifeForm
  entity={{
    __typename: "LifeForm", // This is required, but we will never use it!
    name: "Humans",
  }}
/>

Suddenly, __typename becomes a burden. Our component APIs require something which we will never use (and if we do use it, it would mean coupling our view components to GraphQL’s implementation details – not good!). In this case, getting rid of the __typename requirement is easy: use Omit<T, K>!

interface EntityProps<T> {
  entity: Omit<T, "__typename">;
}

// ...

<LifeForm
  entity={{
    name: "Humans",
  }}
/>;

But what if instead of LifeForm, we need the whole SolarSystem?

interface EntityProps<T> {
  entity: Omit<T, "__typename">;
}
function SolarSystem({ entity }: EntityProps<SolarSystem>) {
  return <>{entity.name}</>;
}
<SolarSystem
  entity={{
    //__typename: "SolarSystem",
    id: 123,
    name: "The Solar System",
    star: {
      __typename: "Planet",
      id: 123,
      inhabitants: null,
      name: "Sun",
      size: 9999,
    },
    planets: [
      {
        __typename: "Planet",
        id: 123,
        name: "Earth",
        size: 12345,
        inhabitants: [
          {
            __typename: "LifeForm",
            id: 123,
            name: "Human",
          },
        ],
      },
    ],
  }}
/>;

The Omit<T, K> allows us to omit the first __typename, but what about the rest? Is it possible to remove all __typename without rewriting the type definition by hand?

Using Mapping Types to Override Definitions

The most practical way of overriding a type definition is by using mapped types.

The TypeScript Handbook: When you don’t want to repeat yourself, sometimes a type needs to be based on another type. Mapped types build on the syntax for index signatures, which are used to declare the types of properties which have not been declared ahead of time.

The most basic mapped type is one that duplicates another type:

interface MyType {
  foo: number;
  bar: boolean;
  baz: "hello" | "world";
}

type MyMappedType = {
  [K in keyof MyType]: MyType[K];
};

// Or more generically...

type Duplicate<T> = {
  [K in keyof T]: T[K];
};

type MyGenericallyMappedType = Duplicate<MyType>;

Playground

Mapped types can extend, restrict, or modify entirely the type they are operating on:

interface MyType {
  foo: number;
  bar: boolean;
  baz: "hello" | "world";
}

type AllowNumbers<T> = {
  [K in keyof T]: T[K] | number;
};

const allowedNumbers: AllowNumbers<MyType> = {
  foo: 5,
  bar: 6,
  baz: 7,
};

type DisallowNumbers<T> = {
  [K in keyof T]: Exclude<T[K], number>;
};

const disallowedNumbers: DisallowNumbers<MyType> = {
  foo: 5, // Error, no numbers allowed
  bar: true,
  baz: "hello",
};

type OnlyNumbers<T> = {
  [K in keyof T]: number;
};

const onlyNumbers: OnlyNumbers<MyType> = {
  foo: 5,
  bar: true, // Error, only numbers allowed
  baz: "hello", // Error, only numbers allowed
};

type DoubleWrapped<T> = {
  [K in keyof T]: { [P in K]: T[K] }; // Nested remapping. P == K
};

const doubleWrapped: DoubleWrapped<MyType> = {
  foo: { foo: 5 },
  bar: { bar: true },
  baz: { baz: "hello" },
};

Playground

The TypeScript Handbook has other interesting examples.

Of particular interest to us is the ability to apply the Omit<T, K> utility to all children of a type:

interface FooType {
  __typename: "First";
  name: string;
  child: {
    __typename: "Second";
    name: string;
    child: {
      __typename: "Third";
      name: string;
    };
  };
}

type OmitFromChildren<T, K extends string> = {
  [P in keyof T]: Omit<T[P], K>;
};

const test: Omit<OmitFromChildren<FooType, "__typename">, "__typename"> = {
  // __typename: "First";
  name: "Top level",
  child: {
    // __typename: "Second",
    name: "Child",
    child: {
      __typename: "Third", // Still Required
      name: "Leaf",
    },
  },
};

Playground

The above allows us to use Omit<T, K> two levels deep. We will later reuse the mapping type technique to apply Omit<T, K> recursively to a complete tree.

Limitations of Omit

Omit<T, K> has a few surprising edge cases that we need to cover before proceeding:

Unions

Under the hood, Omit<T, K> is implemented using Exclude in such a way, that passing a union type to it produces nonsense.

interface FooType {
  __typename: "First";
  name: string;
}
interface FooType2 {
  __typename: "First";
  name2: string;
}

// No static typing is applied
const test: Omit<FooType | FooType2, "__typename"> = {
  name: 123, // Wrong type, but no errors :hmm:
};

Playground

The reason why this behaves the way it does would be a blog post on its own, but suffice to say that the way to fix it is to distribute the union.

Tip: To Distribute means to check every member of a union seperately.

A union can be forcefully distributed by using the extends operator:

// Every type extends `unknown`
type UnionOmit<T, K extends string | number | symbol> = T extends unknown
  ? Omit<T, K>
  : never;

As a sidenote, UnionOmit turns out to be simply a more flexible version of Omit<T, K>. I do not see any value in using Omit<T, K> by itself anymore.

Once the types are distributed, type checking is restored:

interface FooType {
  __typename: "First";
  name: string;
}
interface FooType2 {
  __typename: "First";
  name2: string;
}

type UnionOmit<T, K extends string | number | symbol> = T extends unknown
  ? Omit<T, K>
  : never;

const test: UnionOmit<FooType | FooType2, "__typename"> = {
  name: 123, // TypeError: type checking is back!
};

Playground

Nullable Types

You may think that a nullable type, defined as T | null is just a regular union, but it sometimes behaves differently than other types. I’ll admit that I don’t have this part fully figured out, but my working theory is that null types are sticky and do not distribute like other types.

type UnionOmit<T, K extends string | number | symbol> = T extends unknown
  ? Omit<T, K>
  : never;

interface FooType {
  __typename: "First";
  name: string;
}

// No static typing is applied
const test: Omit<FooType | null, "__typename"> = {
  name: 123, // Wrong type, but no errors :hmm:
};

// No static typing is applied... AGAIN!
const test2: UnionOmit<FooType | null, "__typename"> = {
  name: 123, // Wrong type, but no errors :hmm:
};

Playground

We can forcefully distribute them using a different technique:

type UnionOmit<T, K extends string | number | symbol> = T extends unknown
  ? Omit<T, K>
  : never;
type NullUnionOmit<T, K extends string | number | symbol> = null extends T
  ? UnionOmit<NonNullable<T>, K> | null
  : UnionOmit<T, K>;

interface FooType {
  __typename: "First";
  name: string;
}

const test: NullUnionOmit<FooType | null, "__typename"> = {
  name: 123, // TypeError: type checking is back!
};
const test2: NullUnionOmit<FooType | null, "__typename"> = null; // Nulls are legal

Playground

Functions

A function is a special kind of object: it has the property of being callable. TypeScript considers this property fragile enough to strip it from any function definition that has been touched by Omit<T, K>:

type OmittedFunction = Omit<() => true, "key">;
let func: OmittedFunction = () => true;
func(); // This expression is not callable.
//   Type 'OmittedFunction' has no call signatures.

Playground

One solution to this is to specifically avoid touching functions:

type FunctionSafeOmit<T, K extends string> = T extends Function
  ? T
  : Omit<T, K>;
type OmittedFunction = FunctionSafeOmit<() => true, "key">;
let func: OmittedFunction = () => true;
func();

Playground

There is nothing wrong with this method technically, but it does not inspire confidence. What if functions are not the only type that breaks in this way? While it might be the case today, new special types are added to JavaScript (Classes, Promises, Symbols, Proxies, etc) every few years. It might not be true tomorrow.

This brings us to the second, preferred solution. Instead of blacklisting every type individually, we can selectively apply Omit<T, K> to the types which have the property we wish to omit:

type SafeOmit<T, K extends string> = T extends { [P in K]: any }
  ? Omit<T, K>
  : T;
type OmittedFunction = SafeOmit<() => true, "key">;
let func: OmittedFunction = () => true;
func();

Playground

Writing Recursive Generics

Time to breathe a breath of fresh air: The difficult parts are behind us. Recursive Generics in TypeScript may be tricky at times, but they don’t have gotchas. As long as you do not attempt to write an infinitely deep expression, it should be fine.

A recursive mapping type looks like this:

type Recursive<T> = {
  [P in keyof T]: Recursive<T[P]>;
} & { changed: true };

If we want to recurse conditionally, we need to only recurse when appropriate:

// Do not recurse on specific structure
type Recursive<T> = {
  [P in keyof T]: T[P] extends { value: number } ? T[P] : Recursive<T[P]>;
} & { changed: true };

The above will stop recursing on any branch if it hits a match. If our goal is to recurse on the whole type while applying an Omit<T, K>, the recursion must always happen, but the application becomes conditional:

type Recursive<T> = T extends { value: number }
  ? { [P in keyof T]: Recursive<T[P]> }
  : {
      [P in keyof T]: Recursive<T[P]>;
    } & { changed: true };

let test: Recursive<{ foo: { bar: { value: 3 }; baz: { value: true } } }> =
  null as any;

test.foo.bar.changed; // Property 'changed' does not exist on type
test.foo.baz.changed; // Property 'changed' exists

Playground

The duplicated portion of the definition can be extracted into a helper type:

type RecursiveHelper<T> = { [P in keyof T]: Recursive<T[P]> };
type Recursive<T> = T extends { value: number }
  ? RecursiveHelper<T>
  : RecursiveHelper<T> & { changed: true };

let test: Recursive<{ foo: { bar: { value: 3 }; baz: { value: true } } }> =
  null as any;

test.foo.bar.changed; // Property 'changed' does not exist on type
test.foo.baz.changed; // Property 'changed' exists

Playground

Putting It All Together

type UnionOmit<T, K extends string | number | symbol> = T extends unknown
  ? Omit<T, K>
  : never;
type NullUnionOmit<T, K extends string | number | symbol> = null extends T
  ? UnionOmit<NonNullable<T>, K>
  : UnionOmit<T, K>;
type RecursiveOmitHelper<T, K extends string | number | symbol> = {
  [P in keyof T]: RecursiveOmit<T[P], K>;
};
type RecursiveOmit<T, K extends string | number | symbol> = T extends {
  [P in K]: any;
}
  ? NullUnionOmit<RecursiveOmitHelper<T, K>, K>
  : RecursiveOmitHelper<T, K>;

const cleanSolarSystem: RecursiveOmit<SolarSystem, "__typename"> = {
  //__typename: "SolarSystem",
  id: 123,
  name: "The Solar System",
  star: {
    //__typename: "Planet",
    id: 123,
    inhabitants: null,
    name: "Sun",
    size: 9999,
  },
  planets: [
    {
      //__typename: "Planet",
      id: 123,
      name: "Earth",
      size: 12345,
      inhabitants: [
        {
          //__typename: "LifeForm",
          id: 123,
          name: "Human",
        },
      ],
    },
  ],
};

Playground

Bonus Feature

As a cherry on top, not only does T accept unions, but so does K:

interface Foo {
  a: 3;
  b: 4;
  c: 5;
}
type Bar = RecursiveOmit<Foo, "a" | "b">;
let x: Bar = {
  c: 5,
};

The State of Copy-Pasting in JavaScript

Sat, 15 Jan 2022 00:00:00 +0000

I recently did some work on a VS Code extension whose purpose is to handle rich pastes. It prompted me to survey different copy-pasting libraries and the state of the NPM ecosystem as a whole.

How do clipboards work?

Clipboards across different operating systems work essentially the same. For this reason, we will stick to looking at a single one – Windows.

A common misconception about how clipboards work is that they contain a single piece of data, such as text or an image. In reality, clipboards hold all the ways target software can represent the data.

Consider if I copy the following webpage:

HTML headings as rendered by Firefox

When pasting it into Microsoft Word, it appears formatted as rich content:

Microsoft Word displays rich content exactly as Firefox does

When pasting it into Notepad++, it appears as plain text:

Notepad++ does not handle rich content

Pasting different content types depending on the software is possible because Firefox provides multiple representations of the rendered content to the clipboard.

Let’s see what types the clipboard is holding using Powershell:

$dataObj = [System.Windows.Forms.Clipboard]::GetDataObject()
foreach ($fmt in $dataObj.GetFormats()) {
    [Console]::WriteLine($fmt)
}

## Output: ##
HTML Format
System.String
UnicodeText
Text
Chromium Web Custom MIME Data Format
Locale
OEMText

We can look inside some of the clipboard types using Powershell, mainly HTML Format and Text with the following commands:

# Get Text
[System.Windows.Forms.Clipboard]::GetText([System.Windows.Forms.TextDataFormat]::Text)

## Output: ##
This is heading 1
This is heading 2
This is heading 3
This is heading 4
This is heading 5
This is heading 6

# Get HTML Format
[System.Windows.Forms.Clipboard]::GetText([System.Windows.Forms.TextDataFormat]::Text)

## Output: ##
Version:0.9
StartHTML:00000174
EndHTML:00000410
StartFragment:00000208
EndFragment:00000374
SourceURL:https://www.w3schools.com/tags/tryit.asp?filename=tryhtml_headers
<html><body>
<!--StartFragment--><h1>This is heading 1</h1>
<h2>This is heading 2</h2>
<h3>This is heading 3</h3>
<h4>This is heading 4</h4>
<h5>This is heading 5</h5>
<h6>This is heading 6</h6><!--EndFragment-->
</body>
</html>

The way to approach clipboards as a consumer is to consume the clipboard formats you know how to, prioritizing some over others. For example, Microsoft Word will prioritize pasting HTML Format formats over Text formats by default.

While Powershell has some built-in parsers, implementing the format specification for every type of content is a lot of work. Are there libraries that can help us with this?

Copy-Pasting in the NPM Ecosystem

The simplest clipboard library would let us query the clipboard directly for binary data. This approach would require us to a parser per format per operating system. While such libraries deserve a place in this world, they are not helpful for most applications. Most applications want to handle copying and pasting only for text, rich text, images, and sometimes files. Let’s go through the different clipboard management libraries and see how they fare.

We are looking for a library that has the following features:

Pure JS, with native bindings
Cross-Platform Support
- Windows
- Linux
- MacOS
Copy to clipboard
- Plain Text
- Rich Text
- Images
- Files
Paste from clipboard
- Plain Text
- Rich Text
- Images
- Files

Here is a table I made from the collected NPM packages, featuring the most popular clipboard-related libraries on NPM:

Note: This table does not include browser-based copy-paste.

Features / Libraries	clipboardy	copy-paste	clipboard-cli	node-clipboard-wd	Electron (Not a library)
Pure JS	Uses system utilties	Uses system utilties	Uses system utilties	Chromium binary	Uses native bindings
Cross-Platform Support	Yes	Yes	Yes	Yes	Yes
Windows	Yes	Yes	Yes	Yes	Yes
Linux	Yes	Yes	Yes	Yes	Yes
MacOS	Yes	Yes	Yes	Yes	Yes
Copy to Clipboard	Partial	Partial	Partial	No	Yes
Plain Text	Yes	Yes	Yes	No	Yes
Rich Text	No	No	No	No	Yes
Images	No	No	No	No	Yes
Files	No	No	No	No	Exposes binary API
Paste from Clipboard	Partial	Partial	Partial	Yes	Yes
Plain Text	Yes	Yes	Yes	Yes	Yes
Rich Text	No	No	No	Yes	Yes
Images	No	No	No	Yes	Yes
Files	No	No	No	Yes	Exposes binary API

Honorable mention: save-clipboard-image, uses AppleScript to save an image from clipboard to a file.

Summary

Before writing this post, I was unaware that the result would be this. It appears that all of NPM’s clipboard libraries work the same way: they call built-in executables on their host operating system and return the data. Interestingly, none of them handle images, rich text, or files despite no reason they couldn’t deal with them the same way.

The only exceptions to this pattern are Electron and node-clipboard-wd. The former is a framework unsuitable for usage as a library. The latter was written by myself last week as an experiment.

Where do we go from here?

Software developers have crossed the clipboard bridge in other environments before. In fact, NodeJS developers have already crossed it in Electron, which uses native bindings under the hood. There is no reason we couldn’t do the same using a more lightweight C++ library.

I find clip particularly promising in this regard, and I’ve been looking into writing a NodeJS wrapper around it. For posterity, here is a table of possible native libraries that I have found so far:

Features / Libraries	clip	arboard	clipboard
Cross-Platform Support	Yes	Yes	Yes
Windows	Yes	Yes	Yes
Linux	Yes	Yes	Yes
MacOS	Yes	Yes	Yes
Copy to Clipboard	Yes	Partial	Partial
Plain Text	Yes	Yes	Yes
Rich Text	Yes	No	No
Images	Yes	Yes	Yes
Files	Exposes binary API	No	No
Paste from Clipboard	Yes	Partial	Partial
Plain Text	Yes	Yes	Yes
Rich Text	Yes	No	No
Images	Yes	Yes	Yes
Files	Exposes binary API	No	No

PageSpeed for NGINX -- Fresh Debian Packages

Tue, 04 Jan 2022 00:00:00 +0000

Important Notice: Google has retired the underlying project which made integration with NGINX possible. As a result, the version maintained in my repository is stale, and is not receiving feature or security updates. Using this project is now discouraged and should be removed from your system.
To remove it from your system, follow the instructions at the bottom of the page.

In 2012, Google released version 1.0 of their PageSpeed modules for NGINX and Apache. It has gone largely unnoticed since then. The short of PageSpeed is that if you add it to your web server, you can configure it to optimize anything passing through it using techniques such as minification, format conversion, and even injecting scripts to lazy-load images. You can read more about what it does on the official site.

It sounded great in theory, but how properly install it with NGINX wasn’t obvious. While Google does publish scripts to help with the installation, it requires a non-trivial depth of knowledge to do right. After struggling with it for many hours, I wrote a guide for personal future reference.

I recently returned to those notes to entirely automate the process using GitHub Actions. The work is open-source and available on GitHub.

Installation

Run the following as root on a Debian-based machine:

sudo su
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 8028BE1819F3E4A0
echo "deb https://nginx-pagespeed.knyz.org/dist/ /" > /etc/apt/sources.list.d/nginx-pagespeed.list
echo "Package: *" > /etc/apt/preferences.d/99nginx-pagespeed
echo "Pin: origin nginx-pagespeed.knyz.org" >> /etc/apt/preferences.d/99nginx-pagespeed
echo "Pin-Priority: 900" >> /etc/apt/preferences.d/99nginx-pagespeed
apt update
apt install nginx-full # If NGINX is already installed, an `apt upgrade` works too
echo "pagespeed on;" > /etc/nginx/conf.d/pagespeed.conf
echo "pagespeed FileCachePath \"/var/cache/pagespeed/\";" >> /etc/nginx/conf.d/pagespeed.conf
echo "pagespeed FileCacheSizeKb 102400;" >> /etc/nginx/conf.d/pagespeed.conf
echo "pagespeed FileCacheCleanIntervalMs 3600000;" >> /etc/nginx/conf.d/pagespeed.conf
echo "pagespeed FileCacheInodeLimit 500000;" >> /etc/nginx/conf.d/pagespeed.conf
echo "pagespeed RewriteLevel CoreFilters;" >> /etc/nginx/conf.d/pagespeed.conf

systemctl reload nginx

The installation process is explained more thoroughly on the GitHub page if you’re curious.

Once that is done, you will have an active NGINX + PageSpeed installation that will receive the same updates as upstream NGINX. You can learn more about individual filters that you can enable in the documentation.

Undo

To stop using PageSpeed for NGINX, delete the following files:

/etc/apt/preferences.d/99nginx-pagespeed
/etc/nginx/conf.d/pagespeed.conf

Adding WSL Support to a VS Code Extension

Wed, 29 Dec 2021 00:00:00 +0000

I have a few dozen projects on GitHub. I put a lot of effort into my README.md files, making them complete with descriptions, instructions, and screenshots – the last one being the most time-consuming to manage.

Rich Editors are Easy

I don’t mean easy for the developers (I never tried, but it sounds daunting), but for the users. All the data inside a rich file format such as .docx is embedded inside of itself. There are no worries about hosting or broken links for your pictures, as Microsoft Word will save them the same way as your text.

Rich formats make copy-pasting images easy.

Screenshots are quick with Microsoft Word, especially if you know about Windows+Shift+S

Text Editors are Clunky

IDEs will give you the world as long as you stay inside of it. VS Code makes file management a breeze in your workspace but bringing in anything from the outside world will not be frictionless. Inserting a screenshot into a markdown document within VS Code is a multi-step process:

Take the screenshot
Save the screenshot in a folder
Locate the screenshot in file explorer
Drag-drop the screenshot into VS Code
Reference the screenshot from the markdown document

Nowhere near as seamless as Microsoft Word handles pasting images. What if there was an extension that could handle pastes directly?

Forking Forks

Clocking in at over 150k installs, mushan’s Paste Image features what we want. Unfortunately, the repository appears abandoned with the last commit being over two years old.

That’s a lot of issues

For my purposes, the extension did not work at all on WSL, but its popularity made me believe that there could be a functioning fork. At the time of writing, there are 117 forks, many of them active. Additionally, there are a few forks of forks.

There are a couple dozen forks that had activity in the past year

Most of the forks were to fix one-off issues, but one, in particular, has taken on the mantle by not just stopping at bug fixes and implementing new features. I would describe them, but the README does a fine job of it.

Judging it to be worth investing my time in, I started sending in a series of pull requests. The bulk of my work revolved around adding WSL support and refactoring the code to make it more maintainable. I’m happy with the result.

Reading the Windows Clipboard from WSL-land

As mentioned previously, when testing the original extension, it did not work for me due to my WSL-based setup. The extension works by accessing the clipboard through PowerShell and bash scripts, which invoke system utilities.

There are multiple scripts for Windows, Linux and Mac

The correct script gets executed based on the operating system which the extension detects. In the case of WSL, that operating system that runs the extension host is Linux, but since it is a “headless” Linux without an X11 server (though one can be installed) it doesn’t have a clipboard. Accessing the Windows clipboard requires jumping through a couple of hoops.

A feature of WSL is that any Windows-native application invoked from within WSL will run under the Window host (which is very different from WINE emulation, for example). This feature makes escaping for the WSL context as easy as launching PowerShell. Doing so, however, will break any paths generated in WSL-land such as __dirname or any output from the fs package. Luckily, they can be re-written back and forth between WSL and Windows formats using the wslpath utility.

~
▶ wslpath -u C:/
/mnt/c/

~
▶ wslpath -m /home/
//wsl$/Ubuntu/home

~
▶ wslpath -w /home/
\\wsl$\Ubuntu\home

The extension can detect that it’s running in a WSL environment using the is-wsl package. Putting the two together, it is possible to convert paths inside the NodeJS by calling out to wslpath.

function toWindowsPath(path: string) {
  if (getCurrentPlatform() != "wsl") return path;
  // Path must exist for wslpath to work
  await runCommand("touch", [path]);
  return runCommand("wslpath", ["-m", path]);
}

Better Clipboard API

The current approach of dispatching scripts to extract data from the clipboard is fundamentally broken. It will be possible to do it natively when VS Code extensions can leverage electron’s full clipboard APIs. I have filed an issue to have it supported.

Becoming a Maintainer

After investing many hours into this extension, GitHub greeted me with this e-mail:

GitHub invitation

I have been noticed!

Posts on Building Better Software Slower

Components Are Just Sparkling Hooks

First, What is a Component?

Second, What are Hooks?

You've Got Mail!

Headless Components

Unit Testing

Composition + Headless Components

State of the Art

Conclusion

You've Got Mail!

Default Audio Input (or Output) Device for MacOS

brew install switchaudio-osx

Registering a Service (Agent)

Go Further

You've Got Mail!

Other Solutions

MIDI Sheneningans

Software Solutions

Learn Suspense by Building a Suspense-Enabled Library

The Philosophy

Beware: Boundaries Reset State

Building a Shared Cache

You've Got Mail!

FetchCache Class

FetchCache Provider

useFetch Hook

In Action!

Tracking Data as Promises

Using Promises in the Cache

Enable Suspense 🎉

Whoops. We Just Re-Invented use()!

Review

You've Got Mail!

Ending Notes

FetchCacheProvider Implementation

What is missing from Suspense?

Transitions

Understanding React Concurrency

What is React Concurrency?

You've Got Mail!

No Mode, Only Features

useTransition

useDeferredValue

You've Got Mail!

Concurrent Features & Suspense

Practical Guide To Not Blocking The Event Loop

Throw More Nodes At It!

You've Got Mail!

Refactoring to Perform Work Asynchronously

Promisify

Complete Implementation

Off-Loading to Another Thread

Workers Limitations

Workers != Magic!

You've Got Mail!

Effective Higher-Order Components

HOCs are Wrappers

You've Got Mail!

Conventions

HOCs are Easy

HOCs are Composable

The Don’ts

Don’t use HOCs Inline

Don’t use Conditional Wrappers

Don’t use HOCs for Data

Don’t be Clever

You've Got Mail!

Additional Information for Library Components

A Note on Refs

A Note on Static Properties

Addressing Comments

Hooks > HOCs

(Not Quite) Everything About HOCs

Skipping Outdated Refs with GitHub Actions

Enter: Concurrency Groups

Bridging the Gap

Writing a Recursive Utility Type in TypeScript

You've Got Mail!

Using Mapping Types to Override Definitions

Whoops. We Just Re-Invented `use()`!

`useTransition`

`useDeferredValue`