https://github.com/pedromsilvapt/data-cache

Incredibly simple and extensible in-memory sync/async cache with optional persistence and eviction
https://github.com/pedromsilvapt/data-cache

Last synced: 11 days ago
JSON representation

Incredibly simple and extensible in-memory sync/async cache with optional persistence and eviction

• Host: GitHub
• URL: https://github.com/pedromsilvapt/data-cache
• Owner: pedromsilvapt
• Created: 2019-05-11T21:06:01.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2019-05-11T21:09:09.000Z (over 5 years ago)
• Last Synced: 2024-12-11T12:18:13.911Z (28 days ago)
• Language: TypeScript
• Size: 12.7 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Cache

> Incredibly simple and extensible in-memory sync/async cache with optional persistence and eviction

# Installation

```shell

npm install --save @pedromsilva/data-cache

```

# Usage

> **Note:** Using async-await syntax for simplicity. Not that async-await code must be run inside an async function

```typescript

import { MemoryCache } from '@pedromsilva/data-cache';

const cache = new MemoryCache( 'cache.jsonl' );

// All the methods below have matching synchronous version with a 'Sync' suffix, such as getSync(), loadSync() etc...

// You can choose to use either the async or sync versions of the methods, however

// it is not recommended to mix the two: choose one style and stick with it.

await cache.load();

const has = await cache.has( 'key' );

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

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

await cache.delete( 'key' );

await cache.save();

// There is a shortcut for retrieving an item if it exists, or calculating and storing it if it doesn't

const remoteValue = await cache.compute( 'key', async () => {

    return await fetchValueFromSomeRemoteApi();

} );

// You can iterate over the cache items

for ( let [ key, value ] of cache ) { }

for ( let key of cache.keys() ) { }

for ( let value of cache.values() ) { }

// To fully dispose of a cache, you can close it (releasing any resources it might be holding)

cache.close();

```

## TtlEvictor

By default, this package comes with a TtlEvictor that allows to automatically remove elements from the cache if they are too old.

```typescript

import { MemoryCache, TtlEvictor } from '@pedromsilva/data-cache';

// Items in the cache live for one minute.

const cache = new MemoryCache( 'cache.jsonl', new TtlEvictor( { ttl: 60 * 1000 } ) );

// Or use the shorter version

import { TtlMemoryCache } from '@pedromsilva/data-cache';

const cache = new TtlMemoryCache( 'cache.jsonl', 60 * 1000 );

```

## API

```typescript

export interface ReadCacheOptions {

    readCache ?: boolean;

    readExpiry ?: E;

}

export interface WriteCacheOptions {

    writeCache ?: boolean;

    writeExpiry ?: E;

    writeState ?: S;

}

export interface CacheOptions extends ReadCacheOptions, WriteCacheOptions { }

export interface Cache {

    // Responsible for evicting unused/old records from the cache

    evictor : Evictor;

    // The persistence layer for the cache records

    storage : CacheStorage;

    // Does this cache have unsaved changes?

    readonly dirty : boolean;

    // Is the data in memory up-to-date?

    readonly stale : boolean;

    saveOnWrite : boolean;

    saveOnWriteDebounce : number;

    saveSync () : void;

    save () : Promise;

    saveIfDirtySync () : boolean;

    saveIfDirty () : Promise;

    loadSync () : void;

    load () : Promise;

    loadIfStaleSync () : boolean;

    loadIfStale () : Promise;

    hasSync ( key : string, options ?: ReadCacheOptions ) : boolean;

    has ( key : string, options ?: ReadCacheOptions ) : Promise;

    getSync ( key : string, options ?: ReadCacheOptions ) : T;

 

    get ( key : string, options ?: ReadCacheOptions ) : Promise;

    setSync ( key : string, value : T, options ?: WriteCacheOptions ) : void;

    set ( key : string, value : T, options ?: WriteCacheOptions ) : Promise;

    deleteSync ( key : string ) : boolean;

    delete ( key : string ) : Promise;

    compute ( key : string, producer : () => V | Promise, options ?: CacheOptions ) : Promise;

    computeSync ( key : string, producer : () => V, options ?: CacheOptions ) : V;

    keys ( options ?: ReadCacheOptions ) : IterableIterator;

    values ( options ?: ReadCacheOptions ) : IterableIterator;

    entries ( options ?: ReadCacheOptions ) : IterableIterator<[string, T]>;

    [ Symbol.iterator ] () : IterableIterator<[string, T]>;

    close () : void;

}

```