src/index.js 0000664 00000004367 15112354336 0007017 0 ustar 00 'use strict';
const EventEmitter = require('events');
const JSONB = require('json-buffer');
const loadStore = opts => {
const adapters = {
redis: '@keyv/redis',
mongodb: '@keyv/mongo',
mongo: '@keyv/mongo',
sqlite: '@keyv/sqlite',
postgresql: '@keyv/postgres',
postgres: '@keyv/postgres',
mysql: '@keyv/mysql'
};
if (opts.adapter || opts.uri) {
const adapter = opts.adapter || /^[^:]*/.exec(opts.uri)[0];
return new (require(adapters[adapter]))(opts);
}
return new Map();
};
class Keyv extends EventEmitter {
constructor(uri, opts) {
super();
this.opts = Object.assign(
{
namespace: 'keyv',
serialize: JSONB.stringify,
deserialize: JSONB.parse
},
(typeof uri === 'string') ? { uri } : uri,
opts
);
if (!this.opts.store) {
const adapterOpts = Object.assign({}, this.opts);
this.opts.store = loadStore(adapterOpts);
}
if (typeof this.opts.store.on === 'function') {
this.opts.store.on('error', err => this.emit('error', err));
}
this.opts.store.namespace = this.opts.namespace;
}
_getKeyPrefix(key) {
return `${this.opts.namespace}:${key}`;
}
get(key) {
key = this._getKeyPrefix(key);
const store = this.opts.store;
return Promise.resolve()
.then(() => store.get(key))
.then(data => {
data = (typeof data === 'string') ? this.opts.deserialize(data) : data;
if (data === undefined) {
return undefined;
}
if (typeof data.expires === 'number' && Date.now() > data.expires) {
this.delete(key);
return undefined;
}
return data.value;
});
}
set(key, value, ttl) {
key = this._getKeyPrefix(key);
if (typeof ttl === 'undefined') {
ttl = this.opts.ttl;
}
if (ttl === 0) {
ttl = undefined;
}
const store = this.opts.store;
return Promise.resolve()
.then(() => {
const expires = (typeof ttl === 'number') ? (Date.now() + ttl) : null;
value = { value, expires };
return store.set(key, this.opts.serialize(value), ttl);
})
.then(() => true);
}
delete(key) {
key = this._getKeyPrefix(key);
const store = this.opts.store;
return Promise.resolve()
.then(() => store.delete(key));
}
clear() {
const store = this.opts.store;
return Promise.resolve()
.then(() => store.clear());
}
}
module.exports = Keyv;
LICENSE 0000664 00000002054 15112354336 0005557 0 ustar 00 MIT License
Copyright (c) 2017 Luke Childs
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md 0000664 00000023603 15112354336 0006034 0 ustar 00
> Simple key-value storage with support for multiple backends
[](https://travis-ci.org/lukechilds/keyv)
[](https://coveralls.io/github/lukechilds/keyv?branch=master)
[](https://www.npmjs.com/package/keyv)
[](https://www.npmjs.com/package/keyv)
Keyv provides a consistent interface for key-value storage across multiple backends via storage adapters. It supports TTL based expiry, making it suitable as a cache or a persistent key-value store.
## Features
There are a few existing modules similar to Keyv, however Keyv is different because it:
- Isn't bloated
- Has a simple Promise based API
- Suitable as a TTL based cache or persistent key-value store
- [Easily embeddable](#add-cache-support-to-your-module) inside another module
- Works with any storage that implements the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API
- Handles all JSON types plus `Buffer`
- Supports namespaces
- Wide range of [**efficient, well tested**](#official-storage-adapters) storage adapters
- Connection errors are passed through (db failures won't kill your app)
- Supports the current active LTS version of Node.js or higher
## Usage
Install Keyv.
```
npm install --save keyv
```
By default everything is stored in memory, you can optionally also install a storage adapter.
```
npm install --save @keyv/redis
npm install --save @keyv/mongo
npm install --save @keyv/sqlite
npm install --save @keyv/postgres
npm install --save @keyv/mysql
```
Create a new Keyv instance, passing your connection string if applicable. Keyv will automatically load the correct storage adapter.
```js
const Keyv = require('keyv');
// One of the following
const keyv = new Keyv();
const keyv = new Keyv('redis://user:pass@localhost:6379');
const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');
const keyv = new Keyv('sqlite://path/to/database.sqlite');
const keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');
const keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');
// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));
await keyv.set('foo', 'expires in 1 second', 1000); // true
await keyv.set('foo', 'never expires'); // true
await keyv.get('foo'); // 'never expires'
await keyv.delete('foo'); // true
await keyv.clear(); // undefined
```
### Namespaces
You can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.
```js
const users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });
const cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });
await users.set('foo', 'users'); // true
await cache.set('foo', 'cache'); // true
await users.get('foo'); // 'users'
await cache.get('foo'); // 'cache'
await users.clear(); // undefined
await users.get('foo'); // undefined
await cache.get('foo'); // 'cache'
```
### Custom Serializers
Keyv uses [`json-buffer`](https://github.com/dominictarr/json-buffer) for data serialization to ensure consistency across different backends.
You can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.
```js
const keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });
```
**Warning:** Using custom serializers means you lose any guarantee of data consistency. You should do extensive testing with your serialisation functions and chosen storage engine.
## Official Storage Adapters
The official storage adapters are covered by [over 150 integration tests](https://travis-ci.org/lukechilds/keyv/jobs/260418145) to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.
Database | Adapter | Native TTL | Status
---|---|---|---
Redis | [@keyv/redis](https://github.com/lukechilds/keyv-redis) | Yes | [](https://travis-ci.org/lukechilds/keyv-redis) [](https://coveralls.io/github/lukechilds/keyv-redis?branch=master)
MongoDB | [@keyv/mongo](https://github.com/lukechilds/keyv-mongo) | Yes | [](https://travis-ci.org/lukechilds/keyv-mongo) [](https://coveralls.io/github/lukechilds/keyv-mongo?branch=master)
SQLite | [@keyv/sqlite](https://github.com/lukechilds/keyv-sqlite) | No | [](https://travis-ci.org/lukechilds/keyv-sqlite) [](https://coveralls.io/github/lukechilds/keyv-sqlite?branch=master)
PostgreSQL | [@keyv/postgres](https://github.com/lukechilds/keyv-postgres) | No | [](https://travis-ci.org/lukechildskeyv-postgreskeyv) [](https://coveralls.io/github/lukechilds/keyv-postgres?branch=master)
MySQL | [@keyv/mysql](https://github.com/lukechilds/keyv-mysql) | No | [](https://travis-ci.org/lukechilds/keyv-mysql) [](https://coveralls.io/github/lukechilds/keyv-mysql?branch=master)
## Third-party Storage Adapters
You can also use third-party storage adapters or build your own. Keyv will wrap these storage adapters in TTL functionality and handle complex types internally.
```js
const Keyv = require('keyv');
const myAdapter = require('./my-storage-adapter');
const keyv = new Keyv({ store: myAdapter });
```
Any store that follows the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) api will work.
```js
new Keyv({ store: new Map() });
```
For example, [`quick-lru`](https://github.com/sindresorhus/quick-lru) is a completely unrelated module that implements the Map API.
```js
const Keyv = require('keyv');
const QuickLRU = require('quick-lru');
const lru = new QuickLRU({ maxSize: 1000 });
const keyv = new Keyv({ store: lru });
```
The following are third-party storage adapters compatible with Keyv:
- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple "Least Recently Used" (LRU) cache
- [keyv-file](https://github.com/zaaack/keyv-file) - File system storage adapter for Keyv
- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv
## Add Cache Support to your Module
Keyv is designed to be easily embedded into other modules to add cache support. The recommended pattern is to expose a `cache` option in your modules options which is passed through to Keyv. Caching will work in memory by default and users have the option to also install a Keyv storage adapter and pass in a connection string, or any other storage that implements the `Map` API.
You should also set a namespace for your module so you can safely call `.clear()` without clearing unrelated app data.
Inside your module:
```js
class AwesomeModule {
constructor(opts) {
this.cache = new Keyv({
uri: typeof opts.cache === 'string' && opts.cache,
store: typeof opts.cache !== 'string' && opts.cache,
namespace: 'awesome-module'
});
}
}
```
Now it can be consumed like this:
```js
const AwesomeModule = require('awesome-module');
// Caches stuff in memory by default
const awesomeModule = new AwesomeModule();
// After npm install --save keyv-redis
const awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });
// Some third-party module that implements the Map API
const awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });
```
## API
### new Keyv([uri], [options])
Returns a new Keyv instance.
The Keyv instance is also an `EventEmitter` that will emit an `'error'` event if the storage adapter connection fails.
### uri
Type: `String`
Default: `undefined`
The connection string URI.
Merged into the options object as options.uri.
### options
Type: `Object`
The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.
#### options.namespace
Type: `String`
Default: `'keyv'`
Namespace for the current instance.
#### options.ttl
Type: `Number`
Default: `undefined`
Default TTL. Can be overridden by specififying a TTL on `.set()`.
#### options.serialize
Type: `Function`
Default: `JSONB.stringify`
A custom serialization function.
#### options.deserialize
Type: `Function`
Default: `JSONB.parse`
A custom deserialization function.
#### options.store
Type: `Storage adapter instance`
Default: `new Map()`
The storage adapter instance to be used by Keyv.
#### options.adapter
Type: `String`
Default: `undefined`
Specify an adapter to use. e.g `'redis'` or `'mongodb'`.
### Instance
Keys must always be strings. Values can be of any type.
#### .set(key, value, [ttl])
Set a value.
By default keys are persistent. You can set an expiry TTL in milliseconds.
Returns `true`.
#### .get(key)
Returns the value.
#### .delete(key)
Deletes an entry.
Returns `true` if the key existed, `false` if not.
#### .clear()
Delete all entries in the current namespace.
Returns `undefined`.
## License
MIT © Luke Childs
package.json 0000664 00000003652 15112354336 0007045 0 ustar 00 {
"_args": [
[
"keyv@3.1.0",
"/home/freeclou/app.optimyar.com/backend"
]
],
"_from": "keyv@3.1.0",
"_id": "keyv@3.1.0",
"_inBundle": false,
"_integrity": "sha512-9ykJ/46SN/9KPM/sichzQ7OvXyGDYKGTaDlKMGCAlg2UK8KRy4jb0d8sFc+0Tt0YYnThq8X2RZgCg74RPxgcVA==",
"_location": "/keyv",
"_phantomChildren": {},
"_requested": {
"type": "version",
"registry": true,
"raw": "keyv@3.1.0",
"name": "keyv",
"escapedName": "keyv",
"rawSpec": "3.1.0",
"saveSpec": null,
"fetchSpec": "3.1.0"
},
"_requiredBy": [
"/cacheable-request"
],
"_resolved": "https://registry.npmjs.org/keyv/-/keyv-3.1.0.tgz",
"_spec": "3.1.0",
"_where": "/home/freeclou/app.optimyar.com/backend",
"author": {
"name": "Luke Childs",
"email": "lukechilds123@gmail.com",
"url": "http://lukechilds.co.uk"
},
"bugs": {
"url": "https://github.com/lukechilds/keyv/issues"
},
"dependencies": {
"json-buffer": "3.0.0"
},
"description": "Simple key-value storage with support for multiple backends",
"devDependencies": {
"@keyv/mongo": "*",
"@keyv/mysql": "*",
"@keyv/postgres": "*",
"@keyv/redis": "*",
"@keyv/sqlite": "*",
"@keyv/test-suite": "*",
"ava": "^0.25.0",
"coveralls": "^3.0.0",
"eslint-config-xo-lukechilds": "^1.0.0",
"nyc": "^11.0.3",
"this": "^1.0.2",
"timekeeper": "^2.0.0",
"xo": "^0.20.1"
},
"homepage": "https://github.com/lukechilds/keyv",
"keywords": [
"key",
"value",
"store",
"cache",
"ttl"
],
"license": "MIT",
"main": "src/index.js",
"name": "keyv",
"repository": {
"type": "git",
"url": "git+https://github.com/lukechilds/keyv.git"
},
"scripts": {
"coverage": "nyc report --reporter=text-lcov | coveralls",
"test": "xo && nyc ava test/keyv.js",
"test:full": "xo && nyc ava --serial"
},
"version": "3.1.0",
"xo": {
"extends": "xo-lukechilds"
}
}