New data model/API layer

[richardolsson]

I'm writing this to start a discussion on whether we should replace/augment react-query with something else.

We have been using react-query as the main data/network layer for a while now, and put a lot of effort into making it nice to use and not have a lot of boilerplate. Throw mostly the work of @djbusstop we have created a mostly nice to use abstraction layer with custom hooks.

All in all, however, I don't think it's working great.

In this discussion I'm going to first post the issues I have with react-query, and then some ideas I have for alternative solutions.

[richardolsson]

My issues with react-query for our use case

1. Lack of data understanding

The react-query cache understands nothing about the data it's storing. This is perfectly fine for a cache, but not great when we're using it as a data model. Maybe in less complex applications those two perspectives overlap enough that it doesn't really matter, but I believe that in our use case we are currently being limited by this lack of awareness.

For example, imagine a Zetkin View into which you load 1000 rows. Then you edit a single one of those rows using a react-query mutation. The encouraged behavior with react-query is to invalidate the cache of the 1000 rows when the mutation succeeds, causing all 1000 rows to be refetched even though only one changed.

It's possible to go into the data cached for the 1000 row request and update that specific row instead of invalidating the entire request cache, but doing so is not easy, and error prone, which brings me to my next gripe.

2. Poor support for testing

The issue described above is a typical "model" responsibility. Updating a list after a request succeeds is logic that can fail, and should be tested. But testing code that relies on react-query is very difficult, because react-query is both network and model layer in one.

The only way that the network side could be taken out of our react-query code is if we replaced the callbacks passed to useQuery() etc, but they are hidden deep inside our wrappers, so doing so is not practical.

Whenever we have react-query logic (e.g. post-mutation invalidation) it is currently being tested by integration tests (Playwright). Compared to unit tests, the integration tests are slow to run, and complicated to set up, write and maintain. So we tend not to test a lot of edge cases, and writing those tests is generally thought of as something annoying that we'd rather not do (but do anyway because of protocol).

3. Does not encourage modularity

Along with the lack of separation between network and cache, react-query also does not encourage separation between interface and cache. This has made it unnecessarily difficult for us to build things like "draft pages" for creating objects.

With a modular (e.g. object-oriented) framework it should be super easy to build two models – one that goes to the API and one that only stores data locally – and plug them in and out of the same interface. Instead, because "model data" is usually retrieved using useQuery(), it's not that simple at all.

4. Lack of state structure (and unnecessary separation from non-network state)

I recently had to build a new feature and then fix some bugs in the old Generation 2 Call frontend. In doing so, I got to re-experience the joy of working with (especially debugging) state in redux.

While react-query sure is much better at caching, the lack of structure in the state can be very annoying. The same data can easily become duplicated in many places (see 1), the keys are theoretically structured but really just serialized to strings in a flat key/value store, and although the react-query dev tools are great at what they do, there is no good way to "navigate" or track changes to the cache.

For Gen3 we moved away from redux towards react-query for all network related state (i.e. cached data), encouraged by some shifting winds in the developer community. The idea was that not all state is the same, and cached server state is really something different from "app state".

But really, in rich apps, being able to easily communicate between "app state" and server state actions is actually very useful. Things like navigating after something is created or deleted, storing some data in LocalStorage before submitting it to the server, displaying a global loading bar etc are features that are made easier by having most state in the same place.

5. Boilerplate

IMO react-query has a lot of boilerplate. This has been made much better in our use case by the work of @djbusstop, but we've had to do this by working against react-query, not with it.

More than once we've found ourselves in situations where the wrappers we use have to be modified to support some new use case, but modifying them has been tedious because of the complexity imposed by react-query.

In those situations I've often been enticed to just circumvent the wrappers for that specific edge case, and then I'm back to the boilerplate after all.

I'm not sure if this would be much better with a different solution, but I think so, and at least it can't get much worse.

What's good about react-query?

There are obviously also a lot of things that are great with react-query, that I would like to keep if we're moving to something else.

• Caching and invalidation is great, which is to be expected from a caching library
• Hooks, when not overused too deep in the tree, is IMO a great way to access the store from a component
• Global and local event callbacks, e.g. onSuccess for the entire queryClient vs a single query vs a single request to that query is a nice way to do some things always (e.g. show NProgress loading bar) and others only sometimes.
• Type support in general is great. Everything has generics for the types of data that will be passed/returned.
• React Suspense is supported, or at least possible to implement
• The dev tools are good at what they do, i.e. inspect the current state of the cache

In my subsequent posts in this thread I'm going to offer some thoughts on what a replacement might look like, but I'd be happy to get some feedback on my react-query review in the comments below this post. 😊

[richardolsson]

Proposal 1

Here's my proposal for what an alternative might look like. Let's call it "Proposal 1". 😊

Overview

My proposal sorts code into three layers.

