Repository files navigation

Keyv is a simple key-value storage with support for multiple backend adapters (MySQL, PostgreSQL, SQLite, Redis, Mongo, DynamoDB, Firestore, Memcached, and more).

Forked fromkeyv, plus:

• It isn't bloated.
• It supports namespaces.
• It supports TTL based expiry.
• It has a simple Promise based API.
• It handles all JSON types plusBuffer.
• It's support avary of storages adapters.
• It can beeasily embed inside another module.
• It works with any storage that implements theMap API.
• it handles database errors (db failures won't kill your app).
• It supports the current active LTS version of Node.js or higher.
• It's suitable as a TTL based cache or persistent key-value store.

npm install @keyvhq/core --save

You can optionally install the storage adapter you want to use:

npm install @keyvhq/redis --savenpm install @keyvhq/mongo --savenpm install @keyvhq/sqlite --savenpm install @keyvhq/postgres --savenpm install @keyvhq/mysql --save

If you don't provide a specific storage adapter, a in-memory storage adapter is used by default.

Just create a newKeyv instance, using an specific storage adapter:

constkeyv=newKeyv()// in-memory, by defaultconstkeyvRedis=newKeyv({store:newKeyvRedis('redis://user:pass@localhost:6379')})constkeyvMongo=newKeyv({store:newKeyvMongo('mongodb://user:pass@localhost:27017/dbname')})constkeyvSQLite=newKeyv({store:newKeyvSQLite('sqlite://path/to/database.sqlite')})constkeyvPostgreSQL=newKeyv({store:newKeyvPostgreSQL('postgresql://user:pass@localhost:5432/dbname')})constkeyvMySQL=newKeyv({store:newKeyvMySQL('mysql://user:pass@localhost:3306/dbname')})awaitkeyv.set('foo','expires in 1 second',1000)// trueawaitkeyv.set('foo','never expires')// trueawaitkeyv.get('foo')// 'never expires'awaitkeyv.has('foo')// trueawaitkeyv.delete('foo')// trueawaitkeyv.has('foo')// falseawaitkeyv.clear()// undefined

You can namespace yourKeyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.

constusers=newKeyv({store:newKeyvRedis('redis://user:pass@localhost:6379'),namespace:'users'})constcache=newKeyv({store:newKeyvRedis('redis://user:pass@localhost:6379'),namespace:'cache'})awaitusers.set('foo','users')// trueawaitcache.set('foo','cache')// trueawaitusers.get('foo')// 'users'awaitcache.get('foo')// 'cache'awaitusers.clear()// undefinedawaitusers.get('foo')// undefinedawaitcache.get('foo')// 'cache'

Keyv usesjson-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.

The following example is using@keyvhq/compress as serializer:

constKeyvCompress=require('@keyvhq/compress')constKeyv=require('@keyvhq/core')constkeyv=KeyvCompress(newKeyv({serialize:v8.serialize,deserialize:v8.deserialize}))

Keyv is designed to be easily embedded into other modules to add cache support.

Caching will work in memory by default and users have the option to also install aKeyv storage adapter and pass in a connection string, or any other storage that implements theMap API.

constKeyvRedis=require('@keyvhq/redis')constKeyv=require('@keyvhq/core')constgot=require('got')constcache=newKeyv({store:newKeyvRedis('redis://user:pass@localhost:6379')})awaitgot('https://keyvhq.js.org',{ cache})

The recommended pattern is to expose acache option in your modules options which is passed through toKeyv.

For example,quick-lru is a completely unrelated module that implements theMap API.

constKeyv=require('@keyvhq/core')constQuickLRU=require('quick-lru')constlru=newQuickLRU({maxSize:1000})constkeyv=newKeyv({store:lru})

You should also set anamespace for your module so you can safely call.clear() without clearing unrelated app data.

The official storage adapters are covered byover 150 integration tests to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.

• @keyvhq/file – File storage adapter for Keyv.
• @keyvhq/mongo – MongoDB storage adapter for Keyv.
• @keyvhq/mysql – MySQL/MariaDB storage adapter for Keyv.
• @keyvhq/postgres – PostgreSQL storage adapter for Keyv.
• @keyvhq/redis – Redis storage adapter for Keyv.
• @keyvhq/sqlite – SQLite storage adapter for Keyv.

• @keyvhq/compress – Adds compression bindings for your Keyv instance.
• @keyvhq/memoize – Memoize any function using Keyv as storage backend.
• @keyvhq/multi – Manages local and remote keyv stores as one.
• @keyvhq/offline – Adds offline capabilities for your keyv instance.
• @keyvhq/stats – Collects metrics for a Keyv instance over time.

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.

• keyv-anyredis - Support for Redis clusters and alternative Redis clients.
• keyv-dynamodb - DynamoDB storage adapter for Keyv.
• keyv-file - File system storage adapter for Keyv.
• keyv-firestore – Firebase Cloud Firestore adapter for Keyv.
• keyv-lru – An in-memory LRU back-end for Keyv.
• keyv-memcache - Memcache storage adapter for Keyv.
• keyv-mssql - Microsoft SQL Server adapter for Keyv.
• keyv-s3 - Amazon S3 storage adapter for Keyv.
• quick-lru - Simple "Least Recently Used" (LRU) cache.

Returns a new Keyv instance.

Type:Object

The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.

Type:String
Default:undefined

Namespace for the current instance.

Type:Number
Default:undefined

Default TTL in milliseconds. Can be overridden by specifying a TTL on.set().

Type:Function
Default:JSONB.stringify

A custom serialization function.

Type:Function
Default:JSONB.parse

A custom deserialization function.

Type:Storage adapter instance
Default:new Map()

The storage adapter instance to be used by Keyv.

Type:Boolean
Default:false

If set to true the raw DB object Keyv stores internally will be returned instead of just the value.

This contains the TTL timestamp.

Set a value.

By default keys are persistent. You can set an expiry TTL in milliseconds.

Returns a promise which resolves totrue.

Returns a promise which resolves to the retrieved value.

Returns a promise which resolves to a boolean, indicating existence of a key.

Deletes an entry.

Returns a promise which resolves totrue if the key existed,false if not.

Delete all entries in the current namespace.

Returns a promise which is resolved when the entries have been cleared.

When calling clear(), on a keyv instance with no namespace, all keys are cleared.

Returns anasync iterator, which iterates over all the key-value pairs in the namespace. When called without a namespace, it iterates overall entries in the database.

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.

keyv ©Luke Childs, released under theMIT License.
Maintained byMicrolink with help fromcontributors.

microlink.io · GitHubmicrolinkhq · X@microlinkhq