Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

graphql-norm-stale

dividab109MIT0.6.1TypeScript support: included

Staleness tracking for normalized GraphQL responses

graphql, normalization, denormalization, cache, stale

readme

graphql-norm-stale

npm version travis build Coverage Status code style: prettier MIT license

Staleness tracking for normalized GraphQL responses

How to install

npm install graphql-norm-stale --save

Introduction

When caching several normalized graphql responses it is sometimes helpful to mark some entries in the cache as stale. This package helps with tracking of stale entries.

Example usage

import { normalize, denormalize, merge } from "graphql-norm";
import { request } from "graphql-request";

// A plain JS object to hold the normalized responses
let cache = {};

const query = gql`
  query TestQuery {
    posts {
      id
      __typename
      title
      author {
        id
        __typename
        name
      }
      comments {
        id
        __typename
        commenter {
          id
          __typename
          name
        }
      }
    }
  }
`;

// Make a request to fetch the data
const response = request(query);

// Normalize the response
const normalizedResponse = normalize(query, {}, response);

// Merge the normalized response into the cache
cache = merge(cache, normalizedResponse);

// Later when we want to read a query from the cache
const cachedResponse = denormalize(query, {}, cache);

API

isStale()

The isStale() function takes a map of stale fields and a map of fields and checks if the fields are among the stale entries. The stale field map contains another map of fields for each key. This secondary map can only have entries with value true. The reason a map is used instead of an array is to have faster checking of membership of fields.

isStale(staleMap: FieldsMap, fields: FieldsMap): boolean

clearStale()

The clearStale() function takes a map of normalized GraphQL objects and a map of stale fields. It removes any fields in the staleness map that are present in the normalized map.

clearStale(normMap: NormMap, staleMap: FieldsMap): FieldsMap

invalidateEntity()

Creates a patch for invalidation of an entity.

invalidateField()

Creates a patch for invalidation of an entity's field.

applyPatches()

Returns a new map of stale fields with the patches applied. It needs the normMap in order to do recursive patches.

applyPatches(normMap: NormMap, staleMap: FieldsMap): FieldsMap

How to develop

Node version >=12.6.0 is needed for development.

To execute the tests run yarn test.

How to publish

yarn version --patch
yarn version --minor
yarn version --major

changelog

Change Log

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

v0.6.1 - 2020-03-29

Added

  • Include typescript source from src/ in published npm package.

0.6.0 - 2019-10-14

Changed

  • Return both the new stale map and the cleared fields from clearStale(). See PR #3.

0.5.0 - 2019-10-13

Added

  • Add patches for invlidation/staleness from the graphql-norm-patch package. See PR #2 for more info.

Added

  • Add patches for invlidation/staleness from the graphql-norm-patch package. See PR #2 for more info.

0.4.0 - 2019-10-13

Changed

  • Use the FieldsMap type from graphql-norm instead of StaleMap and StaleFields.
  • Rename updateStale() to clearStale().

0.3.0 - 2019-10-02

Added

  • Upgrade peer deps. The graphql package now has built-in types so no peer dependency is required for the @types/graphql package.

0.2.0 - 2019-09-29

Added

  • Upgrade dependency to graphql-norm.

0.1.2 - 2019-07-17

Fixed

  • Fix invalid dependencies.

0.1.1 - 2019-07-16

Fixed

  • Fix invalid dependencies.

0.1.0 - 2019-07-16

Added

  • Initial version.