{"_id":"@amitic/keyv","name":"@amitic/keyv","dist-tags":{"latest":"4.0.3-multi.1"},"versions":{"4.0.3-multi.1":{"name":"@amitic/keyv","version":"4.0.3-multi.1","description":"Simple key-value storage with support for multiple backends","main":"src/index.js","scripts":{"test":"xo && nyc ava test/keyv.js","test:full":"xo && nyc ava --serial","coverage":"nyc report --reporter=text-lcov | coveralls"},"xo":{"extends":"xo-lukechilds"},"repository":{"type":"git","url":"git+https://github.com/amitic/keyv.git"},"keywords":["key","value","store","cache","ttl"],"author":{"name":"Luke Childs","email":"lukechilds123@gmail.com","url":"http://lukechilds.co.uk"},"license":"MIT","bugs":{"url":"https://github.com/amitic/keyv/issues"},"homepage":"https://github.com/amitic/keyv","dependencies":{"json-buffer":"3.0.1"},"devDependencies":{"ava":"^2.2.0","coveralls":"^3.0.0","eslint-config-xo-lukechilds":"^1.0.0","@keyv/mongo":"*","@keyv/mysql":"*","@keyv/postgres":"*","@keyv/redis":"*","@keyv/sqlite":"*","@keyv/test-suite":"*","nyc":"^14.1.1","this":"^1.0.2","timekeeper":"^2.0.0","xo":"^0.25.3"},"gitHead":"30ff2852565d677a917bb3c02f399f79de7e5737","_id":"@amitic/keyv@4.0.3-multi.1","_nodeVersion":"14.15.1","_npmVersion":"6.14.8","dist":{"integrity":"sha512-hm5ltnrgIcfIBgvo9WXJB84yi1Dcm7DtaB7i0Y1oENi/2Fk6qsNV8ue8IMUQkvmcmrEnNrO+N+a8fLIDM0lS2w==","shasum":"d201c25b654ac5c439da7eb93a923966edffdd3c","tarball":"https://registry.npmjs.org/@amitic/keyv/-/keyv-4.0.3-multi.1.tgz","fileCount":4,"unpackedSize":17826,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDraLdqIvjw1I5uePEkQBXUI+w+9T8F4pMI6IGq8R8lcQIgUP5GpQpFBWMGRyjwCB7H8ylcPypHdxKGCQP/QeZAMEY="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjRZZ5ACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpPFg/+P2lnw2eG0ZTbYtRg1YrCo2mFLIi6x3f5ioScyhTC5dYYjDUM\r\nFLGW8FEjzyycSzJb+3r0aHTupiYAW9XdIWyfSOnTLca1c9onLtemHoKQ2Cfe\r\nae2hj2e7vMfUDn65dTVyzUPv8JLZoL/fcm/JXIQul0rpCtrSHHrUUkH4wwr1\r\nmJ0/GLggdz14VwNretCdeX7Ilh6UW9iFGXGf1UgH6SIDXAQfbaAfhGNy0ld/\r\n9pt9lmZIGp4mC7QiVIuEVv8TVlEi6O4+1UuuQ6QK2Thp+RYxLHBifSKioOHL\r\nd30R2A9cdOqM0vVomxmlgfBDPUNQ0BDDjcLW0SoBm75Jlt9RbqpjfETwmgvv\r\nEOv31icXHXioOBUfhXk5bNp2xuK+CxbBw9B2War2GIhUcnF4l7phVCxw3vG0\r\nUf+A7tzsep7Zx5aN/OAHqeLK4k0m0ezDngUd16BLW3GLsStMaFX65WaZRiv8\r\nKuxGqzMJseldnBtQe/uJInY8i46hx6QVht7hdmujvzz7Xy4Y1eDlmX7e/Vpk\r\nOx9aQ5/jDZx8/ggQz2/ETXhkVgnV5K8HYt5qLhMA6neeoNjp0PkDPNe6Zp7K\r\ntInUpI037vNlrjZ60IwV8+4/lkCgrzHVzRO0Kzgd2J2H8nYDp7yBWsvTtAsj\r\n4WNaPHX3R+s6wpX7GV/MbmcuLq6zi3bzGhg=\r\n=+EEd\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"amitic","email":"amitic@gmail.com"},"directories":{},"maintainers":[{"name":"amitic","email":"amitic@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/keyv_4.0.3-multi.1_1665504888968_0.21239990956935628"},"_hasShrinkwrap":false}},"time":{"created":"2022-10-11T16:14:48.923Z","4.0.3-multi.1":"2022-10-11T16:14:49.236Z","modified":"2022-10-11T16:14:49.366Z"},"maintainers":[{"name":"amitic","email":"amitic@gmail.com"}],"description":"Simple key-value storage with support for multiple backends","homepage":"https://github.com/amitic/keyv","keywords":["key","value","store","cache","ttl"],"repository":{"type":"git","url":"git+https://github.com/amitic/keyv.git"},"author":{"name":"Luke Childs","email":"lukechilds123@gmail.com","url":"http://lukechilds.co.uk"},"bugs":{"url":"https://github.com/amitic/keyv/issues"},"license":"MIT","readme":"

\n\t\"keyv\"\n\t
\n\t
\n

\n\n> Simple key-value storage with support for multiple backends\n\n[![Build Status](https://travis-ci.org/lukechilds/keyv.svg?branch=master)](https://travis-ci.org/lukechilds/keyv)\n[![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv?branch=master)\n[![npm](https://img.shields.io/npm/dm/keyv.svg)](https://www.npmjs.com/package/keyv)\n[![npm](https://img.shields.io/npm/v/keyv.svg)](https://www.npmjs.com/package/keyv)\n\nKeyv 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.\n\n## Features\n\nThere are a few existing modules similar to Keyv, however Keyv is different because it:\n\n- Isn't bloated\n- Has a simple Promise based API\n- Suitable as a TTL based cache or persistent key-value store\n- [Easily embeddable](#add-cache-support-to-your-module) inside another module\n- Works with any storage that implements the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API\n- Handles all JSON types plus `Buffer`\n- Supports namespaces\n- Wide range of [**efficient, well tested**](#official-storage-adapters) storage adapters\n- Connection errors are passed through (db failures won't kill your app)\n- Supports the current active LTS version of Node.js or higher\n\n## Usage\n\nInstall Keyv.\n\n```\nnpm install --save keyv\n```\n\nBy default everything is stored in memory, you can optionally also install a storage adapter.\n\n```\nnpm install --save @keyv/redis\nnpm install --save @keyv/mongo\nnpm install --save @keyv/sqlite\nnpm install --save @keyv/postgres\nnpm install --save @keyv/mysql\n```\n\nCreate a new Keyv instance, passing your connection string if applicable. Keyv will automatically load the correct storage adapter.\n\n```js\nconst Keyv = require('keyv');\n\n// One of the following\nconst keyv = new Keyv();\nconst keyv = new Keyv('redis://user:pass@localhost:6379');\nconst keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');\nconst keyv = new Keyv('sqlite://path/to/database.sqlite');\nconst keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');\nconst keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');\n\n// Handle DB connection errors\nkeyv.on('error', err => console.log('Connection Error', err));\n\nawait keyv.set('foo', 'expires in 1 second', 1000); // true\nawait keyv.set('foo', 'never expires'); // true\nawait keyv.get('foo'); // 'never expires'\nawait keyv.delete('foo'); // true\nawait keyv.clear(); // undefined\n```\n\n### Namespaces\n\nYou can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.\n\n```js\nconst users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });\nconst cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });\n\nawait users.set('foo', 'users'); // true\nawait cache.set('foo', 'cache'); // true\nawait users.get('foo'); // 'users'\nawait cache.get('foo'); // 'cache'\nawait users.clear(); // undefined\nawait users.get('foo'); // undefined\nawait cache.get('foo'); // 'cache'\n```\n\n### Custom Serializers\n\nKeyv uses [`json-buffer`](https://github.com/dominictarr/json-buffer) for data serialization to ensure consistency across different backends.\n\nYou can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.\n\n```js\nconst keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });\n```\n\n**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.\n\n## Official Storage Adapters\n\nThe 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.\n\nDatabase | Adapter | Native TTL | Status\n---|---|---|---\nRedis | [@keyv/redis](https://github.com/lukechilds/keyv-redis) | Yes | [![Build Status](https://travis-ci.org/lukechilds/keyv-redis.svg?branch=master)](https://travis-ci.org/lukechilds/keyv-redis) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv-redis/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv-redis?branch=master)\nMongoDB | [@keyv/mongo](https://github.com/lukechilds/keyv-mongo) | Yes | [![Build Status](https://travis-ci.org/lukechilds/keyv-mongo.svg?branch=master)](https://travis-ci.org/lukechilds/keyv-mongo) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv-mongo/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv-mongo?branch=master)\nSQLite | [@keyv/sqlite](https://github.com/lukechilds/keyv-sqlite) | No | [![Build Status](https://travis-ci.org/lukechilds/keyv-sqlite.svg?branch=master)](https://travis-ci.org/lukechilds/keyv-sqlite) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv-sqlite/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv-sqlite?branch=master)\nPostgreSQL | [@keyv/postgres](https://github.com/lukechilds/keyv-postgres) | No | [![Build Status](https://travis-ci.org/lukechilds/keyv-postgres.svg?branch=master)](https://travis-ci.org/lukechildskeyv-postgreskeyv) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv-postgres/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv-postgres?branch=master)\nMySQL | [@keyv/mysql](https://github.com/lukechilds/keyv-mysql) | No | [![Build Status](https://travis-ci.org/lukechilds/keyv-mysql.svg?branch=master)](https://travis-ci.org/lukechilds/keyv-mysql) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/keyv-mysql/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/keyv-mysql?branch=master)\n\n## Third-party Storage Adapters\n\nYou 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.\n\n```js\nconst Keyv = require('keyv');\nconst myAdapter = require('./my-storage-adapter');\n\nconst keyv = new Keyv({ store: myAdapter });\n```\n\nAny store that follows the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) api will work.\n\n```js\nnew Keyv({ store: new Map() });\n```\n\nFor example, [`quick-lru`](https://github.com/sindresorhus/quick-lru) is a completely unrelated module that implements the Map API.\n\n```js\nconst Keyv = require('keyv');\nconst QuickLRU = require('quick-lru');\n\nconst lru = new QuickLRU({ maxSize: 1000 });\nconst keyv = new Keyv({ store: lru });\n```\n\nThe following are third-party storage adapters compatible with Keyv:\n\n- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple \"Least Recently Used\" (LRU) cache\n- [keyv-file](https://github.com/zaaack/keyv-file) - File system storage adapter for Keyv\n- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv\n- [keyv-firestore ](https://github.com/goto-bus-stop/keyv-firestore) – Firebase Cloud Firestore adapter for Keyv\n- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft Sql Server adapter for Keyv\n- [keyv-memcache](https://github.com/jaredwray/keyv-memcache) - Memcache storage adapter for Keyv\n\n## Add Cache Support to your Module\n\nKeyv 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.\n\nYou should also set a namespace for your module so you can safely call `.clear()` without clearing unrelated app data.\n\nInside your module:\n\n```js\nclass AwesomeModule {\n\tconstructor(opts) {\n\t\tthis.cache = new Keyv({\n\t\t\turi: typeof opts.cache === 'string' && opts.cache,\n\t\t\tstore: typeof opts.cache !== 'string' && opts.cache,\n\t\t\tnamespace: 'awesome-module'\n\t\t});\n\t}\n}\n```\n\nNow it can be consumed like this:\n\n```js\nconst AwesomeModule = require('awesome-module');\n\n// Caches stuff in memory by default\nconst awesomeModule = new AwesomeModule();\n\n// After npm install --save keyv-redis\nconst awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });\n\n// Some third-party module that implements the Map API\nconst awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });\n```\n\n## API\n\n### new Keyv([uri], [options])\n\nReturns a new Keyv instance.\n\nThe Keyv instance is also an `EventEmitter` that will emit an `'error'` event if the storage adapter connection fails.\n\n### uri\n\nType: `String`
\nDefault: `undefined`\n\nThe connection string URI.\n\nMerged into the options object as options.uri.\n\n### options\n\nType: `Object`\n\nThe options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.\n\n#### options.namespace\n\nType: `String`
\nDefault: `'keyv'`\n\nNamespace for the current instance.\n\n#### options.ttl\n\nType: `Number`
\nDefault: `undefined`\n\nDefault TTL. Can be overridden by specififying a TTL on `.set()`.\n\n#### options.serialize\n\nType: `Function`
\nDefault: `JSONB.stringify`\n\nA custom serialization function.\n\n#### options.deserialize\n\nType: `Function`
\nDefault: `JSONB.parse`\n\nA custom deserialization function.\n\n#### options.store\n\nType: `Storage adapter instance`
\nDefault: `new Map()`\n\nThe storage adapter instance to be used by Keyv.\n\n#### options.adapter\n\nType: `String`
\nDefault: `undefined`\n\nSpecify an adapter to use. e.g `'redis'` or `'mongodb'`.\n\n### Instance\n\nKeys must always be strings. Values can be of any type.\n\n#### .set(key, value, [ttl])\n\nSet a value.\n\nBy default keys are persistent. You can set an expiry TTL in milliseconds.\n\nReturns a promise which resolves to `true`.\n\n#### .get(key, [options])\n\nReturns a promise which resolves to the retrieved value.\n\n##### options.raw\n\nType: `Boolean`
\nDefault: `false`\n\nIf set to true the raw DB object Keyv stores internally will be returned instead of just the value.\n\nThis contains the TTL timestamp.\n\n#### .delete(key)\n\nDeletes an entry.\n\nReturns a promise which resolves to `true` if the key existed, `false` if not.\n\n#### .clear()\n\nDelete all entries in the current namespace.\n\nReturns a promise which is resolved when the entries have been cleared.\n\n## License\n\nMIT © Luke Childs\n","readmeFilename":"README.md"}