{"id":13515648,"url":"https://github.com/microlinkhq/keyvhq","last_synced_at":"2026-02-04T21:05:11.934Z","repository":{"id":37402814,"uuid":"358557475","full_name":"microlinkhq/keyvhq","owner":"microlinkhq","description":"Simple key-value storage with support for multiple backends.","archived":false,"fork":false,"pushed_at":"2026-01-11T08:18:59.000Z","size":1761,"stargazers_count":445,"open_issues_count":0,"forks_count":20,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-01-11T14:21:50.640Z","etag":null,"topics":["cache","caching","key-value","localstorage","map","redis","storage","store"],"latest_commit_sha":null,"homepage":"https://keyvhq.js.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microlinkhq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-04-16T10:10:54.000Z","updated_at":"2026-01-11T08:19:03.000Z","dependencies_parsed_at":"2023-02-16T05:31:14.417Z","dependency_job_id":"9b72bb78-8b9a-4ae4-ab2f-7ca6451e84af","html_url":"https://github.com/microlinkhq/keyvhq","commit_stats":{"total_commits":1178,"total_committers":36,"mean_commits":32.72222222222222,"dds":0.4915110356536503,"last_synced_commit":"815b5de980d57373495cbc23f8dcfcce11658869"},"previous_names":["microlinkhq/keyv"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/microlinkhq/keyvhq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microlinkhq%2Fkeyvhq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microlinkhq%2Fkeyvhq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microlinkhq%2Fkeyvhq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microlinkhq%2Fkeyvhq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microlinkhq","download_url":"https://codeload.github.com/microlinkhq/keyvhq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microlinkhq%2Fkeyvhq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28865214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T05:56:06.453Z","status":"ssl_error","status_checked_at":"2026-01-29T05:55:57.668Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","caching","key-value","localstorage","map","redis","storage","store"],"created_at":"2024-08-01T05:01:14.145Z","updated_at":"2026-01-29T06:03:15.724Z","avatar_url":"https://github.com/microlinkhq.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\t\u003cimg width=\"250\" src=\"/media/logo-sunset.svg\" alt=\"keyv logo\"\u003e\n\t\u003cbr/\u003e\n\t\u003cbr/\u003e\n\u003c/h1\u003e\n\n![Last version](https://img.shields.io/github/tag/keyvhq/keyv.svg?style=flat-square)\n[![Coverage Status](https://img.shields.io/coveralls/keyvhq/keyv.svg?style=flat-square)](https://coveralls.io/github/keyvhq/keyv)\n[![NPM Status](https://img.shields.io/npm/dm/@keyvhq/core.svg?style=flat-square)](https://www.npmjs.org/package/@keyvhq/core)\n\n\u003e **Keyv** is a simple key-value storage with support for multiple backend adapters (MySQL, PostgreSQL, SQLite, Redis, Mongo, DynamoDB, Firestore, Memcached, and more).\n\n## Features\n\nForked from [keyv](https://github.com/lukechilds/keyv), plus:\n\n- It isn't bloated.\n- It supports namespaces.\n- It supports TTL based expiry.\n- It has a simple Promise based API.\n- It handles all JSON types plus `Buffer`.\n- It's support a [vary of storages](#official-storage-adapters) adapters.\n- It can be [easily embed](#add-cache-support-to-your-module) inside another module.\n- It works with any storage that implements the [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API.\n- it handles database errors (db failures won't kill your app).\n- It supports the current active LTS version of Node.js or higher.\n- It's suitable as a TTL based cache or persistent key-value store.\n\n## Installation\n\n```bash\nnpm install @keyvhq/core --save \n```\n\nYou can optionally install the storage adapter you want to use:\n\n```bash\nnpm install @keyvhq/redis --save\nnpm install @keyvhq/mongo --save\nnpm install @keyvhq/sqlite --save\nnpm install @keyvhq/postgres --save\nnpm install @keyvhq/mysql --save\n```\n\nIf you don't provide a specific storage adapter, a in-memory storage adapter is used by default.\n\n## Usage\n\nJust create a new **Keyv** instance, using an specific storage adapter:\n\n```js\nconst keyv = new Keyv() // in-memory, by default\nconst keyvRedis = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379')})\nconst keyvMongo = new Keyv({ store: new KeyvMongo('mongodb://user:pass@localhost:27017/dbname')})\nconst keyvSQLite = new Keyv({ store: new KeyvSQLite('sqlite://path/to/database.sqlite')})\nconst keyvPostgreSQL = new Keyv({ store: new KeyvPostgreSQL('postgresql://user:pass@localhost:5432/dbname')})\nconst keyvMySQL = new Keyv({ store: new KeyvMySQL('mysql://user:pass@localhost:3306/dbname')})\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.has('foo') // true\nawait keyv.delete('foo') // true\nawait keyv.has('foo') // false\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({ store: new KeyvRedis('redis://user:pass@localhost:6379'), namespace: 'users' })\nconst cache = new Keyv({ store: new KeyvRedis('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### Serialization\n\n**Keyv** 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\nThe following example is using [@keyvhq/compress](https://github.com/microlinkhq/keyvhq/tree/master/packages/compress) as serializer:\n\n```js\nconst KeyvCompress = require('@keyvhq/compress')\nconst Keyv = require('@keyvhq/core')\n\nconst keyv = KeyvCompress(\n  new Keyv({\n    serialize: v8.serialize,\n    deserialize: v8.deserialize\n  })\n)\n```\n\n## Storage adapters\n\n**Keyv** is designed to be easily embedded into other modules to add cache support. \n\nCaching 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API.\n\n```js\nconst KeyvRedis = require('@keyvhq/redis')\nconst Keyv = require('@keyvhq/core')\nconst got = require('got')\n\nconst cache = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379') })\n\nawait got('https://keyvhq.js.org', { cache })\n```\n\nThe recommended pattern is to expose a `cache` option in your modules options which is passed through to **Keyv**.\n\nFor example, [quick-lru](https://github.com/sindresorhus/quick-lru) is a completely unrelated module that implements the [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API.\n\n```js\nconst Keyv = require('@keyvhq/core')\nconst QuickLRU = require('quick-lru')\n\nconst lru = new QuickLRU({ maxSize: 1000 })\nconst keyv = new Keyv({ store: lru })\n```\n\nYou should also set a [`namespace`](#optionsnamespace) for your module so you can safely call [`.clear()`](#clear) without clearing unrelated app data.\n\n### All the adapters\n\n\u003e The official storage adapters are covered by [over 150 integration tests](https://github.com/microlinkhq/keyvhq/actions/runs/949262324) to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.\n\n- [@keyvhq/file](https://github.com/microlinkhq/keyvhq/tree/master/packages/file) – File storage adapter for Keyv.\n- [@keyvhq/mongo](https://github.com/microlinkhq/keyvhq/tree/master/packages/mongo) – MongoDB storage adapter for Keyv.\n- [@keyvhq/mysql](https://github.com/microlinkhq/keyvhq/tree/master/packages/mysql) – MySQL/MariaDB storage adapter for Keyv.\n- [@keyvhq/postgres](https://github.com/microlinkhq/keyvhq/tree/master/packages/postgres) – PostgreSQL storage adapter for Keyv.\n- [@keyvhq/redis](https://github.com/microlinkhq/keyvhq/tree/master/packages/redis) – Redis storage adapter for Keyv.\n- [@keyvhq/sqlite](https://github.com/microlinkhq/keyvhq/tree/master/packages/sqlite) – SQLite storage adapter for Keyv.\n\n### Decorators\n\n- [@keyvhq/compress](https://github.com/microlinkhq/keyvhq/tree/master/packages/compress) – Adds compression bindings for your Keyv instance.\n- [@keyvhq/memoize](https://github.com/microlinkhq/keyvhq/tree/master/packages/memoize) – Memoize any function using Keyv as storage backend.\n- [@keyvhq/multi](https://github.com/microlinkhq/keyvhq/tree/master/packages/multi) – Manages local and remote keyv stores as one.\n- [@keyvhq/offline](https://github.com/microlinkhq/keyvhq/tree/master/packages/offline) – Adds offline capabilities for your keyv instance.\n- [@keyvhq/stats](https://github.com/microlinkhq/keyvhq/tree/master/packages/stats) – Collects metrics for a Keyv instance over time.\n\n### Community\n\n\u003e 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.\n\n- [keyv-anyredis](https://github.com/natesilva/keyv-anyredis) - Support for Redis clusters and alternative Redis clients.\n- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv.\n- [keyv-file](https://github.com/zaaack/keyv-file) - File system storage adapter for Keyv.\n- [keyv-firestore ](https://github.com/goto-bus-stop/keyv-firestore) – Firebase Cloud Firestore adapter for Keyv.\n- [keyv-lru](https://github.com/e0ipso/keyv-lru) – An in-memory LRU back-end for Keyv.\n- [keyv-memcache](https://github.com/jaredwray/keyv-memcache) - Memcache storage adapter for Keyv.\n- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft SQL Server adapter for Keyv.\n- [keyv-s3](https://github.com/microlinkhq/keyv-s3) - Amazon S3 storage adapter for Keyv.\n- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple \"Least Recently Used\" (LRU) cache.\n\n\n## API\n\n### constructor([options])\n\nReturns a new Keyv instance.\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##### namespace\n\nType: `String`\u003cbr/\u003e\nDefault: `undefined`\n\nNamespace for the current instance.\n\n##### ttl\n\nType: `Number`\u003cbr/\u003e\nDefault: `undefined`\n\nDefault TTL in milliseconds. Can be overridden by specifying a TTL on `.set()`.\n\n##### serialize\n\nType: `Function`\u003cbr/\u003e\nDefault: `JSONB.stringify`\n\nA custom serialization function.\n\n##### deserialize\n\nType: `Function`\u003cbr/\u003e\nDefault: `JSONB.parse`\n\nA custom deserialization function.\n\n##### store\n\nType: `Storage adapter instance`\u003cbr/\u003e\nDefault: `new Map()`\n\nThe storage adapter instance to be used by Keyv.\n\n##### raw\n\nType: `Boolean`\u003cbr/\u003e\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### .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### .has(key)\n\nReturns a promise which resolves to a boolean, indicating existence of a key.\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\nWhen calling clear(), on a keyv instance with no namespace, all keys are cleared.\n\n#### .iterator()\n\nReturns an [async iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator), which iterates over all the key-value pairs in the namespace. When called without a namespace, it iterates over *all* entries in the database.\n\n\u003e The iterator shouldn't be used in environments where performance is key, or there are more than 1000 entries in the database, use an ORM or a native driver if you need to iterate over all entries.\n\n## License\n\n**keyv** © [Luke Childs](https://lukechilds.co), released under the [MIT](https://github.com/microlinkhq/keyvhq/blob/master/LICENSE.md) License.\u003cbr/\u003e\nMaintained by [Microlink](https://microlink.io) with help from [contributors](https://github.com/microlinkhq/keyvhq/contributors).\n\n\u003e [microlink.io](https://microlink.io) · GitHub [microlinkhq](https://github.com/microlinkhq) · X [@microlinkhq](https://x.com/microlinkhq)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrolinkhq%2Fkeyvhq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrolinkhq%2Fkeyvhq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrolinkhq%2Fkeyvhq/lists"}