@solid-soda/cache

It provides features covering simple to advanced caching needs. It is designed for performance and resiliency, ships with ready to use providers for the most common caching backends.

Installation

yarn add @solid-soda/cache

TL;DR

In example app we want to redis as cache-backend. Just create a simple cache instance:

import { Cache, RedisProvider } from "@solid-soda/cache";

const provider = new RedisProvider({
  host: "localhost",
  port: 6379,
  password: "password",
});

export const cache = new Cache(provider);

That is all. We can use cache in any place of our application, or pass the result to DI container, etc.

import { cache } from "./cache";

// ...
let item = await cache.get("my-key");
if (!item) {
  // cache for key "my-key" not found

  item = doHardWork();
  await cache.set("my-key", item);
}

Cache invalidation

Expiration

Cache#set method has third argument lifetime (amount of mimilliseconds). You can pass it, and after this time cached item will be invalidate.

It's a very simple mechanism:

import { Cache, InMemoryProvider } from "@solid-soda/cache";

const provider = new InMemoryProvider();
const cache = new Cache(provider);

// ...

async function doDeal() {
  await cache.set("key", "cached!", 1000);

  await sleep(600);

  const value1 = await cache.get("key"); // 'cached!'

  await sleep(600);

  const value2 = await cache.get("key"); // null
}

Tag invalidation

Will be released later

Providers

You can use many cache providers in your application.

InMemoryProvider

Cache resets after every restart application.
Cache can't be shared between application instances.
Cache can store any value (e.g. Promises), because it doesn't serialize it.

import { Cache, InMemoryProvider } from "@solid-soda/cache";

const provider = new InMemoryProvider();
export const cache = new Cache(provider);

Redis provider

Cache can be stored after restart application, configure redis persistence.
Cache can be shared between any kind of applications.
Cache can store only serializable value.

import { Cache, RedisProvider } from "@solid-soda/cache";

const provider = new RedisProvider({
  host: "localhost",
  port: 6379,
  password: "password",
});
export const cache = new Cache(provider);

If you want to use custom serializer, just pass it as second argument to RedisProvider constructor. More about serializers.

import { Cache, RedisProvider } from "@solid-soda/cache";

const provider = new RedisProvider(credentials, serializer);
export const cache = new Cache(provider);

FileSystemProvider

Cache can be stored after restart application, it's just files on your disk.
Cache can't be shared between any kind of applications, because it's just files on your disk.
Cache can store only serializable value.

import { Cache, FileSystemProvider } from "@solid-soda/cache";

const provider = new FileSystemProvider({
  baseDir: __dirname,
});
export const cache = new Cache(provider);

If you don't pass baseDir it will be use os.tmpdir.

If you want to use custom serializer, just pass it to config in FileSystemProvider constructor. More about serializers.

import { Cache, FileSystemProvider } from "@solid-soda/cache";

const provider = new FileSystemProvider({ baseDir: __dirname, serializer });
export const cache = new Cache(provider);

MultipleProvidersProvider

This provider allow you to use any numbers of providers, it'll spread values to all providers.

import {
  Cache,
  MultipleProvidersProvider,
  RedisProvider,
  InMemoryProvider,
} from "@solid-soda/cache";

const provider = new MultipleProvidersProvider([
  new RedisProvider({
    host: "redis-1",
    port: 6379,
  }),
  new RedisProvider({
    host: "redis-2",
    port: 6379,
  }),
]);

export const cache = new Cache(provider);

Common use case: cache is really large and application need more than one Redis to store it.

Custom provider

This library can includes only limited number of providers, but you can create custom provider and use it for cache. Just implement CacheProvider intreface.

interface CacheProvider {
  get<T>(key: string, def?: T): Promise<T | undefined>;
  set<T>(key: string, value: T): Promise<void>;
  reset(key: string): Promise<void>;
}

For example, we can create CustomMemoryProvider:

import { CacheProvider } from "@solid-soda/cache";

export class CustomMemoryProvider implements CacheProvider {
  private readonly cache = {};

  get = async (key, def) => this.cache[key] || def;

  set = async (key, value) => {
    this.cache[key] = value;
  };

  reset = async (key) => {
    this.cache[key] = undefined;
  };
}

Brilliant! Create the provider instance and pass in to Cache.

Serializer

If can provider stores only string value, you can pass serializer to it. If you don't, provider will use default serializer based on JSON.parse and JSON.stringify.

Any serizliser must implements Serializer interface:

interface Serializer {
  serialize<T>(value: T): Promise<string>;
  deserialize<T>(value: string): Promise<T>;
}

Custom serializer example:

import { Serializer } from '@solid-soda/cache'

const fastSerizliser: Serializer = {
  async serialize(value) {
    const str = // do something
    return str
  },
  async deserialize(str) {
    const value = // do something
    return value
  },
}

project-cemetery/cache