Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/outofsyncstudios/object-key-cache
An object cache extension for Redis and MemoryCache
https://github.com/outofsyncstudios/object-key-cache
cache javascript nodejs npm open-source
Last synced: about 2 months ago
JSON representation
An object cache extension for Redis and MemoryCache
- Host: GitHub
- URL: https://github.com/outofsyncstudios/object-key-cache
- Owner: OutOfSyncStudios
- License: mit
- Created: 2018-02-26T18:24:59.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-09T23:18:35.000Z (5 months ago)
- Last Synced: 2024-08-10T09:05:10.697Z (5 months ago)
- Topics: cache, javascript, nodejs, npm, open-source
- Language: JavaScript
- Homepage:
- Size: 479 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# object-key-cache
[](https://nodei.co/npm/@outofsync/object-key-cache/)
[](https://www.npmjs.org/package/@outofsync/object-key-cache)
[
[](https://www.npmjs.org/package/@outofsync/object-key-cache)
[](https://www.codacy.com/gh/OutOfSyncStudios/object-key-cache/dashboard?utm_source=github.com&utm_medium=referral&utm_content=OutOfSyncStudios/object-key-cache&utm_campaign=Badge_Grade)
[](https://www.codacy.com/gh/OutOfSyncStudios/object-key-cache/dashboard?utm_source=github.com&utm_medium=referral&utm_content=OutOfSyncStudios/object-key-cache&utm_campaign=Badge_Coverage)
[](https://david-dm.org/OutOfSyncStudios/object-key-cache?view=list)
`object-key-cache` is a promise-based, object-key, cache extension for the [Redis](https://www.npmjs.com/package/redis) and [memory-cache](https://www.npmjs.com/package/@outofsync/memory-cache) modules.
Object Key Cache converts JavaScript Objects (Maps) into the key value used to look up data from cache. This is done by serializing the object into JSON (e.g. `JSON.stringify`) and then performing a SHA256 has on the resulting JSON string. This process helps preserve the uniqueness of the key for performing lookups. Once the key has been generated, the key-value pair is passed into the associated Oxxx functions (e.g. oget, oset, etc.)
*Note:* SHA512 has a very low likelihood of key space collisions, but it is not impossible. With one billion messages there is approximately a 1 in 1.4 x 1077 chance that two distinct strings will generate an identical SHA512 hash. This probability is negligible for most use cases; however, if a very large numbers of keys are expected to be stored then consideration should be given to segregating data by a namespace based upon how it will be used within the cache to decrease any potential for collisions.
This module has been updated to support NodeJS 18 or higher.
# [Installation](#installation)
```shell
npm install @outofsync/object-key-cache
```
```js
const ObjectKeyCache = require('@outofsync/object-key-cache');
const objKeyCache = new ObjectKeyCache();
const testObj = { name: 'test key' };
objKeyCache.connect()
.then(() => {
return objKeyCache.oset(testObj, 100);
})
.then(() => {
return objKeyCache.oget(testObj);
})
.then((result) => {
console.log(result); // 100
return objKeyCache.close();
})
.catch((err) => {
// Do something meaningful
});
```
# [API Reference](#api)
With noted exceptions, all functions are Promise-based (meaning they return a Promise which should be handled)
## constructor(options [, redisCredentials] [, log])
Create a new ObjectKeyCache client with the passed options, credentials, and logger. The `options` support only value `failover` which defaults to `true` and causes any connection attempts to Redis to fail-back to the memory Cache. Any other options provided are passed along to the Redis or MemoryCache `createClient` function. If [`redisCredentials`](#redis-credentials) are passed, then ObjectKeyCache will attempt to connect to Redis. If they are omitted or set `null` then Memory Cache is used. The [`log`](#logging-obj) is a Logging object outlined below.
## .attachToClient(redisClient)
Attaches an unconnected ObjectKeyCache to an already existing and connected RedisClient.
## .detachFromClient()
Detaches ObjectKeyCache from a connected RedisClient.
## .connect() ⟾ Promise
Connects to the cache and set the `connected` flag to `true`. The Promise resolves to the cache connection.
## .close() ⟾ Promise
Disconnects from the cache and set the `connected` flag to `false`. The promise resolves to the cache connection.
## .calcObjKey(obj) ⟾ string
Returns the SHA256 Hash of the message resulting from the JSON stringified `obj`.
## .clear() ⟾ Promise
Clears the cache for the currently connected database within the cache. This is equivalent to running `FLUSHDB`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .oget(obj) ⟾ Promise
Retrieves a value stored with the object key `obj`. The promise resolves to the result or `null` if it doesn't exist.
## .oset(obj, value) ⟾ Promise
Sets a value with an object key `obj`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .odel(obj) ⟾ Promise
Deletes the object key `obj`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .ohget(hash, obj) ⟾ Promise
Retrieves the Hash object key `obj` field that is scoped to the `hash`. The promise resolves to the result or `null` if it doesn't exist.
## .ohset(hash, obj, value) ⟾ Promise
Sets the Hash object key `obj` field that is scoped to the `hash` to value `value`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .ohdel(hash, obj) ⟾ Promise
Deletes the object key `obj` field scoped to the `hash`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .get(key) ⟾ Promise
Retrieves the `key` from the cache. The promise resolves to the result or `null` if it does not exist.
## .set(key, value) ⟾ Promise
Sets the `key` to the `value`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .del(key) ⟾ Promise
Deletes the `key`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .hget(hash, field) ⟾ Promise
Retrieves the `field` that is scoped to the `hash`. The promise resolves to the result or `null` if it does not exist.
## .hset(hash, field, value) ⟾ Promise
Sets the `field` that is scoped to the `hash` to the `value`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## .hdel(hash, field) ⟾ Promise
Deletes the `field` scoped to the `hash`. The promise resolves to the Redis/MemoryCache messages (usually 'OK').
## [Redis Credentials](#redis-credentials)
The Redis credentials define how to connect to Redis and are an object as follows:
```js
{
port: 6379,
host: 'localhost'
}
```
## [Logging Object](#logging-obj)
The Logging object is an instance of any logging library, such as [Winston](https://www.npmjs.com/package/winston) or [Bunyan](https://www.npmjs.com/package/bunyan), which support the `.error(...)`, `.info(...)`, `.debug(...)`, and `.log(...)` methods. If this is not provided, then any debug or error messages are sent to `/dev/null`.
Copyright (c) 2018-2019 Jay Reardon
Copyright (c) 2019-2021 Out of Sync Studios LLC -- Licensed under the MIT license.