persistent-node-cache

Light weight persistent cache backed by node-cache. It persists in-memory cache periodically on disk while also saving every write command in an append-only manner to guarantee minimal data loss during application restarts.

Quick Start

Install

npm i persistent-node-cache

Usage

Initialize Cache

import { PersistentNodeCache } from "persistent-node-cache";

const cache = new PersistentNodeCache("mycache", 1000);

Options

cacheName: string (required) the name of the cache. Used for recovering/restoring cache from disk.
period: number (default: 1 second) interval at which cache backup is saved
dir: string (default: home dir of user) directory where backup files will be created
opts: object standard options of node-cache package
serializer: CacheSerializer (default: JSON serializer) custom serializer for persisting data on disk

CacheSerializer Type

type CacheSerializer = {
    serialize: Function;
    deserialize: Function;
}

Cache Operations

All cache operations are similar to those of node-cache package since it's an extension of implementation of node-cache. Please refer to node-cache docs for an extensive list of all operations supported.

Store a key (SET):

cache.set(key, val, [ttl])

Sets a key-value pair. Defining ttl is optional.

cache.set("mykey", "myval", 1000);    //true

Retrieve a key (GET):

Get a key-value pair.

cache.get("mykey");    //myval

Delete a key (DEL):

Delete a key from cache. Returns the number of entries deleted.

cache.del("mykey");    //1

Restore/Recover Cache

Version 1.2.0 onwards

The cache is restored automatically when the cache is initialized (again). Parameter is cacheName should be passed. dir will have to be passed if the cache was created specifying a custom directory.

const cache = new PersistentNodeCache("mycache");

cache.get("mykey");    //myval

Version 1.1.1 and before

The cacheName field should be passed to tell which cache to restore. If dir field was passed during cache initialization previously, it should be passed during recovery as well to locate the backup files.

const cache = new PersistentNodeCache("mycache");
cache.recover();

cache.get("mykey");    //myval

Use Custom Serializer

import { PersistentNodeCache, CacheSerializer } from "persistent-node-cache";

const customSerializer: CacheSerializer = {
    serialize: (item: any) => {
        return Buffer.from(Buffer.from(JSON.stringify(item)).toString('base64') + '\n');
    },
    deserialize: (bf: Buffer) => {
        return JSON.parse(Buffer.from(bf.toString().trim(), 'base64').toString());
    }
};

const cache = new PersistentNodeCache("mycache", 0, '', {}, customSerializer);

Benchmarks

Benchmark figures for get/set operations (on an Apple M2, 8 GB RAM system)

	get	set
`persistent-node-cache`	21,074,363 ops/sec	623,668 ops/sec
`node-cache`	15,939,686 ops/sec	8,862,257 ops/sec
`persistent-cache`	8,670,967 ops/sec	550 ops/sec

kwertop/persistent-node-cache