🚀‍‍ Apollo 🧙 Enchanted InMemoryCache

🚀 Apollo 🛠‍ Tool represented as InMemoryCache 🧙 wrapper for 🗄 storing / 🗃 restoring ✅ selected only 🗂️ queries and for updating ⛓ linked / nested without 🆔 IDs

Content

• Install
• Usage
  • Creating Enchanted InMemoryCache Config
  • Basic usage
• API
  • SubscribedQuery
  • updateQueryHelper: Updater
• Types
• License

Install

$ npm install apollo-enchanted-cache-inmemory -S

or

$ yarn add apollo-enchanted-cache-inmemory

Usage

Creating Enchanted InMemoryCache Config

queries

1// * - example for fields as variables used in a query
2export const SomeQueryName = 'SomeQueryName';
3export const SomeQueryResponseField = 'response';
4export const SomeQueryResultField = 'result';
5export const QUERY_CREATED_BY_GQL_FUNCTION = gql`
6  query ${SomeQueryName} {
7    ${SomeQueryResponseField}: ExampleQuery {
8      ${SomeQueryResultField} {
9        someDataField {
10          ...ExampleFragment
11        }
12        ...ExampleFragment2
13      }
14    }
15  }
16  ${ExampleFragment}
17  ${ExampleFragment2}
18`;
19// * - example for fields as variables used in a query
20const SomeQueryName2 = 'SomeQueryName2';
21const SomeQueryResponseField2 = 'SomeQueryResponseField2';
22const SomeQueryResultField2 = 'SomeQueryResultField2';
23const SomeQueryDataField2 = 'SomeQueryDataField2';
24export const QUERY_CREATED_BY_GQL_FUNCTION_2 = gql`
25  query ${SomeQueryName2} {
26    ${SomeQueryResponseField2}: SomeDataQuery {
27      ${SomeQueryResultField2} {
28        ${SomeQueryDataField2} {
29          someDataField {
30            ...ExampleFragment
31          }
32          ...ExampleFragment2
33        }
34      }
35    }
36  }
37  ${ExampleFragment}
38  ${ExampleFragment2}
39`;
40// ** - example for no variables as fields used in a query
41export const QUERY_CREATED_BY_GQL_FUNCTION_3 = gql`
42  query SomeQueryName3 {
43    response: SomeDataQuery {
44      result {
45        ...ExampleFragment2
46      }
47    }
48  }
49  ${ExampleFragment2}
50`;

import queries and field names if exist

1import { updateQueryHelper } from 'apollo-enchanted-cache-inmemory';
2import {
3    SomeQueryName,
4    SomeQueryResponseField,
5    SomeQueryResultField,
6    SomeQueryName2,
7    SomeQueryResultField2,
8    SomeQueryResponseField2,
9    SomeQueryDataField2,
10    SomeQueryName3,
11    QUERY_CREATED_BY_GQL_FUNCTION,
12} from './queries';
13
14/** @type SubscribedQueries */
15const subscribedQueries = [
16  // #1
17  // each write into Apollo Cache with updating SomeQueryName
18  // will cause storing SomeQueryName asynchronously
19  {
20    name: SomeQueryName,
21    queryNode: QUERY_CREATED_BY_GQL_FUNCTION,
22    storeName: SomeQueryName,
23    nest: [SomeQueryResponseField], // optional
24    // optional XOR - retriever
25    retrieveField: SomeQueryResponseField,
26    // or
27    // optional XOR - retrieveField
28    retriever: () => ({...}) // type Retriever
29  },
30  // #2
31  // SomeQueryName2 will update SomeQueryName at SomeQueryResultField
32  // with deep merging all nested objects as updateType='deepMerge';
33  // data taken from
34  // SomeQueryName2.SomeQueryName2.SomeQueryResponseField2.SomeQueryResultField2
35  // is identical with SomeQueryName.SomeQueryResponseField.SomeQueryResultField
36  // * - example for fields as variables used in a query
37  {
38    name: SomeQueryName2,
39    queryNode: QUERY_CREATED_BY_GQL_FUNCTION,
40    updateName: SomeQueryName,
41    updater: (sourceQuery, targetQuery) => // type Retriever
42      updateQueryHelper({
43        sourceQuery,
44        sourcePath: [SomeQueryResponseField2, SomeQueryResultField2, SomeQueryDataField2],
45        targetQuery,
46        targetPath: [SomeQueryResponseField, SomeQueryResultField],
47        updateType: 'deepMerge',
48      }),
49  },
50  // #3
51  // SomeQueryName3 will update SomeQueryName at someDataField by replace
52  // as updateType='replace' by default;
53  // data taken from SomeQueryName3.response.result
54  // is identical with SomeQueryName.SomeQueryResponseField.SomeQueryResultField
55  // after updating SomeQueryName will be stored as tracked by #1 set
56  // ** - example for no variables as fields used in a query
57  {
58    name: 'SomeQueryName3',
59    queryNode: QUERY_CREATED_BY_GQL_FUNCTION,
60    updateName: SomeQueryName2,
61    updater: (sourceQuery, targetQuery) => // type Retriever
62      updateQueryHelper({
63        sourceQuery,
64        sourcePath: ['response', 'result'],
65        targetQuery,
66        targetPath: ['SomeQueryResponseField', 'result', 'someDataField'],
67        // updateType = 'replace' - by default
68      }),
69  },
70];
71// ...
72export default subscribedQueries;

Basic usage:

Initiation:

