Skip to content

Point-in-time recovery module for in-memory node-cache with asynchronous persistence

License

Notifications You must be signed in to change notification settings

kwertop/persistent-node-cache

Repository files navigation

persistent-node-cache Tests

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