Skip to content
This repository has been archived by the owner on Apr 2, 2024. It is now read-only.
/ cachescribe Public archive

a simple cache that can persist in the file system across different runs of your program.

License

Notifications You must be signed in to change notification settings

saud-alnasser/cachescribe

Repository files navigation

About ❓

a simple cache that can persist in the file system across different runs of your program.

Usage ✨

Installation

npm install cachescribe

Initialization

note: when a cache is created it tries to load entries from the snapshot file synchronously then clears all expired entries, if not found it will start as a new empty cache. it also attaches listeners on the process to create a snapshot file automatically on exit.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

you can pass an object to configure these options upon initialization:

namespace: unique identifier that will be used for snapshot file name generation to avoid overwrites by other caches (default: 'default')

directory: the directory where the snapshot file will be written in (default: 'node_modules/.cache/cachescribe').

extension: file extension to be used for the cache snapshot file (default: '')

algorithm: hashing algorithm to be used for snapshot filename generation (default: md5)

ttl: duration in seconds of the standard time to live for entires, if duration set to zero then it's infinite (default: 0)

hash: hashing function that will be used for cache filename generation (default: node:crypto)

snapshot: should the cache create snapshot files and read from them or not (default: true)

transformer: a transformer that will serialize and deserialize the cache entries to be written in the snapshot file (default: superjson)

API

set:

sets a key and value pair. it is possible to define a ttl (in seconds).

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value', 10);

mset:

sets multiple key and value pairs. it is possible to define a ttl (in seconds).

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.mset(
  { key: 'key1', value: 'value1', ttl: 10 },
  { key: 'key2', value: 'value2' },
  { key: 'key3', value: 'value3' },
);

get:

gets a value from the cache. returns undefined if not found or expired.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value');

const value = cache.get('key');

if (value) {
  // 'value' 
}

mget:

gets multiple entries at once.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');

cache.set('key2', 'value2');

const values = cache.mget('key1', 'key2');
// { key1: 'value1', key2: 'value2' }

take:

gets a value of an entry then removes it from the cache.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value');

const value = cache.take('key');
// 'value'

mtake:

gets multiple values of entries then removes them from the cache.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');

cache.set('key2', 'value2');

const values = cache.mtake('key1', 'key2');
// { key1: 'value1', key2: 'value2' }

has:

checks whether an entry with the given key exists or not.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value');

const exists = cache.has('key');
// true

mhas:

checks whether a list of entries with the given keys all exists or not.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

cache.mhas('key1', 'key2');
// true

del:

removes any entry from the cache.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value');

const deleted = cache.del('key');
// true

cache.has('key');
// false

mdel:

removes entries from the cache.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

cache.mdel('key1', 'key2');

ttl:

changes the time to live for a specific cached entry.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key', 'value', 10);

cache.ttl('key', 3);

flush:

removes all entries in the cache.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

cache.flush();

cache.has('key1');
// false

keys:

returns an iterable iterator of cache entry keys.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

for (const key of cache.keys()) {
  // ...
}

values:

returns an iterable iterator of cache entry values.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

for (const value of cache.values()) {
  // ...
}

entries:

returns an iterable iterator of cache key-value pairs.

import { cachescribe } from 'cachescribe';

const cache = cachescribe();

cache.set('key1', 'value1');
cache.set('key2', 'value2');

for (const [key, value] of cache.entries()) {
  // ...
}

Contribution 💡

feel free to contribute to this project but please read the contributing guidelines before opening an issue or pull request so you understand the branching strategy and local development environment.

About

a simple cache that can persist in the file system across different runs of your program.

Topics

Resources

License

Stars

Watchers

Forks