# @pedromsilva/data-cache

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

Latest version **0.0.1** (published 2019-05-11) · ISC license · 0 weekly downloads

## Install

```sh
npm install @pedromsilva/data-cache
pnpm add @pedromsilva/data-cache
yarn add @pedromsilva/data-cache
bun add @pedromsilva/data-cache
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2019-05-11 |
| First published | 2019-05-11 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 112.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Pedro M. Silva |
| Maintainers | pedromsilva |
| Keywords | js, cache, memory, file, storage, ttl, container, async, typescript |

## Links

- npm: https://www.npmjs.com/package/@pedromsilva/data-cache
- Repository: https://github.com/pedromsilvapt/data-cache
- Homepage: https://github.com/pedromsilvapt/data-cache#readme
- Issues: https://github.com/pedromsilvapt/data-cache/issues
- npm.io page: https://npm.io/package/@pedromsilva/data-cache

## Dependencies (6)

- [mz](https://npm.io/package/mz.md) ^2.7.0
- [data-semaphore](https://npm.io/package/data-semaphore.md) ^0.3.9
- [safe-file-write](https://npm.io/package/safe-file-write.md) ^2.0.0
- [data-balanced-tree](https://npm.io/package/data-balanced-tree.md) ^0.1.0
- [data-async-iterators](https://npm.io/package/data-async-iterators.md) ^1.4.4
- [@pedromsilva/data-future](https://npm.io/package/@pedromsilva/data-future.md) ^1.1.2

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.1 (latest) — 2019-05-11

## 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<E> {
    readCache ?: boolean;
    readExpiry ?: E;
}

export interface WriteCacheOptions<E, S> {
    writeCache ?: boolean;
    writeExpiry ?: E;
    writeState ?: S;
}

export interface CacheOptions<E, S> extends ReadCacheOptions<E>, WriteCacheOptions<E, S> { }

export interface Cache<T, E = void, S = void> {
    // Responsible for evicting unused/old records from the cache
    evictor : Evictor<T, E, S>;

    // The persistence layer for the cache records
    storage : CacheStorage<T, E, S>;

    // 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<void>;

    saveIfDirtySync () : boolean;

    saveIfDirty () : Promise<boolean>;


    loadSync () : void;

    load () : Promise<void>;

    loadIfStaleSync () : boolean;

    loadIfStale () : Promise<boolean>;


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

    has ( key : string, options ?: ReadCacheOptions<E> ) : Promise<boolean>;

    getSync ( key : string, options ?: ReadCacheOptions<E> ) : T;
 
    get ( key : string, options ?: ReadCacheOptions<E> ) : Promise<T>;

    setSync ( key : string, value : T, options ?: WriteCacheOptions<E, S> ) : void;

    set ( key : string, value : T, options ?: WriteCacheOptions<E, S> ) : Promise<void>;

    deleteSync ( key : string ) : boolean;

    delete ( key : string ) : Promise<boolean>;

    compute<V extends T = T> ( key : string, producer : () => V | Promise<V>, options ?: CacheOptions<E, S> ) : Promise<V>;

    computeSync<V extends T = T> ( key : string, producer : () => V, options ?: CacheOptions<E, S> ) : V;


    keys ( options ?: ReadCacheOptions<E> ) : IterableIterator<string>;

    values ( options ?: ReadCacheOptions<E> ) : IterableIterator<T>;

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

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

    close () : void;
}
```

---
_Source: https://npm.io/package/@pedromsilva/data-cache · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._