@j-o-r/cache NPM

@j-o-r/cache

Introduction

The @j-o-r/cache package provides utilities for creating a key-value storage system that respects typed arrays. It offers both synchronous (CacheSync) and asynchronous (CacheAsync) versions for managing cache entries.

Installation

To use the @j-o-r/cache package, install it via npm:

npm install @j-o-r/cache

Usage

Synchronous Version (CacheSync)

Use CacheSync for immediate file operations:

import { CacheSync } from '@j-o-r/cache';

const cache = new CacheSync('storage/tmp', true, 'log', 'ascii');

Asynchronous Version (CacheAsync)

Use CacheAsync for non-blocking file operations:

import { CacheAsync } from '@j-o-r/cache';

const cache = new CacheAsync('storage/tmp', true, 'log', 'ascii');

Use typed arrays

import { CacheAsync, JSONEXT } from '@j-o-r/cache';

const cache = new CacheAsync('storage/tmp', true);
cache.jsonEncoder = JSONEXT;
const data = new Uint32Array([1, 2, 3, 4, 5]);
// write a typed array 
await c.write('typed_array', data);

Methods

Both CacheSync and CacheAsync provide the following methods:

list(): Returns an array of all keys in the cache folder.
write(key, value): Writes a value to the cache with the given key. If the value is not a string and the extension is not json or ndjson, it throws an error.
append(key, value): Appends a value to the cache with the given key. If the value is not a string or if JSON is used without the ndjson extension, it throws an error.
read(key): Reads a value from the cache with the given key. If async, use await. Returns undefined if no file exists.
writeStream(key): Returns a writable stream. For writing large amounts of data
readStream(key): Returns a readable stream for reading large file.
file(key): Returns a CacheFile object with details about file path, encoding, and existence status.
delete(key): Deletes a file from the cache with the given key.
empty(): Empties all files in the cache folder.
expire(time): Deletes files older than specified time (in milliseconds).
secret = [string] Encrypt the content written to the files with this 'secret'.
encoding = [string] Force an encoding (for binaries e.g.) default 'uft-8'.
`sanitizeKey(key)`** returns a valid key. Make sure a key is valid as a storage location (filename).
`md5Key(key)`** returns a valid key in the form of a MD5 hash.
expire(value) Delete all keys who are older (last changed) then the number of MS given as value.

Example

Synchronous Example:

const syncCache = new CacheSync('storage/tmp');

syncCache.write('key', 'value');
const syncValue = syncCache.read('key');
syncCache.delete('key');
syncCache.empty();

Asynchronous Example:

const asyncCache = new CacheAsync('storage/tmp');

await asyncCache.write('key', 'value');
const asyncValue = await asyncCache.read('key');
await asyncCache.delete('key');
await asyncCache.empty();

Read/Write streams

Writing Data with Streams:

const writable = cache.writeStream('large_key_file');
writable.write('Some large data...');
writable.end();

Reading Data with Streams:

const readable = cache.readStream('large_key_file');
readable.on('data', (chunk) => {
    console.log(`Received ${chunk.length} bytes of data.`);
});

Encryption Example

To enable encryption for both versions:

// For both Sync and Async:
cache.secret = 'mySecretKey';

// Write encrypted data:
cache.write('key', 'sensitive data');

// Read and decrypt data:
let decryptedValue;
if (cache instanceof CacheSync) {
    decryptedValue = cache.read('key'); // Synchronous read
} else {
    decryptedValue = await cache.read('key'); // Asynchronous read with await
}
console.log(decryptedValue); // Outputs: 'sensitive data'