https://github.com/m4x1m1l14n/cache-js
Lightweight in-memory isomorphic cache implementation with TTL for browser & Node JS written in TypeScript
https://github.com/m4x1m1l14n/cache-js
browser cache in-memory javascript memcache nodejs ttl typescript
Last synced: 7 months ago
JSON representation
Lightweight in-memory isomorphic cache implementation with TTL for browser & Node JS written in TypeScript
- Host: GitHub
- URL: https://github.com/m4x1m1l14n/cache-js
- Owner: m4x1m1l14n
- License: mit
- Created: 2021-10-25T16:23:42.000Z (over 4 years ago)
- Default Branch: devel
- Last Pushed: 2025-03-14T13:03:03.000Z (12 months ago)
- Last Synced: 2025-04-17T22:02:45.530Z (11 months ago)
- Topics: browser, cache, in-memory, javascript, memcache, nodejs, ttl, typescript
- Language: TypeScript
- Homepage:
- Size: 844 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @m4x1m1l14n/cache
[](https://www.npmjs.com/package/@m4x1m1l14n/cache)
[](https://github.com/m4x1m1l14n/cache-js/actions/workflows/ci.yml)
[](https://codecov.io/gh/m4x1m1l14n/cache-js)
# Lightweight in-memory isomorphic cache implementation with TTL for browser & Node JS
This simple cache is written in TypeScript and works both for browser and Node. It is build on top of built-in `Map` thus theoretical limit for stored entries is in case of Node 2 ^ 24, which is approximately 16.6 million.
Each entry in cache can has its own TTL (timeout) and assigned expiration callback fired once entry expire.
## Table of Contents
- [Installation](#installation)
- [Documentation](#documentation)
- [Instantiation](#instantiation)
- [set](#set)
- [get](#get)
- [take](#take)
- [has](#has)
- [delete](#delete)
- [flush](#flush)
## Installation
```bash
npm i @m4x1m1l14n/cache
```
## Documentation
### Instantiation
Cache implementation uses templates so when you use this library in TypeScript project, you can restrict what type of `key` and `value` cache has to consume.
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
```
Cache behavior can be altered with `options` object passed to its constructor. Following table shows options that can be changed.
| Option | Default value | Description |
| ---------- | ------------- | ------------------------------------------------------------------- |
| ~~resolution~~ | ~~1000~~ | **Deprecated.** Previously set interval for checking expiry. Now items expire at exact TTL times using dynamic timeout scheduling for improved accuracy. |
| defaultTTL | Infinity | Default TTL for all added entries |
| maxItems | 1000 | Maximum number of entries stored in cache |
**Expiration Accuracy**: Cache entries now expire at their exact TTL expiration time rather than being checked periodically. This provides better accuracy and performance by scheduling cleanup events precisely when items expire, instead of checking all items at fixed intervals.
Example:
```ts
import { Cache, CacheOptions } from '@m4x1m1l14n/cache';
const options: CacheOptions = {
defaultTTL: Number.POSITIVE_INFINITY,
maxItems: 1000,
};
const cache = new Cache(options);
```
### set
Store value in cache under specified key.
Prototype:
```ts
public set( key : K, value : T, ttl? : number, callback?: ExpirationCallback ) : Cache;
```
Params:
- `key`: Key under which value will be stored
- `value`: Value to store
- `ttl (optional)`: Timeout after which cache entry will expire and will be deleted
- `callback (optional)`: Callback invoked once entry expire
Return value:
`set` method returns itself, so it is possible to chain multiple sets
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello').set(2, 'World').set(3, '!');
```
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
// Key 1 will persist in cache until standardTTL is reached
cache.set(1, 'Hello');
// Key 2 will expire after 5 seconds
cache.set(2, 'World', 5000);
// Key 3 will expire after 3 seconds, and callback is called
cache.set(3, 'Some other value', 3000, (value) => {
console.log(`'${value}' has expired`);
// Expected output
// > 'Some other value' has expired
});
```
### get
Retrieve value of cached entry by its key.
Prototype:
```ts
public get( key : K, refresh = false ) : T | undefined
```
Params:
- `key`: Key to retrieve
- `refresh (default: false)`: Whether to refresh entry TTL or not. In case `true` is passed, item TTL is refreshed and its expiration is postponed, like item is freshly inserted in cache.
Return value:
`get` returns value assigned to specified `key`. If `key` is not found in cache, `undefined` is returned.
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello');
console.log(cache.get(1));
// Expected output
// > Hello
```
### take
Retrieve value of cached entry by its key and remove it from cache.
Prototype:
```ts
public take( key: K ): T | undefined
```
Params:
- `key`: Key to retrieve
Return value:
`take` returns value assigned to specified `key`. If `key` is not found in cache, `undefined` is returned.
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello');
console.log(cache.take(1));
console.log(cache.take(1));
// Expected output
// > Hello
// > undefined
```
### has
Returns wether cache contains specified key or not.
Prototype:
```ts
public has( key : K ) : boolean
```
Params:
- `key`: Key to check for
Return value:
`true` in case `key` exists in cache, `false` otherwise
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello');
console.log(cache.has(1));
console.log(cache.has(2));
// Expected output
// > true
// > false
```
### delete
Removes cache entry by specified key.
Prototype:
```ts
public delete( key : K ) : boolean
```
Params:
- `key`: Key of entry to remove
Return value:
`true` in case `key` was removed, `false` otherwise
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello');
console.log(cache.get(1));
console.log(cache.delete(1));
console.log(cache.get(1));
console.log(cache.delete(1));
// Expected output
// > Hello
// > true
// > undefined
// > false
```
### flush
Clears all entries from the cache, with an option to invoke expiration callbacks for each entry before deletion.
Prototype:
```ts
public flush(invokeCallback: boolean = false) : void
```
Params:
- `invokeCallback (default: false)`: If set to `true`, any expiration callback assigned to an entry will be called before the entry is deleted.
Return value:
`flush` does not return a value.
Example:
```ts
import { Cache } from '@m4x1m1l14n/cache';
const cache = new Cache();
cache.set(1, 'Hello', 1000, (value) => {
console.log(`'${value}' has expired`);
});
cache.set(2, 'World', 2000, (value) => {
console.log(`'${value}' has expired`);
});
// Flush cache and invoke callbacks
cache.flush(true);
// Expected output:
// > 'Hello' has expired
// > 'World' has expired
// Flush cache without invoking callbacks
cache.flush();
```