read-through-s3-memory-cache

Stability: 1 - Experimental

Read-through in-memory cache for S3 objects that are reasonable to cache in memory.

Contributors

@tristanls

Contents

• Overview
• Installation
• Tests
• Usage
• Documentation
• Releases

Overview

This module offers a read-through in-memory cache for small objects that are stored in S3. It assumes it is running in an environment where aws-sdk has access to its standard credentials chain with s3:GetObject permission to the configured S3 Bucket.

Installation

npm install read-through-s3-memory-cache

Tests

npm test

Usage

const Cache = require("read-through-s3-memory-cache");
const cache = new Cache(
{
    bucket: "name-of-my-s3-bucket"
});
cache.get("myKey", (error, value) =>
{
    console.log(error, value);
});

const initialCache = new Map();
initialCache.set("myKey", Buffer.from("myValue"));
const cache2 = new Cache(
{
    bucket: "name-of-my-other-s3-bucket",
    initialCache
});
cache2.get("myKey", (error, value) =>
{
    console.log(error, value);
});

Documentation

Cache

Public API

• Cache.S3_NOT_FOUND_CODES
• new Cache(config)
• cache.get(key, [context], callback)

Cache.S3_NOT_FOUND_CODES

• ["AccessDenied", "NoSuchKey"]

Default S3 error codes to treat as "not found" (AccessDenied can occur if the object does not exist but the caller has no s3:ListBucket permission).

new Cache(config)

• config: Object Cache configuration.
  • bucket: String Name of S3 bucket to retrieve values from.
  • initialCache: Map (Default: undefined) Initial cached values to use.
  • stdoutTelemetry: Boolean (Default: false) If true, telemetry will be emitted to stdout.

Creates a new Cache.

cache.get(key, [context], callback)

• key: String S3 Key to retrieve from cache.
• context: Object Optional context.
  • parentSpan: TraceTelemetryEvents.Span Parent span to use to trace execution.
• callback: Function function(error, value){}
  • error: Error Error, if any.
  • value: Buffer S3 Object, if it exists, undefined otherwise.

Retrieves the cached value from memory. If not found in memory, attempts to retrieve the value from S3. If not found in S3, caches undefined locally, otherwise, caches the value locally.

Releases

Current releases.

Policy

We follow the semantic versioning policy (semver.org) with a caveat:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards-compatible manner, and PATCH version when you make backwards-compatible bug fixes.

caveat: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.