@grafoo/core

Grafoo core

Install

$ npm i @grafoo/core && npm i -D @grafoo/babel-plugin

Setup

Assuming you already have babel installed, the only additional step required to build an application with Grafoo is to configure @grafoo/babel-plugin. The options it accepts are idFields - the fields Grafoo will take to build unique identifiers, and schema, which is a relative path to your schema file.

{
  "plugins": [
    [
      "@grafoo/babel-plugin",
      {
        "schema": "schema.graphql",
        "idFields": ["id"]
      }
    ]
  ]
}

API

@grafoo/core consists of a module that exports as default function a factory to create the client intance and a submodule that exports that graphql template tag.

graphql template tag

From @grafoo/core/tag is exported the graphql or gql tag that you'll use to create your queries. On build time every time you use that tag it will be replace with a special object that assists the client on the caching process. It is a dummy module and if you do not have @grafoo/babel-plugin it will thow you an error.

Example

import gql from "@grafoo/core/tag";

const USER_QUERY = gql`
  query($id: ID!) {
    user(id: $id) {
      name
    }
  }
`;

// will be transformed to this on build time

const USER_QUERY = {
  query: "query($id: ID!) { user(id: $id) { name id } }"
  paths: {
    "user(id:$id){name id}": {
      name: "user",
      args: ["id"]
    }
  }
}

createClient factory

createClient accepts as arguments a transport function to comunicate with your GraphQL API and an options object. This options are:

Option	Type	Required	Description
idFields	string[]	false	fields Grafoo takes to build unique identifiers
initialState	object	false	a initial state to hydrate the cache. It can be produced by the flush client method

Example

import createClient from "@grafoo/core";

function fetchQuery(query, variables) {
  const init = {
    method: "POST",
    body: JSON.stringify({ query, variables }),
    headers: {
      "content-type": "application/json"
    }
  };

  return fetch("http://some.graphql.api", init).then(res => res.json());
}

const client = createClient(fetchQuery);

IdFields

IdFields is homologous to the @grafoo/babel-plugin option with the same name. You don't have much to worry about it because it's automatically inserted by @grafoo/babel-plugin on every client instantiation. It is an array of fields that Grafoo will take to build unique identifiers.

Say you want to consume a query like so:

{
  me {
    name
  }
}

If idFields is configured with ["id"]. This query will be transformed to this:

{
  me {
    name
    id
  }
}

Then the client, when caching this data, will use this id field to store it.

Example

const client = createClient(fetchQuery, {
  idFields: ["id", "__typename"]
});

GrafooClient

the createClient factory returns a client instance with some methods:

Name	Description
execute	executes queries
read	reads queries from the cache
write	writes queries to the cache
listen	takes a listener callback and notify for cache changes
flush	dumps the internal state of the instance cache

GrafooClient.execute

This method receives as arguments a query object created with the @grafoo/core/tag template tag and optionally a GraphQL variables object. It returns a promise that will resolve with the data requested or reject with a list of GraphQL errors.

Example

const variables = { id: 123 };

client.execute(USER_QUERY, variables).then(data => {
  console.log(data); // { "user": { "name": "John Doe", "id": "123" } }
});

GrafooClient.write

The write method as the name implies writes to the cache. It takes as argumets the query object, an optional variables object and the data to be stored.

Example

client.execute(USER_QUERY, variables).then(data => {
  client.write(USER_QUERY, variables, data);
});

GrafooClient.read

The read method takes as arguments the query object and optionally a variables object. It returns an object with three properties: data, a tree structured object shaped according to your query tree, objects a flat structured object containing every node on your query indexed by a unique id created with the idProps option passed on client instantiation and a partial property that flags if the data is partially cached or not.

Example

client.read(USER_QUERY, variables);
// {
//   "data": {
//     "user": {
//       "name": "John Doe",
//       "id": "123"
//     }
//   },
//   "objects": {
//     "123": {
//       "name": "John Doe",
//       "id": "123"
//     }
//   },
//   partial: false
// }

GrafooClient.listen

listen takes a listener callback as argument. Whenever the cache is updated that listener is called with the objects that were inserted, modified or removed.

Example

function listener(objects) {
  console.log(objects);
}

const unlisten = client.listen();

client.write(USER_QUERY, variables, data);

unlisten(); // detaches the listener from the client

GrafooClient.flush

The flush method dumps all of the data inside the cache in it's raw state, producing a snapshot. It is to be used in mainly on the server producing, a initial state that can be passed as an option to createClient on client side.

Example

// server.js
app.get("/", (req, res) => {
  res.send(`<script>_GRAFOO_INITIAL_STATE_=${JSON.stringify(client.flush())}_</script>`);
});

// client.js
const client = createClient(fetchQuery, {
  initialState: window._GRAFOO_INITIAL_STATE_
});

LICENSE

MIT