1import { InMemoryCache } from 'apollo-cache-inmemory';
2import ApolloClient from 'apollo-client';
3import { withClientState } from 'apollo-link-state';
4import { ApolloLink } from 'apollo-link';
5// if React Native
6// up to RN v0.58
7// import { AsyncStorage } from 'react-native';
8// since RN v0.59
9import AsyncStorage from '@react-native-community/async-storage';
10// if Web just use window.LocalStorage
11
12const inMemoryCache = new InMemoryCache({
13  // ...
14});
15// ...
16// for debug/log reasons
17/** @type Logs */
18const logs = {
19  logCacheWrite: true,
20  beforeHandlers: (cacheData, queryName) => {
21    console.log('beforeHandlers', queryName, cacheData.data);
22  },
23  beforeWrite: (cacheData, queryName) => {
24    console.log('beforeWrite', queryName, cacheData.data);
25  },
26  afterWrite: (cacheData, queryName) => {
27    console.log('afterWrite', queryName, cacheData.data);
28  },
29};
30
31const cache = createEnchantedInMemoryCache(
32  inMemoryCache, // instance of `InMemoryCache`
33  subscribedQueries, // config type `SubscribedQueries`
34  AsyncStorage, // or `LocalStorage` - main app storage, can be omitted if `GraphQLStorage` provided  
35  logs, // type Logs
36  // GQLStorage, - alternative to `GraphQLStorage` class, e.g. `Realm` (mobile) / `IndexedDB` (web) Wrapper
37);
38const GQLStorage = cache.GQLStorage; // to get `GQLStorage`
39const AppStorage = cache.AppStorage; // to get `AppStorage` - AsyncStorage or LocalStorage
40// ...
41const stateLink = withClientState({
42  cache,
43  resolvers,
44  defaults,
45});
46// ...
47const apolloClient = new ApolloClient({
48  cache,
49  link: ApolloLink.from([stateLink]),
50});
51// ...
52export default apolloClient;

Restoring data from storage into cache:

1// ...
2(async () => {
3  // ...
4  await cache.restoreAllQueries();
5  // ...
6})();

API

SubscribedQuery

Array<SubscribedQuery>

Prop	Type	Default	Note
name	string	(required)	query name which changes in Apollo cache will be tracked
queryNode	Query	(required)	Graphql Query created by Apollo's gql utility; type DocumentNode from Apollo Client
storeName	string	(semi-required)*	name used to store and restore in a storage formatted into 'Query:${storeName}' _* either storeName or updateName _
updateName	string	(semi-required)*	query name which will be updated _* either updateName or storeName _
nest	ObjectPath		path to Query field for nesting restored data
retrieveField**	string	(semi-required)*	path to Query field for _* in case if storeName provided _ ** - either retriever or retrieveField
retriever**	Retriever	(semi-required)*	function returns data for storing/restoring _* in case if storeName provided _ ** - either retriever or retrieveField
updater	Updater	(semi-required)*	function returns result with updated data for updating _* - in case if updateName provide

updateQueryHelper: Updater

Prop	Type	Default	Note
sourceQuery	QueryObject	(required)	Object Data of source Query tracked for updating target Query
sourcePath	ObjectPath	[]	path to Data source Query object field
targetQuery	QueryObject		Object Data of target Query should be updated
targetPath	ObjectPath	[]	path to Data target Query object field
updateType	UpdateTypesEnum	replace	replace - just replacing target Data at object some field by source Data rootMerge - merge target Data Object at object field by source Data with replacing tested Data deepMerge - merge target Object Data at all fields (sourcePath of sourceQuery) by source Object Data with same fields (targetPath of targetQuery); begins at source Object field and goes recursively into the depths
sourceDefault	any	null	data to be used for updating the target Object if no present in the source Object

Types

1type ArrayPath = Array<string | number>; // ['a', 'b', 0, 'c', 1]
2
3type ObjectPath = ArrayPath | string; // ['a', 'b', 'c', 0] | 'a.b.c.0'
4
5type QueryObject<Data> = { Object; Data }; // Query result data
6
7type Updater = <T1, T2, T3>(
8  sourceQuery: QueryObject<T1>,
9  targetQuery: QueryObject<T2>,
10) => QueryObject<T3>;
11
12type Retriever = <T1, T2, T3>(
13  sourceQuery: QueryObject<T1>,
14  targetQuery: QueryObject<T2>,
15) => QueryObject<T3>;
16
17type LinkedQuery = {
18  name: string;
19  queryNode: DocumentNode; // Apollo Query definition, returned by gql`...`
20  updateName: string;
21  updater: Updater;
22};
23
24type StoredQuery = {
25  name: string;
26  queryNode: DocumentNode; // Apollo Query definition, returned by gql`...`
27  storeName: string;
28  nest?: ObjectPath;
29  retrieveField?: string;
30  retriever?: Retriever;
31};
32
33type SubscribedQuery = LinkedQuery | StoredQuery;
34
35type SubscribedQueries = Array<SubscribedQuery>;
36
37type DepTrackingCache = { data: Object; depend: Object };
38
39type Logger = (cacheData: DepTrackingCache, queryName: String) => void;
40
41type Logs = {
42    logCacheWrite: Boolean,
43    beforeHandlers: Logger,
44    beforeWrite: Logger,
45    afterWrite: Logger,
46};
47
48enum UpdateTypesEnum {
49  replace = 'replace',
50  rootMerge = 'rootMerge',
51  deepMerge = 'deepMerge',
52}

License

Copyright (c) 2019 KosiakMD (Anton Kosiak)

Licensed under the The MIT License (MIT) (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://raw.githubusercontent.com/airbnb/react-native-maps/master/LICENSE

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.