@quell/client

@quell/client is an easy-to-implement JavaScript library providing a client-side caching solution and cache invalidation for GraphQL. Quell's schema-governed, type-level normalization algorithm caches GraphQL query responses as flattened key-value representations of the graph's nodes, making it possible to partially satisfy queries from the client-side cache storage, reformulate the query, and then fetch additional data from other APIs or databases.

@quell/client is an open-source NPM package accelerated by OS Labs and developed by Cassidy Komp, Andrew Dai, Stacey Lee, Ian Weinholtz, Angelo Chengcuenca, Emily Hoang, Keely Timms, Yusuf Bhaiyat, David Lopez, Sercan Tuna, Idan Michael, Tom Pryor, Chang Cai, Robert Howton, Joshua Jordan, Jinhee Choi, Nayan Parmar, Tashrif Sanil, Tim Frenzel, Robleh Farah, Angela Franco, Ken Litton, Thomas Reeder, Andrei Cabrera, Dasha Kondratenko, Derek Sirola, Xiao Yu Omeara, Nick Kruckenberg, Mike Lauri, Rob Nobile, and Justin Jaeger.

Installation

Download @quell/client from npm in your terminal with npm i @quell/client. @quell/client will be added as a dependency to your package.json file.

Implementation

Let's take a look at a typical use case for @quell/client by re-writing a fetch request to a GraphQL endpoint.

Sample code of fetch request without Quell:

const sampleQuery = `query {
    countries {
        id
        name
        cities {
            id
            name
            population
        }
    }
}`


fetch('/graphQL', {
    method: "POST",
    body: JSON.stringify(sampleQuery)
})

costOptions = {
  maxCost: 50,
  maxDepth: 10,
  ipRate: 5 
}

To make that same request with Quell:

1. Import Quell with import { Quellify } from '@quell/client/dist/Quellify'
2. Instead of calling fetch(endpoint) and passing the query through the request body, replace with Quellify(endpoint, query, costOptions)

• The Quellify method takes in three parameters
  1. endpoint - your GraphQL endpoint as a string (ex. '/graphQL')
  2. query - your GraphQL query as a string (ex. see sampleQuery, above)
  3. costOptions - your cost limit, depth limit, and IP rate limit for your queries (ex. see costOptions, above)
  4. mutationMap - maps mutation names to corresponding parts of the schema.
     (For more information, see the Schema section in @quell/server README file)

And in the end , your Quell-powered GraphQL fetch would look like this:

Quellify('/graphQL', sampleQuery, costOptions, mutationMap)
  .then( /* use parsed response */ );

Note: Quell will return a promise that resolves into an array with two elements. The first element will be a JS object containing your data; this is in the same form as the response found on the 'data' key of a typical GraphQL response { data: // response }. The second element will be a boolean indicating whether or not the data was found in the client-side cache.

That's it! You're now caching your GraphQL queries in the client-side cache storage.

Usage Notes

• @quell/client now client-side caching speed is 4-5 times faster than it used to be.

• Currently, Quell can cache any non-mutative query. Quell will still process other requests, but all mutations will cause cache invalidation for the entire client-side cache. Please report edge cases, issues, and other user stories to us, we would be grateful to expand on Quells use cases!

For information on @quell/server, please visit the corresponding README file.