DEV Community: Petyo Ivanov

Why I wrote my own state management for React Virtuoso

Petyo Ivanov — Mon, 14 Dec 2020 17:05:57 +0000

Almost 2 years after its first release, last Saturday I shipped v1 of React Virtuoso. With this release, the state management framework powering Virtuoso is now available as a separate package called urx,
with its own documentation and examples available at urx.virtuoso.dev. This is the story of what brought the development of the project there.

Virtuoso is not your Typical React App

The popular React state management solutions are designed with the app in mind - a relatively large data tree with reducers rebuilding certain parts of it. Managing the state of the Virtuoso component is a different kind of problem.
In its case, a multitude of continuously changing input values from the DOM combine with the component properties into a relatively simple data structure - a list of items "windowed" to show the currently visible part of a large list. Here's a pseudo-code representation of what the state calculation looks like:

// DOM input
top = dom.scrollTop
height = dom.viewportHeight
sizes = dom.itemSizes

// component properties
count = props.totalCount
overscan = props.overscan
data = props.data
groups = props.groups

// ... intermediate calculations
sizeTree = rebuildSizeTree(sizeTree, sizes, count)
listRange = rebuildWindow(top, height, overscan, listDimensions)
list = items(listRange, sizeTree)
listDimensions = dimensions(list)

// output of a list 
[paddingTop, paddingBottom] = dimensions(list)
items = buildItems(list, data, groups)

Here's the catch - none of the dom/props above is a static value. They are streams of changing values which should be efficiently propagated through the list/item calculation logic. The change propagation cannot be described efficiently with procedural code - you need a topology of dependencies.

Initial Prototype - the Redux-based Failure

My initial prototype of the component was Redux based.
The good news was that the idea of using a binary tree structure for the item sizes worked. The bad news was that either I did not understand Redux or it was the incorrect tool for what I was doing. My code was a pile of interdependent reducers that were repeatedly called with various combinations of values from actions and the existing state.

An artistic interpretation of Virtuoso's Redux implementation. Photo by Behnam Norouzi on Unsplash.

Second Attempt - Hooks

Unsurprisingly, re-implementing the idea with hooks did not make it better. In fact, it looked like a step in the wrong direction, because the Redux implementation was at least easily unit-testable outside of React. I threw the spaghetti away and took a short break from the idea.

Third Pass - RxJS to the Rescue

Staring at the code, I noticed the stream pattern. The scroll container was continuously "emitting" scrollTop values. The viewport emitted its height when resizing. The list items emitted their sizes when rendering or when resizing. Squinting a little bit, even the values of the component properties looked like streams of changing values. Could those values be wrapped into RxJS Observables?

The next implementation of Virtuoso was a bag of input observables that got combined and transformed to produce output observables. The observables were put in a context, and wired up to "dumb" React components through useInput(observable$) / useOutput(observable$)
pair of hooks that either pushed into the specified observable or re-rendered in response to a new value being emitted.

This approach was an enormous improvement. Handing updates through the combineLatest and withLatestFrom operators eliminated the duplication from the Redux actions. The observable combinatory logic was easily testable outside of React. Finally, rather than dealing with a state tree, I subscribe to the output observables I needed in the specific component, optimizing its rendering.

Observables felt like a well organized, permanent piping and transformation system of the component state. Photo by Paul Teysen on Unsplash.

Building Virtuoso was fun again. The version which I mustered the courage to announce to the world was built on top of RxJS - and it got a fairly positive response in /r/reactjs.
A few redditors noticed the RxJS dependency, but nobody called me out on the state management blasphemy I have created. Instead, they complained about the bundle size. RxJS was too large for a small UI component. And they were right.

This problem was not unsolvable, because I used a very small part of RxJS. Over the weekend, I whipped a home-grown implementation of what I was using from RxJS and threw it in a cheekily named tinyrx.ts. The RxJS dependency was gone and the package was down to 7kB according to Bundlephobia. In hindsight, doing that replacement back then was the right choice. Doing that at a later stage would not be that easy.

Fast Forward One Year - Virtuoso is Used for Chats and Feeds

The problem solved by Virtuoso (easy virtualization of variably sized items) was hard enough for the project to attract and retain supportive (and smart!) early adopters - who endured my poor understanding of React
and educated me on the finer arts of improving React performance (shoutout to Federico Zivolo a.k.a. FezVrasta).

