README
= vapic
ifndef::env-github[]
endif::[] :toc!: ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]
https://github.com/bguiz/vapic[*Versioned API Cache^]
== Installation
[source,bash]
npm install vapic --save
== Usage
=== .set()
Stores the value in the cache, against the current version.
[source,javascript]
const vapic = require('vapic');
vapic.set({ url: '/foo', value: 'bar'), maxVersions: 3, // <1> redisClient: require('redis').createClient(), }, (err, result) => { /* ... */ });
<1> If maxVersions is set, cullOld() is automatically called.
Options:
url:: Used to construct the cache key
value:: The value to store in the cache
maxVersions:: The maximum number of cached versions to store;
when set .cullOld() is called.
versionMatchType:: How to determine which version to match. +
When exact (the default), only an exact version match with the current version will be returned. +
When skipWhenSameAsLatest, does not insert a new version if the value of the most recent version
is the same as the new one you are inserting;
use when multiple version are likely to contain the same value.
=== .cullOld()
Deletes older versions that have been cached.
The versions to keep/ remove are determined using semver.
[source,javascript]
const vapic = require('vapic');
vapic.cullOld({ url: '/foo', maxVersions: 3, redisClient: require('redis').createClient(), }, (err, result) => { /* ... */ });
Options:
Same as .set().
=== express middleware
[source,javascript]
const vapic = require('vapic'); const express = require('express');
const vapicOptions = { permittedAge: 3600, // one hour cacheVersion: require('package.json').version, redisClient: require('redis').createClient(), };
const router = express.Router(); router.get('/foo', vapic.expressMiddleware(vapicOptions), (req, res) => { if (req.vapicError) { res.status(404).json({ message: 'Data unavailable', }); return; } else { const data = JSON.parse(req.vapicResult); res.json(data); return; } });
module.exports = router;
Options:
prefix:: Prefix for the cache key.
Defaults to vapic:/
cacheVersion:: Cached version to use.
Defaults to the version number of the current module,
or process.env.npm_package_version
versionMatchType:: How to determine which version to match. +
When exact (the default), only an exact version match with the current version will be returned. +
When latestUpToCurrent, the latest version that is less than or equal to the current version will be returned. +
readVersionFromHeader:: If set to true,
will read the contents of the vapic HTTP request header,
and if the version property is present,
it will use that instead of the specified cacheVersion. +
This is most useful when there are multiple versions of clients being served by the same server,
and each of them needs to lock down their expected responses to a particular version. +
The vapic HTTP request header's value is expected to be a base64 encoded JSON string,
e.g. {version:'0.0.1'} => 'eyJ2ZXJzaW9uIjoiMC4wLjEifQ=='.
permittedAge:: The number of seconds the Cache-Control header in the response
should set its max-age to.
Defaults to 60 (One minute).
logger:: An object that has an error function.
Defaults to console
redisClient:: A Redis client instance.
Defaults to require('redis').createClient().
[TIP]
vapic.expressMiddleware() where versionMatchType=latestUpToCurrent is intended for use in conjunction with
vapic.set() where versionMatchType=skipWhenSameAsLatest
[TIP]
Convenience object to JSON conversion utilities are exposed in vapic.util.
If you wish to import this without require-ing all of vapic,
you can also require('vapic/util.js') directly.
== Development
If you would like to contribute, fork the git repo, and create a branch off the develop branch, and submit your pull request when you are done.
[NOTE]
This repo uses the git flow branching strategy.
To run tests:
[source,bash]
npm run test
== Author
http://bguiz.com[Brendan Graetz^]
== Licence
GPL-3.0