# @bemoje/max-age-cache

Simple key-value cache with configurable maximum age of entries. After expiry,
keyvals are automatically deleted in order to free up memory.

## Module Compatibility

![javascript](https://img.shields.io/badge/language-UMD-blue.svg?label=JavaScript)
![javascript](https://img.shields.io/badge/language-ES-blue.svg?label=JavaScript)
![javascript](https://img.shields.io/badge/language-CJS-blue.svg?label=JavaScript)

## Stats

![bash](https://img.shields.io/npm/dt/shrine512?label=downloads)
![bash](https://img.shields.io/npm/dm/shrine512?label=over%20time)
![asd](https://img.shields.io/github/forks/bemoje/shrine512)

## Installation

Enter one of these into your console to install using npm / node.

```sh
npm install @bemoje/max-age-cache
npm install --save @bemoje/max-age-cache
npm install --save-dev @bemoje/max-age-cache
```

## Usage

```javascript
// import library
import MaxAgeCache from '@bemoje/max-age-cache'

// create new instance with 500 ms maximum age
const cache = new MaxAgeCache(500)

// add keyvals
cache.set('a', 1)
cache.set('b', 2)
cache.set('c', 3)

// check if value exists at key
cache.has('b')
//=> true

// get a value at key
cache.get('c')
//=> 3

// delete a cache value at key
cache.del('c')

// get all cache's keys
cache.keys()
//=> ['a', 'b']

// get all cache's values
cache.values()
//=> [1, 2]

// get all cache's keyvals as entries
cache.entries()
//=> [['a', 1], ['b', 2]]

// get all cache's keyvals as object
cache.toObject()
//=> {a: 1, b: 2}

// let cache entries expire after 1200 ms and check existence before and after
cache.has('a')
//=> true
setTimeout(() => {
	cache.has('a')
	//=> false
}, 1200)
```

## API

### MaxAgeCache

-  `maxAgeMs` **[number]** The number of milliseconds that is the maximum age of
   entries.

Returns **[MaxAgeCache]** A new MaxAgeCache instance.

#### maxAge

Sets the maximum age for new entries.

-  `ms` **[number]** The number of milliseconds to be the maximum age of
   entries.

Returns **void** void

#### set

Add a keyval to the cache. Chainable.

-  `key` **[string]** The key
-  `value` **any** The value

Returns **[MaxAgeCache]** this self

#### get

Add a keyval to the cache. Chainable.

-  `key` **[string]** The key
-  `resetAge` (optional, default `true`)

Returns **(null | any)** The retrieved value

#### has

Check whether a key exists.

-  `key` **[string]** The key

Returns **[boolean]** boolean

#### del

Delete a key and its corresponding value.

-  `key` **[string]** The key

Returns **void** void

#### keys

Returns all keys as an array.

-  `key` **[string]** The key

Returns **[Array]<[string]>** An array of string keys.

#### values

Returns all values as an array.

-  `key` **[string]** The key

Returns **[Array<any>** An array of values.

#### entries

Returns all entries as an array.

-  `key` **[string]** The key

Returns **[Array]<[Array]<string, any>>** An array of entries.

#### toObject

Returns all data as an object of the cache's keys and values.

-  `key` **[string]** The key

Returns **[object]** object

## Support

Please [open an issue](https://github.com/bemoje/shrine512/issues/new) for
support.

## Contributing

Please contribute using
[Github Flow](https://guides.github.com/introduction/flow/). Create a branch,
add commits, and
[open a pull request](https://github.com/bemoje/shrine512/compare/).

## License

Copyright (c) 2020 | [MIT](https://en.wikipedia.org/wiki/MIT_License) |
[Benjamin M Jensen](https://github.com/bemoje/) <<bemoje@gmail.com>>