Simple Fetch Cache

This module performs fetch requests using the node-fetch package, offering some basic caching functionality.

The motivation behind it is to have a simple but functional module to avoid hitting the live servers more than needed / allowed (ie. using an API with a quota)

Simple fetch cache calls the requested url and cache the results in memory using its own Map Object.

The reply is cached only if the server issue a 200 status code http response. Also the reply from the module indicates if the request comes from the cache:

// First request

> const {fetch} = require('simple-fetch-cache')
> const wikiprefix = 'https://en.wikipedia.org/w/api.php?action=query&format=json'
>
> fetch(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`).then(r => console.log(r))
> { reply:
   { batchcomplete: '',
     query: { normalized: [Object], pages: [Object] } },
  headers:
   { date: [ 'Sat, 29 Dec 2018 20:27:44 GMT' ],
     'content-type': [ 'application/json; charset=utf-8' ],
     server: [ 'mw1286.eqiad.wmnet' ] },
  status: 200,
  cached: false }

// Next request
> fetch(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`).then(r => console.log(r))
> { reply:
   { batchcomplete: '',
     query: { normalized: [Object], pages: [Object] } },
  headers:
   { date: [ 'Sat, 29 Dec 2018 20:27:44 GMT' ],
     'content-type': [ 'application/json; charset=utf-8' ],
     server: [ 'mw1286.eqiad.wmnet' ] },
  status: 200,
  cached: true }

The module only has an external node-fetch dependency to fetch the requested urls and Jest as dev dependency to run the tests.

Install

You can install with [npm]:

$ npm install --save simple-fetch-cache

Usage

The module provides two main functions: fetch to get the required url and cache it if possible and fetchFresh to get a fresh copy of the url and refresh the cache. So following up with the previous example

// First request

> const {fetch, fetchFresh} = require('simple-fetch-cache')
> const wikiprefix = 'https://en.wikipedia.org/w/api.php?action=query&format=json'
>
> fetch(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`).then(r => console.log(r))
> { reply:
   { batchcomplete: '',
     query: { normalized: [Object], pages: [Object] } },
  headers:
   { date: [ 'Sat, 29 Dec 2018 20:27:44 GMT' ],
     'content-type': [ 'application/json; charset=utf-8' ],
     server: [ 'mw1286.eqiad.wmnet' ] },
  status: 200,
  cached: false }

// Next request
> fetch(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`).then(r => console.log(r))
> { reply:
   { batchcomplete: '',
     query: { normalized: [Object], pages: [Object] } },
  headers:
   { date: [ 'Sat, 29 Dec 2018 20:27:44 GMT' ],
     'content-type': [ 'application/json; charset=utf-8' ],
     server: [ 'mw1286.eqiad.wmnet' ] },
  status: 200,
  cached: true }

// Fresh request

> fetchFresh(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`).then(r => console.log(r))
> { reply:
   { batchcomplete: '',
     query: { normalized: [Object], pages: [Object] } },
  headers:
   { date: [ 'Sat, 29 Dec 2018 20:38:49 GMT' ],
     'content-type': [ 'application/json; charset=utf-8' ],
     server: [ 'mw1342.eqiad.wmnet' ] },
  status: 200,
  cached: false }

Response format

As exposed in the previous example, the module returns in the response an object with the following 4 parameters:

Parameter	Description
reply	Message body from the server, converted to JSON if the mime-type is application/json, String if the type is text/html. Otherwise it will return a Buffer so you can further deal with it (ie. pipe image to a file)
headers	Abridged version of the headers, including date, server, content-type & content-length
status	Status code returned from the server (ie. 200, 404, 500 or 418)
cached	Boolean from simple-fetch-cache indicating if the request is cached (true or false)

Time to live (TTL)

All the requests cached in memory will persist there as long as the process in running. Nevertheless if you require the cache to expire after X miliseconds, you can pass it as a second parameter to the fetch function:

// Cache will expire after 1 hour.

> const {fetch} = require('simple-fetch-cache')
> const wikiprefix = 'https://en.wikipedia.org/w/api.php?action=query&format=json'
> const onehourMsec = 3600000
> fetch(`${wikiprefix}&prop=coordinates&utf8=&titles=dublin`, onehourMsec).then(r => console.log(r))

License

Copyright © 2018, Juan Convers. Released under the MIT License.