I also understood a lot more about my users and their virtual lists. Many of them were building chats and data feeds - a use case which can be best described as a reverse endless scrolling. Reverse scrolling was a problem that I originally did not intend to address. And the business as usual new features overburdened my naive VirtuosoStore implementation, a single JS function that initiated and combined the entire set of observables used in the component. The project needed a rewrite to move forward.

My fellow developers had more than enough of me explaining why observables made sense in React.

urx was Born

As these things go, I fell in love with my pet reactive state management pattern, so I decided to give it its own name and proper documentation. It also grew up a bit and got some original looks. Rather than just being a poor man's RxJS, the urx library includes the systems abstraction as a way to organize Observables into testable components.
Subjects and Behavior Subjects (the names of which I find highly confusing) are renamed to streams and stateful streams.
The React abstraction got its own package, dedicated to the magical transformation of an urx system into a React component.

The Result

React Virtuoso consists of 1550 lines of code in framework-agnostic urx systems, wrapped up in ~200 lines of dumb react components wired up to the "master" List system. The react code is downright boring - the only unit tests against it are mostly checking the server-side-rendering specifics. The rest of the test suite is written against the various urx systems. As an example, here's how the domIOSystem looks:

import { connect, pipe, scan, map, system, stream, statefulStream } from '@virtuoso.dev/urx'

export const UP = 'up' as const
export const DOWN = 'down' as const
export type ScrollDirection = typeof UP | typeof DOWN

export const domIOSystem = system(
  () => {
    const scrollTop = stream<number>()
    const deviation = statefulStream(0)
    const smoothScrollTargetReached = stream<true>()
    const statefulScrollTop = statefulStream(0)
    const viewportHeight = stream<number>()
    const scrollTo = stream<ScrollToOptions>()
    const scrollBy = stream<ScrollToOptions>()

    connect(scrollTop, statefulScrollTop)
    const scrollDirection = statefulStream<ScrollDirection>(DOWN)

    connect(
      pipe(
        scrollTop,
        scan(
          (acc, scrollTop) => {
            return { direction: scrollTop < acc.prevScrollTop ? UP : DOWN, prevScrollTop: scrollTop }
          },
          { direction: DOWN, prevScrollTop: 0 } as { direction: ScrollDirection; prevScrollTop: number }
        ),
        map(value => value.direction)
      ),
      scrollDirection
    )

    return {
      // input
      scrollTop,
      viewportHeight,
      smoothScrollTargetReached,

      // signals
      scrollTo,
      scrollBy,

      // state
      scrollDirection,
      statefulScrollTop,
      deviation,
    }
  },
  [],
  { singleton: true }
)

The component implementation is quite portable; when React goes out of fashion, the underlying stream system can be wrapped in a different UI framework.

It's not all Roses, but it's Worth it

Reactive programming is not a silver bullet, nor magic fairly land where your code has no bugs. At some point, the Reactive Programming Wikipedia Article Implementation Challenges
became a checklist of the errors and the subtle issues I encountered. React, while perceptive to the approach, is also not explicitly designed to work with observable streams.

Still, I am certain that I could not implement React Virtuoso with any other state management.

Should you try urx?

The short answer is probably "no" unless you are implementing something similar to React Virtuoso. The popular state management tools have enormous healthy ecosystems, documentation, and tooling built for them.

However, you can go through the documentation even for the fun of it - it is a different take on UI state management. If you want to see a real-world example of how systems are built and organized, you can dig into the source code of React Virtuoso itself.

Reactive Programming for React Developers Part 2 - Integrate with React

Petyo Ivanov — Mon, 03 Jun 2019 05:56:12 +0000

In the first part of the series, we went through some basics of reactive programming. Today, we are going to implement a small (but interesting enough) task using React as the view and a reactive engine as the backend.

First Take: Counter

As a warm-up, we are going to do something similar to the Redux Counter example - a button which clicks and increments a value. Let's create a function which creates an input stream for the button click and an output stream for the counter:

import subscribe from 'callbag-subscribe'
import subject from 'callbag-subject'
import pipe from 'callbag-pipe'
import scan from 'callbag-scan'
import startWith from 'callbag-start-with'

export function createEngine() {
  const increments$ = subject()  

  const counter$ = 
    pipe(
      increments$,
      scan( acc => acc + 1, 0),
      startWith(0)
    )

  return {
    counter$,
    increments$
  }
}

