@query-command/core

This package contains the core logic for creating a store for use within framework specific functions and hooks, like @query-command/react.

It exports a single function, createStore, which does this.

Why?

Libraries like @tanstack-query don't have a shared state across all queries; since each query is cached, the cache effectively represents the state.

This works fine on a small scale, but can be hard to maintain once you introduce more endpoints or rollbacks because you tend to find yourself writing wrappers around it to type your query keys etc.

It also means you have to manually manipulate the (potentially untyped) cache in order to perform optimistic updates.

I personally found this cumbersome, so I decided to try a new approach using a centralised store with queries and commands.

The Store

All of your external data should be kept within the Store. This will be data that you fetch from the backend, like a list of comments or posts for example.

This will dictate the structure of your State type.

Queries

You should define globally a set of queries which can be used to fetch data from your backend.

They're structurally similar to a reducer pattern where you dispatch actions.

For example, you might have two queries for getting your user data:

type MyQuery = { type: 'getUser'; id: string } | { type: 'getUsers' }

Your app then dispatches those queries and only those queries when trying to fetch your store's state.

Commands

You also probably want a way to mutate the state within your store.

This is done via commands.

Again, you define globally a set of commands which can be used throughout your app to mutate the state.

E.g.,

type MyCommand =
  | { type: 'createUser'; id: string; name: string }
  | { type: 'deleteUser'; id: string }

And within your command handler, you can immediately update the store's state "optimistically" while asnychronously performing the action.

How to use

The first step is to create a store using createStore.

You'll need some initial state, and a query and command handler.

The handlers will accept the query/command and then somehow update the store's state and potentially perform some async action.

Once you have your store, you're technically ready to use it within your app. However, it's recommended to use one of the framework packages to make it easier.

For example, see @query-command/react for information on how to create hooks in React (the only supported framework currently)