# cache-list

> Cache list

Latest version **0.1.9** (published 2022-03-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install cache-list
pnpm add cache-list
yarn add cache-list
bun add cache-list
```

## 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.1.9 |
| Published | 2022-03-10 |
| First published | 2017-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.15.0 |
| Dependencies | 2 |
| Unpacked size | 101.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Vladimir Rudenko |
| Maintainers | vruden |
| Keywords | node, cache, memory cache, redis cache |

## Links

- npm: https://www.npmjs.com/package/cache-list
- Repository: https://github.com/vruden/node-cache
- Issues: https://github.com/vruden/node-cache/issues
- npm.io page: https://npm.io/package/cache-list

## Dependencies (2)

- [redis](https://npm.io/package/redis.md) ^3.0.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.4

## 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

- 0.1.9 (latest) — 2022-03-10
- 0.1.8 — 2022-03-09
- 0.1.7 — 2021-01-19
- 0.1.6 — 2021-01-19
- 0.1.5 — 2020-08-05
- 0.1.4 — 2020-07-19
- 0.1.3 — 2020-06-21
- 0.1.2 — 2020-04-19
- 0.1.1 — 2020-04-19
- 0.0.2 — 2017-11-11
- 0.0.1 — 2017-11-11

## README

# Cache List

# Install

    $ npm install cache-list

# How to use
```js
import { MemoryCache } from 'cache-list';

const cache = new MemoryCache({
    defaultDuration: 600, // 10 min
});

const data = [
    {
        name: 'Tom',
        age: 35
    },
    {
        name: 'Emma',
        age: 29
    }
];

cache.set('users', data, 3600); // 60 min

if (cache.exists('users')) {
    return cache.get('users');
}
```

# List:
* [MemoryCache](#memorycache)
* [RedisCache](#rediscache)

# Properties
* [defaultDuration](#defaultduration) [integer] - Default duration in seconds before a cache entry will expire.
* [keyPrefix](#keyprefix) [string] - A string prefixed to every cache key so that it is unique globally in the whole cache storage.
* [serialization](#serialization) [boolean] - Store serialized or unserialized cached data.

# Methods
* buildKey - Builds a normalized cache key from a given key.
* exists - Checks whether a specified key exists in the cache.
* get - Retrieves a value from cache with a specified key.
* multiGet - Retrieves multiple values from cache with the specified keys.
* set - Stores a value identified by a key into cache.
* multiSet - Stores multiple items in cache. Each item contains a value identified by a key.
* add - Stores a value identified by a key into cache if the cache does not contain this key.
* multiAdd - Stores multiple items in cache. Each item contains a value identified by a key.
* delete - Deletes a value with the specified key from cache.
* flush - Deletes all values from cache.

# Property Details
## defaultDuration
Default duration in seconds before a cache entry will expire. Default value is 0, meaning infinity. This value is used by [set()](#set) if the duration is not explicitly given.

## keyPrefix
A string prefixed to every cache key so that it is unique globally in the whole cache storage. It is recommended that you set a unique cache key prefix for each application if the same cache storage is being used by different applications.

To ensure interoperability, only alphanumeric characters should be used.

## serialization
If this property is set false, data will be directly sent to and retrieved from the cache component without any serialization or deserialization.

# Method Details
## buildKey
Builds a normalized cache key from a given key.

If the given key is a string containing alphanumeric characters only and no more than 32 characters, then the key will be returned back prefixed with [keyPrefix](#keyprefix). Otherwise, a normalized key is generated by serializing the given key, applying MD5 hashing, and prefixing with [keyPrefix](#keyprefix).

| buildKey(key)|||
| ------------- |---| ---|
| key | *mixed* | The key to be normalized |
| return | *string* | The generated cache key |

## exists
Checks whether a specified key exists in the cache.

This can be faster than getting the value from the cache if the data is big.

| exists(key)|||
| ------------- |---| ---|
| key | *mixed* | A key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key. |
| return | *boolean* | True if a value exists in cache, false if the value is not in the cache or expired. |

## get
Retrieves a value from cache with a specified key.

| get(key)|||
| ------------- |---| ---|
| key | *mixed* | A key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key. |
| return | *mixed* | The value stored in cache, false if the value is not in the cache, expired, or the dependency associated with the cached data has changed. |

## multiGet
Retrieves multiple values from cache with the specified keys.

Some caches allow retrieving multiple cached values at the same time, which may improve the performance. In case a cache does not support this feature natively, this method will try to simulate it.

| multiGet(key)|||
| ------------- |---| ---|
| key | *string[]* | List of string keys identifying the cached values |
| return | *mixed* | List of cached values corresponding to the specified keys. The array is returned in terms of (key, value) pairs. If a value is not cached or expired, the corresponding array value will be false. |

## set
Stores a value identified by a key into cache.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

| set(key, value, duration)|||
| ------------- |---| ---|
| key | *mixed* | A key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key. |
| value | *mixed* | The value to be cached |
| duration | *integer* | The number of seconds in which the cached value will expire. 0 means never expire. If not set, default [defaultDuration](#defaultduration) value is used. |
| return | *string* | Whether the value is successfully stored into cache |

## multiSet
Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

| multiSet(items, duration)|||
| ------------- |---| ---|
| items | *mixed* | The items to be cached, as key-value pairs. |
| duration | *integer* | Default number of seconds in which the cached values will expire. 0 means never expire. |
| return | *string* | Array of failed keys |

## add
Stores a value identified by a key into cache if the cache does not contain this key.

Nothing will be done if the cache already contains the key.

| add(key, value, duration)|||
| ------------- |---| ---|
| key | *mixed* | A key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key. |
| value | *mixed* | The value to be cached |
| duration | *integer* | The number of seconds in which the cached value will expire. 0 means never expire. If not set, default [defaultDuration](#defaultduration)§ value is used. |
| return | *string* | Whether the value is successfully stored into cache |

## multiAdd
Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be preserved.

| multiAdd(items, duration)|||
| ------------- |---| ---|
| items | *mixed* | The items to be cached, as key-value pairs. |
| duration | *integer* | Default number of seconds in which the cached values will expire. 0 means never expire. |
| return | *string* | Array of failed keys |

## delete
Deletes a value with the specified key from cache.

| delete(key)|||
| ------------- |---| ---|
| key | *mixed* | A key identifying the value to be deleted from cache. This can be a simple string or a complex data structure consisting of factors representing the key. |
| return | *boolean* | If no error happens during deletion |

## flush
Deletes all values from cache.

Be careful of performing this operation if the cache is shared among multiple applications.

| flush()|||
| ------------- |---| ---|
| return | *boolean* | Whether the flush operation was successful. |

## MemoryCache
Use memory as a storage.

## RedisCache
Use Redis as a storage.

### Properties
* isSharedDatabase [boolean] - If you use a separated database to store a cache, set [keyPrefix](#keyprefix)
* clientOptions [object] - Config for redis connections. You can find a full list of redis client options [here](https://www.npmjs.com/package/redis#options-object-properties).

```js
const cache = new RedisCache();

const cache = new RedisCache({
    clientOptions: {
        db: 2
    }
});

const cache = new RedisCache(
    {
        isSharedDatabase: true,
        keyPrefix: 'active_users',
        clientOptions: {
            db: 1
        }
    }
);
```

## Redis Client Options
| Property                   | Default   | Description                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| host                       | 127.0.0.1 | IP address of the Redis server                                                                                                                                                                                                                                                                                                                      |
| port                       | 6379      | Port of the Redis server                                                                                                                                                                                                                                                                                                                            |
| path                       | null      | The UNIX socket string of the Redis server                                                                                                                                                                                                                                                                                                          |
| url                        | null      | The URL of the Redis server. Format: `[redis[s]:]//[[user][:password@]][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]]` (More info avaliable at [IANA](http://www.iana.org/assignments/uri-schemes/prov/redis)).                                                                                                             |
| family                     | IPv4      | You can force using IPv6 if you set the family to 'IPv6'. See Node.js [net](https://nodejs.org/api/net.html) or [dns](https://nodejs.org/api/dns.html) modules on how to use the family type.                                                                                                                                                       |
| db                         | null      | If set, client will run Redis `select` command on connect.                                                                                                                                                                                                                                                                                          |
| password                   | null      | If set, client will run Redis auth command on connect. Alias `auth_pass` **Note** Node Redis < 2.5 must use `auth_pass`                                                                                                                                                                                                                             |
| socket_keepalive           | true      | If set to `true`, the keep-alive functionality is enabled on the underlying socket.                                                                                                                                                                                                                                                                 |
| socket_initial_delay       | 0         | Initial Delay in milliseconds, and this will also behave the interval keep alive message sending to Redis.                                                                                                                                                                                                                                          |
| enable_offline_queue       | true      | By default, if there is no active connection to the Redis server, commands are added to a queue and are executed once the connection has been established. Setting `enable_offline_queue` to `false` will disable this feature and the callback will be executed immediately with an error, or an error will be emitted if no callback is specified.|
| retry_unfulfilled_commands | false     | If set to `true`, all commands that were unfulfilled while the connection is lost will be retried after the connection has been reestablished. Use this with caution if you use state altering commands (e.g. `incr`). This is especially useful if you use blocking commands.                                                                      |
| disable_resubscribing      | false     | If set to `true`, a client won't resubscribe after disconnecting.                                                                                                                                                                                                                                                                                   |

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