keyv 2.0.1 → 4.0.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,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.1",
+  "version": "4.0.0",
   "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.20.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.24.0"
   }
 }

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,21 +50,25 @@ class Keyv extends EventEmitter {
 		return `${this.opts.namespace}:${key}`;
 	}
 
-	get(key) {
+	get(key, opts) {
 		key = this._getKeyPrefix(key);
-		const store = this.opts.store;
+		const { store } = this.opts;
 		return Promise.resolve()
 			.then(() => store.get(key))
 			.then(data => {
-				data = (typeof data === 'string') ? JSONB.parse(data) : data;
+				return (typeof data === 'string') ? this.opts.deserialize(data) : data;
+			})
+			.then(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;
 			});
 	}
 
@@ -68,31 +77,32 @@ class Keyv extends EventEmitter {
 		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(key, value, ttl))
 			.then(() => true);
 	}
 
 	delete(key) {
 		key = this._getKeyPrefix(key);
-		const store = this.opts.store;
+		const { store } = this.opts;
 		return Promise.resolve()
 			.then(() => store.delete(key));
 	}
 
 	clear() {
-		const store = this.opts.store;
+		const { store } = this.opts;
 		return Promise.resolve()
 			.then(() => store.clear());
 	}

package/.npmignore

@@ -1,77 +0,0 @@
-test/testdb.sqlite
-
-## Node
-
-#npm5
-package-lock.json
-
-# Logs
-logs
-*.log
-npm-debug.log*
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (http://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules
-jspm_packages
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional REPL history
-.node_repl_history
-
-## OS X
-
-*.DS_Store
-.AppleDouble
-.LSOverride
-
-# Icon must end with two \r
-Icon
-
-
-# Thumbnails
-._*
-
-# Files that might appear in the root of a volume
-.DocumentRevisions-V100
-.fseventsd
-.Spotlight-V100
-.TemporaryItems
-.Trashes
-.VolumeIcon.icns
-.com.apple.timemachine.donotpresent
-
-# Directories potentially created on remote AFP share
-.AppleDB
-.AppleDesktop
-Network Trash Folder
-Temporary Items
-.apdisk

package/.travis.yml

@@ -1,21 +0,0 @@
-dist: trusty
-language: node_js
-node_js:
-  - '8'
-  - '6'
-  - '4'
-services:
-  - redis-server
-  - mongodb
-  - mysql
-addons:
-  postgresql: '9.5'
-before_script:
-  - psql -c 'create database keyv_test;' -U postgres
-  - mysql -u root -e 'CREATE DATABASE keyv_test;'
-  - mysql -u root -e 'GRANT ALL PRIVILEGES ON keyv_test.* TO 'mysql'@'localhost';'
-script: npm run test:full
-after_success: npm run coverage
-notifications:
-  email:
-    on_success: never

package/media/logo.svg

@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg width="512" height="512" viewBox="0 0 512 512" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <defs>
-        <linearGradient x1="30%" y1="20%" x2="65%" y2="50%" id="gradient">
-            <stop stop-color="#24C6DC" offset="0%"></stop>
-            <stop stop-color="#C86DD7" offset="100%"></stop>
-        </linearGradient>
-    </defs>
-    <path fill="url(#gradient)" fill-rule="nonzero" d="M189 196v-17.4c13.7 10.2 40.2 15 66.5 15 26.3 0 52.8-4.8 66.5-15V196c0 12-30 21.8-66.5 21.8-36.6 0-66.5-9.8-66.5-21.8zm133 16.6v19.8c-3.7 11-32.3 19.4-66.5 19.4s-62.8-8.5-66.5-19.4v-20c13.7 10.4 40.2 15 66.5 15 26.3 0 52.8-4.6 66.5-14.8zM189 162v-17.4c13.7 10.2 40.2 15 66.5 15 26.3 0 52.8-4.8 66.5-15V162c0 12-30 22-66.5 22-36.6 0-66.5-10-66.5-22zm66.5-12c-36.7 0-66.5-10-66.5-22s29.8-21.8 66.5-21.8S322 116 322 128s-29.8 22-66.5 22zm.5 362C114.6 512 0 397.4 0 256S114.6 0 256 0s256 114.6 256 256-114.6 256-256 256zm0-3c139.7 0 253-113.3 253-253S395.6 3 256 3 3 116.4 3 256s113.3 253 253 253zM122 351.2l56-51h5l-56.5 51 59.3 60h-5l-58.7-59.7v59.8h-3.5v-111h3.4v51zm77 23.3c0 4.4.7 8.7 2 13 1.3 4.3 3.3 8 6 11.5 2.6 3.5 6 6.3 10 8.4 4 2 9 3 14.5 3 5.7 0 10.7-1 15-3.3 4.5-2 8.3-5.4 11.5-9.7l2.5 2.2c-3.5 4.6-7.7 8-12.4 10.5-4.7 2.4-10.2 3.6-16.5 3.6-5.3 0-10.2-1-14.6-3-4.5-1.8-8.3-4.5-11.5-8-3.2-3.4-5.6-7.5-7.4-12.3-1.6-5-2.5-10-2.5-15.7 0-5.5 1-10.5 2.7-15 1.8-4.7 4.2-8.7 7.3-12 3-3.4 6.7-6 11-7.8 4-2 8.6-2.8 13.4-2.8 5.6 0 10.5 1 14.7 3 4.2 2 7.7 4.6 10.4 8 3 3 5 6.8 6.3 11 1.4 4 2 8.3 2 12.6v3H199zm61-3c0-4.7-.8-9-2.4-13-1.5-3.8-3.5-7-6.2-10-2.6-2.6-5.7-4.8-9.4-6.3-3.6-1.5-7.7-2.3-12.2-2.3-5.5 0-10 1-14 3.4-4 2.2-7 5-9.5 8.3-2.5 3.3-4.3 6.8-5.4 10.4-1.3 3.7-1.8 7-1.8 9.6h61zm40.7 63.7c-1.6 4.5-4 8-6.6 10.5-2.7 2.4-6.3 3.6-10.7 3.6-1 0-2 0-3.3-.3-1.2 0-2.3-.3-3-.7l.8-3c.6.3 1.5.5 2.6.7 1 .2 2.2.3 3.2.3 2.2 0 4-.4 5.8-1.3 1.6-.8 3-2 4-3.2 1.3-1.3 2.2-2.8 3-4.4.8-1.7 1.5-3.4 2-5l7-19-28.5-74.2h3.6l26.6 70.4 25.6-70.4h3.7l-35.8 96zm76.3-24h-4.5l-28.4-72h3.8l27 68.7h.2l26-68.8h3.7L377 411.4z"></path>
-</svg>

package/test/keyv.js

@@ -1,84 +0,0 @@
-import test from 'ava';
-import tk from 'timekeeper';
-import keyvTestSuite from '@keyv/test-suite';
-import Keyv from 'this';
-
-test.serial('Keyv is a class', t => {
-	t.is(typeof Keyv, 'function');
-	t.throws(() => Keyv()); // eslint-disable-line new-cap
-	t.notThrows(() => new Keyv());
-});
-
-test.serial('Keyv accepts storage adapters', async t => {
-	const store = new Map();
-	const keyv = new Keyv({ store });
-	t.is(store.size, 0);
-	await keyv.set('foo', 'bar');
-	t.is(await keyv.get('foo'), 'bar');
-	t.is(store.size, 1);
-});
-
-test.serial('Keyv hands tll functionality over to ttl supporting stores', async t => {
-	t.plan(3);
-	const store = new Map();
-	store.ttlSupport = true;
-	const storeSet = store.set;
-	store.set = (key, val, ttl) => {
-		t.is(ttl, 100);
-		storeSet.call(store, key, val, ttl);
-	};
-	const keyv = new Keyv({ store });
-	await keyv.set('foo', 'bar', 100);
-	t.is(await keyv.get('foo'), 'bar');
-	tk.freeze(Date.now() + 150);
-	t.is(await keyv.get('foo'), 'bar');
-	tk.reset();
-});
-
-test.serial('Keyv respects default tll option', async t => {
-	const store = new Map();
-	const keyv = new Keyv({ store, ttl: 100 });
-	await keyv.set('foo', 'bar');
-	t.is(await keyv.get('foo'), 'bar');
-	tk.freeze(Date.now() + 150);
-	t.is(await keyv.get('foo'), undefined);
-	tk.reset();
-});
-
-test.serial('.set(key, val, ttl) overwrites default tll option', async t => {
-	const startTime = Date.now();
-	tk.freeze(startTime);
-	const store = new Map();
-	const keyv = new Keyv({ store, ttl: 200 });
-	await keyv.set('foo', 'bar');
-	await keyv.set('fizz', 'buzz', 100);
-	await keyv.set('ping', 'pong', 300);
-	t.is(await keyv.get('foo'), 'bar');
-	t.is(await keyv.get('fizz'), 'buzz');
-	t.is(await keyv.get('ping'), 'pong');
-	tk.freeze(startTime + 150);
-	t.is(await keyv.get('foo'), 'bar');
-	t.is(await keyv.get('fizz'), undefined);
-	t.is(await keyv.get('ping'), 'pong');
-	tk.freeze(startTime + 250);
-	t.is(await keyv.get('foo'), undefined);
-	t.is(await keyv.get('ping'), 'pong');
-	tk.freeze(startTime + 350);
-	t.is(await keyv.get('ping'), undefined);
-	tk.reset();
-});
-
-test.serial('.set(key, val, ttl) where ttl is "0" overwrites default tll option and sets key to never expire', async t => {
-	const startTime = Date.now();
-	tk.freeze(startTime);
-	const store = new Map();
-	const keyv = new Keyv({ store, ttl: 200 });
-	await keyv.set('foo', 'bar', 0);
-	t.is(await keyv.get('foo'), 'bar');
-	tk.freeze(startTime + 250);
-	t.is(await keyv.get('foo'), 'bar');
-	tk.reset();
-});
-
-const store = () => new Map();
-keyvTestSuite(test, Keyv, store);

package/test/storage-adapters/mongodb.js

@@ -1,9 +0,0 @@
-import test from 'ava';
-import keyvTestSuite, { keyvOfficialTests } from '@keyv/test-suite';
-import Keyv from 'this';
-import KeyvMongo from '@keyv/mongo';
-
-keyvOfficialTests(test, Keyv, 'mongodb://127.0.0.1:27017', 'mongodb://127.0.0.1:1234');
-
-const store = () => new KeyvMongo('mongodb://127.0.0.1:27017');
-keyvTestSuite(test, Keyv, store);

package/test/storage-adapters/mysql.js

@@ -1,9 +0,0 @@
-import test from 'ava';
-import keyvTestSuite, { keyvOfficialTests } from '@keyv/test-suite';
-import Keyv from 'this';
-import KeyvMysql from '@keyv/mysql';
-
-keyvOfficialTests(test, Keyv, 'mysql://mysql@localhost/keyv_test', 'mysql://foo');
-
-const store = () => new KeyvMysql('mysql://mysql@localhost/keyv_test');
-keyvTestSuite(test, Keyv, store);

package/test/storage-adapters/postgresql.js

@@ -1,9 +0,0 @@
-import test from 'ava';
-import keyvTestSuite, { keyvOfficialTests } from '@keyv/test-suite';
-import Keyv from 'this';
-import KeyvPostgres from '@keyv/postgres';
-
-keyvOfficialTests(test, Keyv, 'postgresql://postgres@localhost:5432/keyv_test', 'postgresql://foo');
-
-const store = () => new KeyvPostgres('postgresql://postgres@localhost:5432/keyv_test');
-keyvTestSuite(test, Keyv, store);

package/test/storage-adapters/redis.js

@@ -1,9 +0,0 @@
-import test from 'ava';
-import keyvTestSuite, { keyvOfficialTests } from '@keyv/test-suite';
-import Keyv from 'this';
-import KeyvRedis from '@keyv/redis';
-
-keyvOfficialTests(test, Keyv, 'redis://localhost', 'redis://foo');
-
-const store = () => new KeyvRedis('redis://localhost');
-keyvTestSuite(test, Keyv, store);

package/test/storage-adapters/sqlite.js

@@ -1,9 +0,0 @@
-import test from 'ava';
-import keyvTestSuite, { keyvOfficialTests } from '@keyv/test-suite';
-import Keyv from 'this';
-import KeyvSqlite from '@keyv/sqlite';
-
-keyvOfficialTests(test, Keyv, 'sqlite://test/testdb.sqlite', 'sqlite://non/existent/database.sqlite');
-
-const store = () => new KeyvSqlite('sqlite://test/testdb.sqlite');
-keyvTestSuite(test, Keyv, store);