README.md

cloud-cache

Node.js caching library with pluggable backing store via abstract-blob-store. Streaming support makes it particularly useful for caching larger values like resized/cropped images or transcoded videos.

Table of Contents

• Features
• Install
• Usage
  • Setting up the client
  • Promise API
  • Stream API
    • Error Handling
  • Errors
• How it works
• Partial Writes / Durability

Features

• Promise and Stream based APIs
• Supported backing stores:
  • AWS S3
  • Google Cloud Storage
  • Azure Storage
  • LevelDB
  • PostgreSQL
  • Local file system
  • IPFS
  • etc.
• Supported data types:
  • Buffer
  • JSON types
    • Number
    • String
    • Boolean
    • Array
    • Object

Install

npm install --save cloud-cache

Requires Node v6+

Usage

See ./test directory for usage examples.

Setting up the client

import cloudCache from 'cloud-cache'
const cache = cloudCache(blobStore [, opts])

• blobStore: blobStore abstract-blob-store instance
• opts.keyPrefix: String cloudcache/ global key prefix that will be automatically prepended to all keys

Promise API

All methods return promises.

cache.get(key) Get a key.

• key: String the key to get

Throws a KeyNotExistsError error if the key doesn't exist or value has expired.

cache.get('key')

cache.set(key, value [, opts]) Stores a new value in the cache.

• key: String the key to set
• value: Mixed Buffer or any JSON compatible value.
• opts.ttl: Number, Infinity Time to live: how long the data needs to be stored measured in seconds

cache.set('foo', 'bar', { ttl: 60 * 60 })

cache.del(key) Delete a key.

• key: String the key to delete

cache.del('key')

cache.getOrSet(key, getValueFn [, opts]) Returns cached value, storing and returning value on cache misses.

• key: String the key to get
• getValueFn: Function function to evaluate on cache misses
• opts: Object same as cache.set
• opts.refresh: Boolean false forces a cache miss

The arguments are the same as cache.set, except that value must be a function or a promise returning function that evaluates / resolves to a valid cache.set value. The function will only be evaluated on cache misses.

cache.getOrSet('google.com', () => (
  fetch('http://google.com/').then(body => body.text())
))

Stream API

cache.getStream(key)

• key: String the key to read

Returns a Readable Stream.

Emits a KeyNotExistsError error if the key doesn't exist or value has expired.

Alias: cache.gets(key)

cache.getStream('olalonde/avatar.png').pipe(req)

cache.setStream(key [, opts])

• key: String the key to set
• opts: Object same as cache.set

Returns a Writable Stream.

Alias: cache.sets(key)

resizeImage('/tmp/avatar.png').pipe(cache.setStream('olalonde/avatar.png'))

cache.getOrSetStream(key, getStreamFn [, opts])

• key: String the key to get
• getStreamFn: Function Read Stream returning function that will be called on cache misses.
• opts: Object same as cache.getOrSet

Returns a Readable Stream.

Important:

• The stream returned by getStreamFn might not be cached if the stream returned by cache.getOrSetStream not fully consumed (e.g. by piping it).
• A finish event is fired to indicate that the stream was completely saved to the cache.

cache.getOrSetStream('olalonde/avatar.png', () => resizeImage('/tmp/avatar.png')).pipe(req)

Error Handling

The streams returned by cache may emit error events. We recommend using pipe() from the mississippi module to avoid unhandled errors and make sure the cache stream closes properly if the destination has an error.

e.g.:

import { pipe } from 'mississippi'
// ...
pipe(cache.getOrSetStream('key', getReadStream), req, (err) => {
  if (err) return next(err)
})

Errors

• CloudCacheError this base class is inherited by the errors below
• KeyNotExistsError thrown/emitted when trying to get a non existent / expired key. Exposes a key property

The error classes can be accessed through import or as a property on the cache object, e.g.:

import { CloudCacheError, KeyNotExistsError } from 'cloud-cache'
// ...
cache.CloudCacheError === CloudCacheError // true
cache.KeyNotExistsError === KeyNotExistsError // true
KeyNotExistsError instanceof CloudCacheError // true

How it works

Cloud-cache encodes each cached value as a file stored on a storage provider (S3, file system, etc.). The files start with a small JSON header which contains metadata (e.g. creation time, ttl, data type, etc.), followed by a newline character (\n) and finally, the actual cached value. Values are encoded as JSON, except for buffers or streams which are stored as raw bytes.

This means that cached values aren't very useful to applications which are unaware of the header.

If you are caching transformed images to S3 for example, you couldn't reference the S3 URL directly from an HTML image tag for example (because the browser wouldn't know it needs to ignore everything before the first newline character).

You could however serve the images from a Node.js HTTP server and use the stream API to stream the image from S3 (e.g. cache.gets('olalonde/avatar.png').pipe(res)).

Cloud-cache evicts expired values on read which means that expired values will remain stored as long as they are not read.

Partial Writes / Durability

Cloud-cache does not guarantee that set operations will be atomic and instead delegates that responsibility to the underlying store implementation. If the underlying store doesn't guarantee atomic writes, partial writes can happen (e.g. if the process crashes in the middle of a write). For example, fs-blob-store will happily write half of a stream to the file system. s3-blob-store, on the other hand, will only write a stream which has been fully consumed.