There we go. If you went through the first part of the series, the above should not look that scary. We use the scan operator to capture and accumulate the clicks counter. We specify the initial value of the counter using startWith. Let's connect it to React:

import React, { useState } from 'react';
import { render } from 'react-dom';

import { useCallbagInput, useCallbagOutput } from './CallbagHooks'
import { createEngine } from './engine'

const App = () => {
  const [ engine ] = useState(createEngine)
  const buttonClick = useCallbagInput(engine.increments$)
  const counter = useCallbagOutput(engine.counter$)

  return <div>
    <button onClick={buttonClick}>Click me</button>

    <span>Button was clicked {counter} times</span>
  </div>
}

render(<App />, document.getElementById('root'));

We put the streams in the state of the component (leaving it read-only), and connect them to React using the useCallbagInput / useCallbagOutput hooks, respectively. Let's see it in action!

Notice: you can examine the hooks implementation in the example above - it is the glue between the streams and React's state. The useCallbagInput is not even a real hook.

The above approach looks like an overcomplication - you can achieve the same with useState or useReducer in fewer, simpler lines of code. However, it accomplished something important - it encapsulated the logic of our app in a building block which resides outside of our React components. You can easily write tests against it, without any React component/rendering involved.

Next, let's try something more complex!

Second step: Calculator

We will build a calculator which sums two or more numbers and keeps track of the previous sums. Check the following prototype for a better idea:

Let's see what are the requirements for our engine:

We need:

something to process the clicks of the number buttons
something to process the click of the 'sum' button

and

something to update the numbers to be summed
something to update the calculations so far

From the engine's point of view, these are two input streams and two output streams. The input streams push data into the store (numbers, sum); the output streams output the results to the consumer (in our case, the React UI). Thinking in Redux terms (although not exact mapping), the input streams are the actions, while the output streams are the state. Don't get hung up on this parallel though.

Build the Engine

import subject from "callbag-subject"
import pipe from "callbag-pipe"
import map from "callbag-map"
import scan from "callbag-scan"
import buffer from "callbag-buffer"
import cut from "callbag-cut"

const numbersToSumString = numbers => numbers.join('+')

const sum = numbers => numbers.reduce((a, b) => a + b)

export const createEngine = () => {
  const numbersToSum$ = subject();
  const calculate$ = subject();

  const solutions$ = pipe(
    numbersToSum$,
    buffer(calculate$),
    map(numbers => `${numbersToSumString(numbers)}=${sum(numbers)}` ),
    scan((solutionsSoFar, solution) => [solution, ...solutionsSoFar], [])
  )

  const pendingNumbers$ = pipe(
    numbersToSum$,
    cut(calculate$),
    map(numbersToSumString),
  )

  return {
    // input
    numbersToSum$,
    calculate$,

    // output
    solutions$,
    pendingNumbers$
  }
}

We finally got to the fun parts! We combine the two input streams (numbersToSum$ and calculate$) in different ways in order to build our output streams - the calculated solutions and the numbers in the current unfinished solution.

The part which I appreciate the most about the implementation is that the engine is stateful, but we don't deal with that manually. Instead, we use the scan, buffer and cut operators to the job for us.

The next example connects the engine to the React view we started with:

In addition to the hooks from the Counter example, we put the engine in a context and then access the streams we need in the child components. Notice that, unlike Redux, the streams do not change over time. Instead, they act like permanent pipes which take care of accepting inputs from events in the various parts of the app and delivering the updated values where necessary.

Why Callbag and not RxJS?

The engine implementation would look mostly the same if we used RxJS. For the purposes of the tutorial, callbag felt simpler (everything is a function!).

Why should I care about that? React already has hooks, Redux, MobX, etc.?

Indeed - however, consider this more of a thought-provoking exercise on how we can program outside of the framework. Compared to the traditional imperative approach, coding your logic with streams feels like programming on a higher level. Notice how the implementation above has zero if statements, no variable reassignments, and no loops. Instead, we have a few pure functions composed with pre-made operators.

I want to learn more!

An excellent resource to get you excited is RxMarbles - without any actual code, it shows the power of the Rx observables. Most, if not all of the Rx operators have their counterparts implemented in Callbag.

Reactive Programming for React Developers - the Absolute Beginner Guide

Petyo Ivanov — Fri, 31 May 2019 07:42:15 +0000

Intro

In the my recent adventure, I decided to find the one true way to manage the internal state of a complex React component. A virtualized list is a complex affair. Users scroll and load new data, items resize because images load, devices change orientation. Sometimes, all of the above happens simultaneously.

