README.md

@quell/client

@quell/client is an easy-to-implement JavaScript library providing a simple, client-side caching solution and cache invalidation for GraphQL. Quell's client-side cache implementation caches whole queries as keys and saves their results as values in LokiJS.

@quell/client is an open-source NPM package accelerated by OS Labs and developed by Alex Martinez, Cera Barrow, Jackie He, Zoe Harper, 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)
})

To make that same request with Quell:

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

• The Quellify method takes in two parameters
  1. endpoint - your GraphQL endpoint as a string (ex. '/graphQL')
  2. query - your GraphQL query as a string (ex. see sampleQuery, above)

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

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

Note: Quell will return a promise that resolves into a JS object containing your data in the same form as a typical GraphQL response { data: // response }

That's it! You're now caching your GraphQL queries in the LokiJS 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 invalidate 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!

Future Additions

Goals for the future of Quell/client include:

• The caching logic for the server-side is multi-faceted, allowing for each query to be broken down into parts and have each data point cached individually. The client-side logic was not working as intended and was iterating through each data-point in the cache. As the cache grew in size this became extremely slow, and as such, the most recent iteration of quell removes much of the functionality to trim the file size down and prevent this issue. Additionally, the client-side was querying the database with every call, removing the benefit of a client-side cache.
  1. Translate the server-side caching logic to the client-side, translating RedisDB functions to similar LokiDB functions.
  2. Re-write much of the core logic, as LokiDB has significantly different functions and benefits than a Redis DB. Alternatively, as the logic is very simple right now, the DB could be transitioned from LokiDB to a newer DB technology that also offers in-memory storage for quick retrieval of data.
• The previous testing suites created during the original implementation of Quell/client were very thorough, but as the project grew in complexity and versins these tests were not updated to test the new functionality.
  1. Create new testing suites for the current implementation of the client-side cache.
  2. Restart TDD from the ground up while re-writing the caching logic.

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