• The UI layer contains React components, some of which connect themselves to the next layer ("connected"), and others which only act upon models passed to them via props ("dumb").
• The Model layer contains model classes that hold logic for things like caching, filtering lists, storing draft data until submission etc, and also a redux store which stores the actual data in plain objects.
• The Source layer contains code to handle data sources, mainly adapter classes through which the models can interact with the REST API.

Feature: Object-oriented design

The model and source layers are designed according to object-oriented principles. For example, when creating a model that needs to be able to interact with the API, it's passed an API adapter object, e.g. (pseudo-code):

//...
const apiClient = new BrowserAPIClient();
const campaignApi = new CampaignApiAdapter(apiClient);
const campaignsModel = new CampaignsModel(reduxStoreAdapter, campaignApi);

const campaigns = await campaignsModel.getActiveCampaigns();

This design is powerful because it makes it very easy to replace the apiClient with a mock, to be able to test the UI and model layer together, without having to do it in a fully integrated environment using Playwright.

Benefits

• Testable by replacing parts of the system with mocks/stubs
  • Test "dumb" components by passing simple data
  • Test "connected" components + models + store by providing a model with mocked/stubbed adapters
  • Test model layer in isolation (models+store without UI) by running model code directly in tests, with mocked/stubbed adapters
  • Test full integration using playwright by network mocking using moxy
• Code can be reused for common patterns (e.g. lists of items)

Feature: Redux comeback (for all state)

I'm suggesting that we bring back redux for the storage of data. The models would then use redux actions and the redux store to modify and provide data.

One can think of the store as the "database" and the models as the "ORM", if one is so inclined.

This allows us to use all of the developer tooling that redux provides, and to also have a central storage for all data which is very useful to achieve things like updating data in one part of the system based on what happens elsewhere, without strong coupling, e.g. updating the breadcrumbs when the name of something changes, or updating the row of a view when a tag is applied to a person.

The store would contain "bare objects", and the models would use (or just return) the data from those objects. For example, a CampaignModel might represent a specific campaign with some ID, and it would get that data using the ID, from the store which contains a list of many campaigns.

Benefits

• Powerful debugging
• App-global communication

Caching in the models

We swapped to react-query from redux because we wanted to think of the local representation of server data more like a cache. But that doesn't mean we have to use a caching library. We can still store the data in redux, and do caching in the models.

If a model has a load() function, it could go to the store to look at the data to see if it's already there, and if we keep timestamps in the store it could check that it's not too old, before retrieving it from the API.

In most cases we will be able to reuse the same (simple) code for this. But in some cases we will want more complex caching logic, and with this approach that will be quite simple, because that code will be self-contained within the model class.

Benefits

• Get the same caching capabilities we had in react-query (and were missing in Gen2)
• Flexibility to use whatever caching strategy makes sense for each use case

Simple React Suspense

The model layer can very easily implement the necessary logic to use React Suspense for handling asynchronously available data, showing loading spinners etc.

Granted, I've never implemented Suspense like this before, but I'm pretty sure it should be possible to do this:

const Container = () => {
  // Not sure how connecting to models would work, but something like this?
  const campaignModel = useModel(CampaignModel, 25);

  useEffect(() => {
    // On first render, start loading the campaign
    campaignModel.load();
  });

  return (
    <React.Suspense fallback={ <Spinner /> }>
     <CampaignCard campaignModel={campaignModel} />
    </React.Suspense>
  );
}

const CampaignCard = ({ campaignModel }) => {
  // This will fail and cause suspense if not loaded yet
  const data = campaignModel.data;

  return (
    <h1>{data.title}</h1>
  );
}

class CampaignModel {
  private _promise: Promise<CampaignData> | null;
  private _data: CampaignData | null;

  constructor(store: ReduxStoreAdapter, api: ApiAdapter, id: number) {
    super(store, api);
    this._id = id;
    this._data = null;
  }

  async load() {
    // TODO: Caching
    this._promise = this._api.loadCampaign(this._id);

    // TODO: The data should actually go in the redux store, not just end up here
    this._data = await this._promise;
  }

  get data(): CampaignData {
    if (!this._data) {
      // Throw promise to trigger React Suspense
      throw this._promise;
    }

    return this._data!;
  }
}

In conclusion

This approach separates code into three concerns:

• Presentation (React components)
• Logic and data (Model classes and redux data store)
• Data source (CRUD against API, LocalStorage or whatever)

In doing so, I believe that we will get more testable and scalable code, and whatever increase in boilerplate we incur will be manageable through object-oriented patterns for code reuse.

Eager to get feedback, here or elsewhere. 😊

[richardolsson]

I have started implementing a prototype to test my ideas in #805.

[richardolsson]

This was implemented, caused a number of issues, and was then ditched in favor of a variation where normal react hooks replace the model and repo (adapter).