keyv 2.0.2 → 4.0.1

package/README.md

@@ -8,6 +8,7 @@
 
 [![Build Status](https://travis-ci.org/lukechilds/keyv.svg?branch=master)](https://travis-ci.org/lukechilds/keyv)
 [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv?branch=master)
+[![npm](https://img.shields.io/npm/dm/keyv.svg)](https://www.npmjs.com/package/keyv)
 [![npm](https://img.shields.io/npm/v/keyv.svg)](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.
@@ -21,7 +22,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 - 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 JavaScript types (values can be `Buffer`/`null`/`undefined`)
+- 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)
@@ -59,7 +60,7 @@ 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));
+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
@@ -85,6 +86,18 @@ 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.
@@ -124,6 +137,15 @@ 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
+- [keyv-firestore ](https://github.com/goto-bus-stop/keyv-firestore) – Firebase Cloud Firestore adapter for Keyv
+- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft Sql Server adapter for Keyv
+- [keyv-memcache](https://github.com/jaredwray/keyv-memcache) - Memcache 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.
@@ -196,6 +218,20 @@ Default: `undefined`
 
 Default TTL. Can be overridden by specififying a TTL on `.set()`.
 
+#### options.serialize
+
+Type: `Function`<br>
+Default: `JSONB.stringify`
+
+A custom serialization function.
+
+#### options.deserialize
+
+Type: `Function`<br>
+Default: `JSONB.parse`
+
+A custom deserialization function.
+
 #### options.store
 
 Type: `Storage adapter instance`<br>
@@ -220,23 +256,32 @@ Set a value.
 
 By default keys are persistent. You can set an expiry TTL in milliseconds.
 
-Returns `true`.
+Returns a promise which resolves to `true`.
+
+#### .get(key, [options])
+
+Returns a promise which resolves to the retrieved value.
+
+##### options.raw
+
+Type: `Boolean`<br>
+Default: `false`
 
-#### .get(key)
+If set to true the raw DB object Keyv stores internally will be returned instead of just the value.
 
-Returns the value.
+This contains the TTL timestamp.
 
 #### .delete(key)
 
 Deletes an entry.
 
-Returns `true` if the key existed, `false` if not.
+Returns a promise which resolves to `true` if the key existed, `false` if not.
 
 #### .clear()
 
 Delete all entries in the current namespace.
 
-Returns `undefined`.
+Returns a promise which is resolved when the entries have been cleared.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv",
-  "version": "2.0.2",
+  "version": "4.0.1",
   "description": "Simple key-value storage with support for multiple backends",
   "main": "src/index.js",
   "scripts": {
@@ -29,11 +29,11 @@
   },
   "homepage": "https://github.com/lukechilds/keyv",
   "dependencies": {
-    "json-buffer": "3.0.0"
+    "json-buffer": "3.0.1"
   },
   "devDependencies": {
-    "ava": "^0.22.0",
-    "coveralls": "^2.13.1",
+    "ava": "^2.2.0",
+    "coveralls": "^3.0.0",
     "eslint-config-xo-lukechilds": "^1.0.0",
     "@keyv/mongo": "*",
     "@keyv/mysql": "*",
@@ -41,9 +41,9 @@
     "@keyv/redis": "*",
     "@keyv/sqlite": "*",
     "@keyv/test-suite": "*",
-    "nyc": "^11.0.3",
+    "nyc": "^14.1.1",
     "this": "^1.0.2",
-    "timekeeper": "^1.0.0",
-    "xo": "^0.19.0"
+    "timekeeper": "^2.0.0",
+    "xo": "^0.25.3"
   }
 }

package/src/index.js

@@ -17,6 +17,7 @@ const loadStore = opts => {
 		const adapter = opts.adapter || /^[^:]*/.exec(opts.uri)[0];
 		return new (require(adapters[adapter]))(opts);
 	}
+
 	return new Map();
 };
 
@@ -24,7 +25,11 @@ class Keyv extends EventEmitter {
 	constructor(uri, opts) {
 		super();
 		this.opts = Object.assign(
-			{ namespace: 'keyv' },
+			{
+				namespace: 'keyv',
+				serialize: JSONB.stringify,
+				deserialize: JSONB.parse
+			},
 			(typeof uri === 'string') ? { uri } : uri,
 			opts
 		);
@@ -45,54 +50,59 @@ class Keyv extends EventEmitter {
 		return `${this.opts.namespace}:${key}`;
 	}
 
-	get(key) {
-		key = this._getKeyPrefix(key);
-		const store = this.opts.store;
+	get(key, opts) {
+		const keyPrefixed = this._getKeyPrefix(key);
+		const { store } = this.opts;
 		return Promise.resolve()
-			.then(() => store.get(key))
+			.then(() => store.get(keyPrefixed))
+			.then(data => {
+				return (typeof data === 'string') ? this.opts.deserialize(data) : data;
+			})
 			.then(data => {
-				data = (typeof data === 'string') ? JSONB.parse(data) : data;
 				if (data === undefined) {
 					return undefined;
 				}
-				if (!store.ttlSupport && typeof data.expires === 'number' && Date.now() > data.expires) {
+
+				if (typeof data.expires === 'number' && Date.now() > data.expires) {
 					this.delete(key);
 					return undefined;
 				}
-				return store.ttlSupport ? data : data.value;
+
+				return (opts && opts.raw) ? data : data.value;
 			});
 	}
 
 	set(key, value, ttl) {
-		key = this._getKeyPrefix(key);
+		const keyPrefixed = this._getKeyPrefix(key);
 		if (typeof ttl === 'undefined') {
 			ttl = this.opts.ttl;
 		}
+
 		if (ttl === 0) {
 			ttl = undefined;
 		}
-		const store = this.opts.store;
+
+		const { store } = this.opts;
 
 		return Promise.resolve()
 			.then(() => {
-				if (!store.ttlSupport) {
-					const expires = (typeof ttl === 'number') ? (Date.now() + ttl) : null;
-					value = { value, expires };
-				}
-				return store.set(key, JSONB.stringify(value), ttl);
+				const expires = (typeof ttl === 'number') ? (Date.now() + ttl) : null;
+				value = { value, expires };
+				return this.opts.serialize(value);
 			})
+			.then(value => store.set(keyPrefixed, value, ttl))
 			.then(() => true);
 	}
 
 	delete(key) {
-		key = this._getKeyPrefix(key);
-		const store = this.opts.store;
+		const keyPrefixed = this._getKeyPrefix(key);
+		const { store } = this.opts;
 		return Promise.resolve()
-			.then(() => store.delete(key));
+			.then(() => store.delete(keyPrefixed));
 	}
 
 	clear() {
-		const store = this.opts.store;
+		const { store } = this.opts;
 		return Promise.resolve()
 			.then(() => store.clear());
 	}