Skip to content

1. Introduction

Jump to bottom
Naveen Mathew edited this page Apr 8, 2024 · 2 revisions

What is Qwery?

Qwery is a collection of utilities to aid with declarative asynchronous state management. Asynchronous state is often persisted by relaying changes to an API. Qwery is most useful where data piles up, in most cases this is either on the frontend of a web application or on the backend where data is aggregated from multiple services.

It draws heavily upon TanStack Query and Redux, it's API should be fairly familiar to those familiar with either.

Comparison with TanStack Query:

  • Backend agnostic ✅
  • Auto refetching ✅
  • Parallel queries ✅
  • Automatic garbage collection ✅
  • Scroll recovery ✅
  • Render-as-you-fetch ✅
  • Offline support (possible but not OOB) ❌
  • Dedicated devtools ❌
  • Window focus refetching ✅
  • Dependent queries ✅
  • Paginated/cursor queries ✅
  • Request cancellation ✅
  • Prefetching ✅
  • SSR support ✅
  • Auto caching ✅
  • Polling/subscription queries ✅
  • Infinite queries ✅
  • Suspense ✅
  • Variable-length parallel queries ❌
  • Data selectors ❌
  • Broadcast updates between tabs and windows ✅
  • ~2 MB vs ~220 kB

Why?

Advantages of using Qwery:

  1. simpler mental model: you can dispatch changes to a Qwery, read the latest version of its state or peruse the transformations it has undergone, there's not much more to it

  2. it presents a universal model for managing asynchronous state allowing us to utilize the same data access patterns on both ends of the stack, Qwery also maintains the same shape across the various environments it supports

  3. does not require explicit cache management enabling a dispatch and forget approach to cache management

  4. centralizes state update logic: a side-effect of modelling things after Redux, centralizing state update logic helps with maintainability

  5. lighter weight: the scope of Qwery is unlikely to expand much beyond this, expect patch and maybe minor releases but major changes are not planned

  6. supports both REST and GraphQL APIs, with Qwery being considerably lighter than Apollo Client

In a nutshell

The central ideas in Qwery are dispatch and queryKey.

When changes are dispatched to a Qwery, the change event handler (onChange) is invoked with the next version of the state and the previous version of the state as arguments.

A model on the client usually corresponds to one or more models on the API which in turn corresponds to one or more models on the database. From these arguments, handlers can pick the relevant changes and apply them.

Specifying a queryKey enables caching and broadcasting updates between tabs and windows.

Qwery also exports a collection of utility functions to allow simple distributed transactions client-side, finding the difference between two versions of state (referential equality), retrying a query and monitoring the status of a query.

Clone this wiki locally