keyv 3.0.0 → 3.1.0

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,12 @@ 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.
@@ -196,6 +215,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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Simple key-value storage with support for multiple backends",
   "main": "src/index.js",
   "scripts": {
@@ -32,7 +32,7 @@
     "json-buffer": "3.0.0"
   },
   "devDependencies": {
-    "ava": "^0.22.0",
+    "ava": "^0.25.0",
     "coveralls": "^3.0.0",
     "eslint-config-xo-lukechilds": "^1.0.0",
     "@keyv/mongo": "*",
@@ -44,6 +44,6 @@
     "nyc": "^11.0.3",
     "this": "^1.0.2",
     "timekeeper": "^2.0.0",
-    "xo": "^0.19.0"
+    "xo": "^0.20.1"
   }
 }

package/src/index.js

@@ -24,7 +24,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
 		);
@@ -51,7 +55,7 @@ class Keyv extends EventEmitter {
 		return Promise.resolve()
 			.then(() => store.get(key))
 			.then(data => {
-				data = (typeof data === 'string') ? JSONB.parse(data) : data;
+				data = (typeof data === 'string') ? this.opts.deserialize(data) : data;
 				if (data === undefined) {
 					return undefined;
 				}
@@ -77,7 +81,7 @@ class Keyv extends EventEmitter {
 			.then(() => {
 				const expires = (typeof ttl === 'number') ? (Date.now() + ttl) : null;
 				value = { value, expires };
-				return store.set(key, JSONB.stringify(value), ttl);
+				return store.set(key, this.opts.serialize(value), ttl);
 			})
 			.then(() => true);
 	}