FilamentQL

FilamentQL is a lightweight caching library for GraphQL queries that utilizes a parsing algorithm to detect differences between incoming queries and existing data stored within the cache. The library offers tools for both client and server side caching as well as tools for offline mode.

FilamentQL's npm package can be downloaded here

Server-Side Caching

On the server-side, FilamentQL provides a GraphQL endpoint for your Express server with user-defined type definitions and resolvers, and creates a caching layer via a local Redis instance. When a client makes a request, FilamentQL checks the Redis cache for any previously stored data that matches the request. Through a parsing algorithm, FilamentQL then takes the incoming query and identifies any dissimilarities, and makes a subsequent query for just those dissimilarities to the database. Whenever possible, FilamentQL merges data coming back from the database with data from Redis cache and sends it back to the client:

Client-Side Caching

On the client-side, FilamentQL behaves similarly. For its local cache implementation, FilamentQL utilizes session storage, a built-in property on the browser's window object, which allows data to persist throughout page refreshes.

Offline Mode

FilamentQL also supports an offline mode. If the user gets disconnected from the server, all mutations made when the internet is down will be stored in a queue. At a set interval, FilamentQL checks if the network is back online. Whenever the user is back online, FilamentQL dequeues and sends each mutation to the server. Subsequently, the data that comes back from server will update the state and re-render the frontend components. What the user experiences and sees on their end is a seamless re-syncing of information when they come back online.

Installation

1. Redis

FilamentQL utilizes Redis for its server-side caching. If Redis is not already installed on your machine:

• Install on Mac using Homebrew:
  • In the terminal, enter

    brew install redis

  • When installation completes, start a redis server by entering

    redis-server

  • By default redis server runs on

    localhost:6379

  • To check if your redis server is working: send a ping to the redis server by entering the command

    redis-cli ping

    , you will get a

    PONG

    in response if your redis server is working properly.
• Install on Linux or non-Homebrew:
  • Download appropriate version of Redis from redis.io/download
  • Follow installation instructions
  • When installation completes, start a redis server by entering

    redis-server

  • By default redis server runs on

    localhost:6379

  • To check if your redis server is working: send a ping to the redis server by entering the command

    redis-cli ping

    , you will get a

    PONG

    in response if your redis server is working properly.

2. FilamentQL

Check out our npm package

npm install filamentql

Instructions

FilamentQL comes with

filamentql/client

filamentql/server

On client side,

filamentql

useFilamentQuery

useFilamentMutation

Both abstract away how to fetch queries and mutations and automatically update state when data is returned from server.

Client Example

import React, { useState } from 'react';
import { useFilamentQuery, useFilamentMutation } from 'filamentql/client';

const query =   query {     todos {       id       text       isCompleted     }   };
const mutation = (text) =>   mutation {     addTodo(input: { text: "${text}" }) {       id       text       isCompleted     }   };
const App = () => {
  const [value, setValue] = useState('');
  const { state: todosQuery } = useFilamentQuery(query);
  const [callAddTodoMutation, addTodoResponse] = useFilamentMutation(
    mutation,
    () => {
      // this callback is invoked when data is returned from server
      // this is a good place to update relevant state now with new data
      console.log(addTodoResponse.addTodo);
    }
  );
  const handleSubmit = (event) => {
    event.preventDefault();
    callAddTodoMutation(value);
    setValue('')
  };
  const handleChange = (event) => setValue(event.target.value)
  return (
    

      
        
        New todo
      
      

        {todosQuery &&
          todosQuery.todos.map((todo) => )}
      
    
  );
};

export default App;

Server Example

FilamentQL achieves the caching ability via Express middleware

/filament

/graphql

Since

useFilamentQuery

/filament

/filament

And make sure to mount your GraphQL server at route

/graphql

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const redis = require('redis');

// Redis Setup
const client = redis.createClient();
client
  .on('error', (err) => console.log('Error: ' + err))
  .on('connect', () => console.log('Redis client connected'));
// FilamentQL Setup
const filamentMiddlewareWrapper = require('filamentql/server');
const filamentMiddleware = filamentMiddlewareWrapper(client);
// Express setup
const app = express();
const PORT = 4000;
const schema = require('./schema');
app.use(express.json());
app.use('/filament', filamentMiddleware);
app.use(
  '/graphql',
  graphqlHTTP((req) => ({
    schema,
    graphiql: true,
    context: {
      req,
    },
  }))
);
app.listen(PORT, () => console.log(GraphQL server is on port: ${PORT}));

Contributors

FilamentQL is an open-source NPM package created in collaboration with OS Labs and developed by - Andrew Lovato - Chan Choi - Duy Nguyen - Nelson Wu

More infomation about FilamentQL can be found at filamentql.io

Notes

• Currently, FilamentQL v1.0 can only cache and parse queries without arguments, variables, or directives and do not support caching for mutation.