I started with a redux-like store. A couple of days later, I ended up in entangled nested reducers and a bunch of repetition I could not get rid of. The available tests could not help me figure out why the component was behaving in unexpected ways.

I was here, quite fast:

artist: Manu Cornet

There must be a better way. Or so, I thought.

Let's Try Reactive Programming! Enter RxJS

Figuring out RxJS while learning reactive programming was hard. RxJS is extremely powerful at the cost of being complex. A bunch of abstractions which did not immediately click or were named in the exact opposite way from how I understood them - hot and cold Observables, Observers, Subscribers, Subscriptions, and Schedulers, oh my. Nevertheless, I managed to plow through. Thanks to Learn RxJS and RxMarbles, the component store was re-done. (Don't dive into the resources above, remember them for later. They are long and awesome and get hard really fast. Finish this article first).

The result implementation was beautiful, 1/4 the size of the redux store, testable and reliable. Beauty is in the eye of the beholder of course. The first version of Virtuoso shipped with RxJS store implementation.

Looks awesome, they said. Not gonna use it, RxJS is huge, no way I am adding this as a dependency, they said. Sigh.

The Dunning-Kruger effect kicked in. I knew enough about reactive programming to replace RxJS with a small home-grown implementation. Better do this early, before I add more complex features.

It worked, bringing the usual amount of hard to trace bugs.

You are reinventing the wheel, they said. Check Callbag, they said. I should have asked earlier. Anyway, the home-grown solution was there, and it worked. Better is the enemy of good enough. Stop messing around and finish what you have started. Let me browse the Callbag docs really quick...

So let's cut the bullshit.

Reactive programming is programming with asynchronous data streams.
In a way, this isn't anything new. Event buses or your typical click events are really an asynchronous event stream, on which you can observe and do some side effects. Reactive is that idea on steroids. You are able to create data streams of anything, not just from click and hover events. Streams are cheap and ubiquitous, anything can be a stream: variables, user inputs, properties, caches, data structures, etc. For example, imagine your Twitter feed would be a data stream in the same fashion that click events are. You can listen to that stream and react accordingly.

On top of that, you are given an amazing toolbox of functions to combine, create and filter any of those streams. That's where the "functional" magic kicks in. A stream can be used as an input to another one. Even multiple streams can be used as inputs to another stream. You can merge two streams. You can filter a stream to get another one that has only those events you are interested in. You can map data values from one stream to another new one.

There we go. That's the starting point I think everyone needs. This is what inspired me to write this post.

What follows is what I consider the bare minimum of what you need to understand about reactive programming, presented as jest tests. I will stick to things which can be useful in React projects, where binding to a DOM element events directly does not make much sense. This is the full test suite - let's go through each test. We are using Callbag as the underlying implementation. However, all of the above would look mostly the same with RxJS. Don't worry if you don't know Jest. The assertions should be self-explanatory.

Subject, Subscriber and Observe

test("subject emits values to its subscribers", () => {
  const a = subject();

  const subscriber = val => expect(val).toEqual("foo");
  observe(subscriber)(a);
  // Ignore the "1" parameter for now
  a(1, "foo"); 
});

This pretty much captures the whole idea of reactive programming. In the above, we:

create a stream a, which in our case is a generic subject;
create a subscriber, which acts on the values coming from the stream(in this case, we verify that we received the correct value);
we attach the subscriber to the stream using observe;
we push "foo" in the stream a;

If the above makes sense to you, congratulations! The rest of the examples just add small blocks on top of that.

Behavior Subject

test("behavior subject emits previously pushed values to new subscribers", done => {
  const a = behaviorSubject("foo");

  a(1, "bar");

  const subscriber = val => {
    expect(val).toEqual("bar");
    done();
  }

  observe(subscriber)(a);
});

Next, we have the behavior subject. Its behavior is very similar to the vanilla subject, with one exception - the behavior subject is stateful. This means that attached subscribers will immediately be called with the last value of the subject. Also, it is constructed with an initial value. In a nutshell, subscribing to such subject means that you will be called immediately.

Behavior subjects are prevalent in the Virtuoso store implementation - that's where it keeps most of its state.

Pipe and Map

test("pipe and map transform the incoming stream values", done => {
  const a = subject();

  const subscription = val => {
    expect(val).toEqual(2);
    done();
  };

  const b = pipe(
    a,
    map(i => i * 2)
  );

  observe(subscription)(b);

  a(1, 1);
});

Passing values around is not much fun. Thanks to pipe and map, we create an output stream (b) which transforms and emits values coming from a.

Combine

test("combine takes values from two streams", done => {
  const a = subject();
  const b = subject();

  const subscription = vals => {
    expect(vals).toEqual([1, 2]);
    done();
  }
  const c = pipe(combine(a, b))

  observe(subscription)(c)

  a(1, 1);
  b(1, 2);
});

test("pipe, combine and map work together", done => {
  const a = subject();
  const b = subject();

  const subscription = val => {
    expect(val).toEqual(3);
    done();
  }
  const c = pipe(
    combine(a, b), 
  map(([aVal, bVal]) => aVal + bVal )
  )

  observe(subscription)(c)

  a(1, 1);
  b(1, 2);
});

combine is what I consider the last essential tool we need. It allows you to build an output stream which transforms incoming values from two or more input streams.

Bonus - `scan` and `sampleCombine`

The test suite includes two more tests that show how scan and sampleCombine work. If the examples so far make sense to you, you should have little trouble figuring them out.

Stay tuned for the next post, where we are going to build a simple store from subjects and integrate it with a React component. We will also talk about why the heck would one need to do that when you can use hooks, Redux, etc.

In the meantime, go through The introduction to Reactive Programming you've been missing from André Staltz. You can also fork the sandbox and add more tests for the some of callbag utilities listed in the Callbag Wiki. Share your forks in the comments!

Creating Beautiful Virtualized Lists with Material-UI and React Virtuoso

Petyo Ivanov — Tue, 28 May 2019 16:38:16 +0000

If you did not get the news, Material-UI v4 is out. Awesome announcement indeed; the Material Design system is amazing. And a mature, popular, open-source react library that implements the material design specs? We live in great times.

My goal with the React Virtuoso library is to provide "chromeless" engine components which complement and power-up exiting UI libraries with advanced virtualization behavior. Version 0.6 allows you to replace the component structure with components of your choice. Today, we will use the Material-UI list components as containers in React Virtuoso to build a Material-looking virtualized list.

The final result looks like this:

Ready? Go!

Step 1: Hello World

A relatively modest step - we power up a new Stackblitz react project, and add the starter Virtuoso example - a list with 500 Item {index} items. the Virutoso component configuration is easy; you pass some dimensions (you can pass anything, including %, rem, etc), the total of items to render, and the item render prop. The component figures out the rest for you.

Step 2: Add material UI

Let's make that list stylish! By default, Virtuoso renders its list container as a div, and each individual item in a div wrapper. We swap those for their Material-UI counterparts by specifying the ListContainer and ItemContainer properties. They render ul and li under the hood - works for us!

Step 3: Add real (fake) data

Displaying Item 40 is quite boring, and, most likely, not what you need in your project. Let's show real data. Or at least, something that looks more convincing. In the next step, we generate a set of 500 user records using the awesome faker library and display them in the list. We also make the list structure more complex by adding an avatar to each item. To keep up with the trends, we separate the data from the presentation by putting the user record generation in a reusable hook.

Final step - endless scrolling

This is the most interesting part of the exercise. Loading 500 records in a single step is not a good idea. Instead, we start the list with 50 records, and add more when the user scrolls down. The hook we did in the previous step comes in handy; we extend it further to expose a loadMore method which simulates a roundtrip to the server and appends more records to the existing array. The loadMore call is wired up to Virtuoso's endReached callback property.

We also introduce two other minor enhancements: a footer which displays loading... in case the user scrolls too fast, and an overscan property which controls the eagerness of the load more behavior.

And, we are done! Was it shorter and simpler than expected? Are you looking for more? If so, go and check the advanced example in the docs - In addition to the above, it shows grouping with sticky items, optimizing the scrolling experience by hiding the avatars during scrolling.

React Virtuoso - an elegant virtual list component

Petyo Ivanov — Tue, 14 May 2019 09:08:32 +0000

Hey everyone,

after some struggle with large data sets, i decided to scratch my own itch and build a proper component that can display variable height items without much hassle - React Virtuoso. Please let me know what you think about the implementation and the feature set.

a few interesting details:

the component is written in typescript, and uses the tsdx scaffold.
the internal state is implemented with rxjs. propagating the observables changes works quite well with the hooks api.