= vapic ifndef::env-github[]

View on 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