Map Cache

Map Cache is a singleton class that caches the data returned from any function for a specified amount of time (defaults to 5 minutes). If the data has been cached and has not expired, Map Cache will return the cached data without calling the function, if there is no cached data, it will call the function and store its returned data.

It works both on Node.JS and browsers that support btoa. Under the hood it uses the JS Map object to store data.

Motivation

I often have the need to cache the data I retrieve through API calls, but most of the packages available are outdated, not fully typed or don't do exactly what I need.

Tooling

• TypeScript
• Jest
• Babel
• Prettier
• Eslint

Tests

yarn test

The code has 100% coverage (tests are run both with node and jsdom to ensure compatibility with both).

Parameters

mapCache exposes the fetch, clear and size methods.

The fetch method takes as parameter an object with the following properties:

Property	Optional	Default	Description
key	no		An arbitrary string
params	yes		If the calback yelds differets data based on parameters, add them here
callback	no		The callback used to fetch the data you want to cache
expiresInSeconds	yes	300 (5 min)	How long the data will last in the cache

Example

1// <T> is the type of the data that will be returned from the callback
2const data = await mapCache.fetch<T>({
3  key: 'someKey', // an arbitrary string
4  params: { id: 0 }, // optional
5  callback: () => 'data', // the function returned data will be stored in the cache
6  expiresInSeconds: 10 // optional, defaults to 5 minutes
7})

The clear method clears the cache.

1mapCache.clear()

The size method returns the number of entries stored in the cache.

1console.log(mapCache.size())

Usage

Basic usage

1import mapCache from 'ts-map-cache'
2
3async function basicExample() {
4  // The callback can be a sync or async function, but the fetch method has to be always awaited
5  const someFunction = () => {
6    console.log('I have been called!')
7    return 'some_data'
8  }
9
10  // Since fetch is async, await it
11  const data1 = await mapCache.fetch<string>({ key: 'basicFunction', callback: someFunction })
12  console.log(`it called the function and returned the data: ${data1}`)
13
14  const data2 = await mapCache.fetch<string>({ key: 'basicFunction', callback: someFunction })
15  console.log(`it returned the cached data: ${data2}`)
16}
17
18basicExample()

With expiration

1import mapCache from 'ts-map-cache'
2
3async function basicExampleWithExpiration() {
4  const someFunction = async () => {
5    console.log('I have been called!')
6    return 'some_data'
7  }
8
9  const data = await mapCache.fetch<string>({
10    key: 'basicFunction',
11    callback: someFunction,
12    expiresInSeconds: 1
13  })
14  console.log(`it called the function and returned the data: ${data}`)
15
16  setTimeout(async () => {
17    const data = await mapCache.fetch<string>({ key: 'basicFunction', callback: someFunction })
18    console.log(`it re fetched the data: ${data}`)
19  }, 2000)
20}
21
22basicExampleWithExpiration()

With params

Params is useful when the same function returns different values based on the parameters it receives. Passing the parameters also to the fetch method will automatically build an unique id for that function/returned data. It can be useful, for example, with GraphQL query resolvers.

1import mapCache from 'ts-map-cache'
2
3async function basicExampleWithParams() {
4  const someFunction = async (params: { id: number }) => {
5    console.log(`I have been called with id ${params.id}!`)
6    return `some_data for id ${params.id}`
7  }
8
9  const params1 = { id: 0 }
10  const data1 = await mapCache.fetch<string>({
11    key: 'basicFunction',
12    callback: async () => someFunction(params1),
13    params: params1
14  })
15
16  console.log(`it called the function and returned the data: ${data1}`)
17
18  const params2 = { id: 1 }
19  const data2 = await mapCache.fetch<string>({
20    key: 'basicFunction',
21    callback: async () => someFunction(params2),
22    params: params2
23  })
24
25  console.log(`it called the function and returned the data: ${data2}`)
26}
27
28basicExampleWithParams()

With a network request

1import mapCache from 'ts-map-cache'
2import axios from 'axios'
3
4interface IData {
5  userId: number
6  id: number
7  title: string
8  completed: boolean
9}
10
11async function main() {
12  const getData = async () => {
13    return await axios
14      .get('https://jsonplaceholder.typicode.com/todos/1')
15      .then(({ data }) => data)
16      .catch((err) => console.log(err))
17  }
18
19  // This request will appear on the network tab of the dev tools
20  let data = await mapCache.fetch<IData>({ key: 'fetch', callback: getData })
21
22  // This will not since it's getting the cached data
23  data = await mapCache.fetch<IData>({ key: 'fetch', callback: getData })
24}
25
26main()