n1ru4l / Graphql Live Query

Real-Time with GraphQL for any GraphQL schema or transport.

Read the blog post - Learn how operations are tracked

Packages in this Repository

Package	Description	Stats
@n1ru4l/in-memory-live-query-store	Live query implementation.
@n1ru4l/graphql-live-query	Utilities for live query implementations.
@n1ru4l/graphql-live-query-patch	Reduce live query payload size with JSON patches
todo-example-app	Todo App with state sync across clients.
@n1ru4l/socket-io-graphql-server	GraphQL over Socket.io - Server Middleware
@n1ru4l/socket-io-graphql-client	GraphQL over Socket.io - Client
todo-example-app	Todo App with state sync across clients.	-

Motivation

There ia no mature live query implementation that is not tied to any specific database or SaaS product. This implementation should serve as an example how live queries can be added to any schema with (almost) any GraphQL transport.

GraphQL already has a solution for real-time: Subscriptions. Those are the right tool for responding to events. E.g. triggering a sound or showing a toast message because someone poked you on Facebook. Subscriptions are also often used for updating existing query results on a client that consumes a data from a GraphQL API. Depending on the complexity of that data, cache update code can eventually become pretty bloated. Often it is more straight-forward to simply refetch the query once a subscription event is received.

In contrast to manual cache updates using subscriptions, live queries should feel magically and update the UI with the latest data from the server without having to write any cache update wizardry code on the client.

Concept

A live query is a query operation that is annotated with a @live directive.

query users @live {
  users(first: 10) {
    id
    login
  }
}

A live query is sent to the server (via a transport that supports delivering partial execution results) and registered. The client receives a immediate execution result and furthermore receives additional (partial) execution results once the live query operation was invalidated and therefore the client data became stale.

The client can inform the server that it is no longer interested in the query (unsubscribe the live query operation).

On the server we have a live query invalidation mechanism that is used for determining which queries have become stale, and thus need to be rescheduled for execution. In the future we might event be able to only re-execute partial subtrees of a query operation.

How does the server know the underlying data of a query operation has changed?

The reference InMemoryLiveQueryStore implementation uses an ad hoc resource tracker, where an operation subscribes to the specific topics computed out of the query and resolved resources during the latest query execution.

A resource (in terms of the reference implementation) is described by a root query field schema coordinate (such as Query.viewer or Query.users), , a root query field with id argument (Query.user(id:"1")) or a resource identifier (such as User:1). The latter is by default composed out of the resource typename and the non nullable id field of the given GraphQL type.

For the following type:

type User {
  id: ID!
  name: String!
}

Legitimate resource identifiers could be User:1, User:2, User:dfsg12. Where the string after the first colon describes the id of the resource.

In case a resource has become stale it can be invalidated using the InMemoryLiveQueryStore.invalidate method, which results in all operations that select a given resource to be scheduled for re-execution.

Practical example:

// somewhere inside a userChangeLogin mutation resolver
user.login = "n1ru4l"
liveQueryStore.invalidate([
  // Invalidate all operations whose latest execution result contains the given user
  `User:${newUser.id}`,
  // Invalidate query operations that select the Query,user field with the id argument
  `Query.user(id:"${newUser.id}")`,
  // invalidate a list of all users (redundant with previous invalidations)
  `Quer.users`
]);

Those invalidation calls could be done manually in the mutation resolvers or on more global reactive level e.g. as a listener on a database write log. The possibilities are infinite. 🤔

For scaling horizontally the independent InMemoryLiveQueryStore instances could be wired together via a PubSub system such as Redis.

How are the updates sent/applied to the client

The transport layer can be any transport that allows sending partial execution results to the client.

Most GraphQL clients (including GraphiQL) have support for Observable or async iterable data structures which are perfect for describing both Subscription and Live Queries. Ideally a GraphQL Live Query implementation uses a AsyncIterable or Observable for pushing the latest query data to the client framework that consumes the data.

List of compatible transports/servers

List of known and tested compatible transports/servers. The order is alphabetical.

Package	Transport	Version	Downloads
@n1ru4l/socket-io-graphql-server	GraphQL over Socket.io (WebSocket/HTTP Long Polling)
graphql-helix	GraphQL over HTTP (IncrementalDelivery/SSE)
graphql-ws	GraphQL over WebSocket