# simple-lrucache

> Least Recently Used Cache

Latest version **1.2.0** (published 2019-09-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-lrucache
pnpm add simple-lrucache
yarn add simple-lrucache
bun add simple-lrucache
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2019-09-03 |
| First published | 2017-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 127.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Murtaza Zaidi |
| Maintainers | murtazazaidi |
| Keywords | lru, cache, lrucache, least recently used cache, simple, simple cache, simple-lrucache |

## Links

- npm: https://www.npmjs.com/package/simple-lrucache
- Repository: https://github.com/murtazazaidi/lrucache
- Homepage: https://github.com/murtazazaidi/lrucache#readme
- Issues: https://github.com/murtazazaidi/lrucache/issues
- npm.io page: https://npm.io/package/simple-lrucache

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2019-09-03
- 1.1.0 — 2018-07-08
- 1.0.4 — 2017-12-07
- 1.0.3 — 2017-12-07
- 1.0.2 — 2017-12-07
- 1.0.1 — 2017-11-07
- 1.0.0 — 2017-11-01

## README

[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/esta/issues) [![HitCount](http://hits.dwyl.io/murtazazaidi/lrucache.svg)](http://hits.dwyl.io/murtazazaidi/lrucache) [![Build Status](https://travis-ci.org/murtazazaidi/lrucache.svg?branch=master)](https://travis-ci.org/murtazazaidi/lrucache) [![codecov](https://codecov.io/gh/murtazazaidi/lrucache/branch/master/graph/badge.svg)](https://codecov.io/gh/murtazazaidi/lrucache) [![npm version](https://badge.fury.io/js/simple-lrucache.svg)](https://badge.fury.io/js/simple-lrucache)  [![Dependency Status](https://david-dm.org/murtazazaidi/lrucache.svg)](https://david-dm.org/murtazazaidi/lrucache) [![devDependency Status](https://david-dm.org/murtazazaidi/lrucache/dev-status.svg)](https://david-dm.org/murtazazaidi/lrucache#info=devDependencies)


# LRUCache for JS
Least Recently Used Cache based on JavaScript


## LRUCache Components
It consists of a HashMap and a Doubly LinkedList.
1. HashMap keeps the data against provided key
2. Doubly LinkedList maintains history for recently accessed keys


## Under the hood
There are two basic operations in any cache, (i) Addition/Updation (ii) Retrieval. Since latency is an important factor for any cache the data needs to reside in memory but memory is more expensive than storage and due to physical limitations we cannot have infinite memory so the cache must have limited amount of records at given point in time. This raises need for a retention policy. As the name suggests LRUCache retains only the most recently accessed data in cache, replacing least recently accessed data with newly added one.

Retrieval and Updation processes can be broken as
#### 1. Retrieval
- Lookup in HashMap for data against key, if found then return the data and proceed

- Look for the key in LinkedList and reposition it to more recent end

#### 2. Addition/Updation
- Check if it's an addition or updation. If it's an updation, we will update the data against the key and reposition the node in LinkedList to more recent end

- If it's an addition, we will check if there cache size won't exceed capacity. If size won't exceed capacity we will add the data in HashMap and create a new node with the key and add it on the recent end of LinkedList

- If size will exceed capacity, retention policy will kickoff. We will remove the least recent node from the LinkedList and remove data against they removed key from HashMap. Then we'll add data against new key as we did in previous step.

## LRUCache Interface
LRUCache has following methods.

1. Instantiate:
```javascript
// limit is maximum no of items/keys to be kept in cache at one time.
// Once this limit is reached, least recently used item will be dropped in
// favor of more recent additions
var limit = 100;
var cache = new LRUCache(limit);
```


2. Addition/Updation:
```javascript
var key = 'venus';
var value = {
  radius: 6052,
  unit: 'km',
  dayLength: 116.75
};
cache.set(key, value);
```


3. Retrieval:
```javascript
cache.get('venus');
// returns {radius: 6052, unit: "km", dayLength: 116.75}
```


4. Removal:
```javascript
cache.remove('venus');
// returns {radius: 6052, unit: "km", dayLength: 116.75}
// and removes venus from cache
```


5. Clear Cache:
```javascript
cache.clearAll();
// clears all data in the cache
```

## Installation
```
npm install simple-lrucache
```

## Usage
```javascript
// using ES6 import
import LRUCache from 'simple-lrucache';

// or using NodeJS require;
var LRUCache = require('simple-lrucache').default;

var cache = new LRUCache(5);
cache.set('a', 'Murtaza');
cache.set('b', 'Adeel');
cache.set('c', 'Hammad');
cache.set('d', 'Ghalib');
cache.set('e', 'Mehak');
cache.set('f', 'Anns');
console.log(cache.get('a')); // returns null
console.log(cache.get('b')); // returns 'Adeel'
cache.remove('b'); // returns 'Adeel' and removes from cache
console.log(cache.get('b')); // returns null
console.log(cache.get('c')); // return 'Hammad'
cache.clearAll();
console.log(cache.get('c')); // returns null
```


## Build Process for Project
NodeJS should be installed
```
# Run once after cloning the project to install dependencies
npm install .

# Building the project
npm run build

# Build and test the project with coverage report
npm run test
```

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