https://github.com/tusharf5/runtime-memcache
runtime-memcache is a javascript key-value store for chunks of arbitrary data (strings, objects, numbers) from results of database calls, API calls, or etc. It supports many commonly used caching policies.
https://github.com/tusharf5/runtime-memcache
browser cache caching-strategies javascript lru lru-cache mru nodejs runtime runtime-memcache typescript
Last synced: 3 months ago
JSON representation
runtime-memcache is a javascript key-value store for chunks of arbitrary data (strings, objects, numbers) from results of database calls, API calls, or etc. It supports many commonly used caching policies.
- Host: GitHub
- URL: https://github.com/tusharf5/runtime-memcache
- Owner: tusharf5
- License: mit
- Created: 2020-01-17T21:18:12.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-15T03:10:53.000Z (about 3 years ago)
- Last Synced: 2023-08-24T06:47:27.183Z (over 2 years ago)
- Topics: browser, cache, caching-strategies, javascript, lru, lru-cache, mru, nodejs, runtime, runtime-memcache, typescript
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/runtime-memcache
- Size: 608 KB
- Stars: 20
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
runtime-memcache
A no dependency, high performance, near optimal javascript caching library
runtime-memcache is a caching library to store key-value cache store for small chunks of arbitrary data (strings, objects, numbers) from results of database calls, API calls, or etc. It is entirely written using Typescript and supports many commonly used caching policies.
When creating a new cache store, you can specify the policy to evict items from the store. The default policy is `lru` (Least Recently Used)
runtime-memcache provides flexible construction to create a cache with a combination of the following features:
- size-based eviction when a maximum is exceeded based on frequency and recency
- time-based expiration of entries, measured since last access or last write
## Installation
```shell
npm install --save runtime-memcache
# or using yarn
yarn add runtime-memcache
```
### Node Environment (ES6+ import/export)
```javascript
import createStore from 'runtime-memcache';
```
### Node Environment (CJS)
```javascript
const createStore = require('runtime-memcache');
```
### Browser (use as a script tag)
```html
// RMStore is globaly set
const store = new RMStore();
```
## API
Calling the `createStore` function returns an object with the following properties.
| Property | Description |
| --------------- | ------------------------------------------------ |
| `get(id)` | Retrieves an item from the store |
| `has(id)` | Check if an item exists in the store |
| `set(id, data)` | Sets an item in the store |
| `remove(id)` | Removes an item from the store |
| `size()` | Returns the size of the item cache store |
| `keys()` | Returns all the keys of the cache store as array |
## Config
`createStore` takes an optional config object as an argument with the following properties.
| Property | Description | Type | Default |
| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------- | ------- |
| `timeToClear` | Time in **milliseconds** for which the store will keep an item when the policy is `timeout` or `tlru` | Number | 7200000 |
| `policy` | A Policy to evict items from the store | `timeout`, `lru`, `mru`, `tlru` | `lru` |
| `lruSize` | Size of the cache store when the policy is `lru` or `tlru` | Number | 500 |
| `mruSize` | Size of the cache store when the policy is `mru` | Number | 500 |
## Caching Policies
Following caching policies are supported.
| Policy | Name | Description |
| --------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeout` | Timeout | The items in the cache store will be automatically evicted after a fixed amount of time has elapsed since that item was set |
| `lru` | Least Recently Used | This policy evicts the **least recently used** items when the store size is full |
| `tlru` | Time Aware Least Recently Used | This policy evicts the **least recently used** items when the store size is full and also evict untouched items after a fixed amount of time has elapsed since that item was set |
| `mru` | Most Recently Used | This policy evicts the **most recently used** items when the store size is full |
## Time Complexity
| Policy | Method | Complexity |
| ------- | ---------------------- | ---------------- |
| timeout | `set`, `get`, `remove` | O(1), O(1), O(1) |
| lru | `set`, `get`, `remove` | O(1), O(1), O(1) |
| tlru | `set`, `get`, `remove` | O(1), O(1), O(1) |
| mru | `set`, `get`, `remove` | O(1), O(1), O(1) |
## Usage
### Typescript
```typescript
import createStore, { Config } from 'runtime-memcache';
const config: Config = {
policy: 'lru',
lruSize: 300, // cache a maximum of 300 users at a given time
};
interface User {
name: string;
}
const userCache = createStore(config);
async function loginUser(userId: string) {
if (userCache.has(userId)) {
return userCache.get(userId);
}
const user: User = await UserService.getUser(userId);
userCache.set(userId, user);
return user;
}
```
### Javascript
```javascript
import createStore from 'runtime-memcache';
const config = {
policy: 'timeout',
timeToClear: 7200000, // 2 hours
};
type Keys = 'key1' | 'key2';
const store = createStore(config);
store.set('key1', { name: 'name' }); // store the object and associate it with the provided key
store.get('key1'); // retrieves the object associated with this key
store.has('key1'); // returns true
store.size(); // returns 1
store.keys(); // returns ['key1']
store.remove('key1'); // deletes the object associated with this key
```
## NPM Script Commands
- `npm run test` -- Runs tests, lint and build.
- `npm run lint` -- Runs ESLint.
- `npm run format` -- Reformats all of the `.ts` and `.tsx` files with Prettier.
- `npm run build` -- Regenerates `dist` folder that gets included into NPM module.
## Under The Hood
runtime-memcache uses a combination of modified doubly-linked lists and hashmap data structures to achieve O(1) search-time complexity for all the methods.
## Todos
- Timeout Policy (TR)
- Least Recently Used Policy (LRU)
- Most Recently Used Policy (MRU)
- Least Frequently Used Policy (LFU)
- Time Aware Least Recently Used Policy (TLRU)
- Random Eviction Policy (RR)
- Add a warmup period for new items
For more information on caching policies read [this](https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU)