• Stars
    star
    422
  • Rank 102,753 (Top 3 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 3 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Simple key-value storage with support for multiple backends.

keyv logo

Last version Coverage Status NPM Status

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

Features

Forked from keyv, 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 plus Buffer.
  • It's support a vary of storages adapters.
  • It can be easily embed inside another module.
  • It works with any storage that implements the Map 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.

Installation

npm install @keyvhq/core --save 

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

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

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

Usage

Just create a new Keyv instance, using an specific storage adapter:

const keyv = new Keyv() // in-memory, by default
const keyvRedis = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379')})
const keyvMongo = new Keyv({ store: new KeyvMongo('mongodb://user:pass@localhost:27017/dbname')})
const keyvSQLite = new Keyv({ store: new KeyvSQLite('sqlite://path/to/database.sqlite')})
const keyvPostgreSQL = new Keyv({ store: new KeyvPostgreSQL('postgresql://user:pass@localhost:5432/dbname')})
const keyvMySQL = new Keyv({ store: new KeyvMySQL('mysql://user:pass@localhost:3306/dbname')})

await keyv.set('foo', 'expires in 1 second', 1000) // true
await keyv.set('foo', 'never expires') // true
await keyv.get('foo') // 'never expires'
await keyv.has('foo') // true
await keyv.delete('foo') // true
await keyv.has('foo') // false
await keyv.clear() // undefined

Namespaces

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

const users = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379'), namespace: 'users' })
const cache = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379'), namespace: 'cache' })

await users.set('foo', 'users') // true
await cache.set('foo', 'cache') // true
await users.get('foo') // 'users'
await cache.get('foo') // 'cache'
await users.clear() // undefined
await users.get('foo') // undefined
await cache.get('foo') // 'cache'

Serialization

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

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

const KeyvCompress = require('@keyvhq/compress')
const Keyv = require('@keyvhq/core')

const keyv = KeyvCompress(
  new Keyv({
    serialize: v8.serialize,
    deserialize: v8.deserialize
  })
)

Storage adapters

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 a Keyv storage adapter and pass in a connection string, or any other storage that implements the Map API.

const KeyvRedis = require('@keyvhq/redis')
const Keyv = require('@keyvhq/core')
const got = require('got')

const cache = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379') })

await got('https://keyv.js.org', { cache })

The recommended pattern is to expose a cache option in your modules options which is passed through to Keyv.

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

const Keyv = require('@keyvhq/core')
const QuickLRU = require('quick-lru')

const lru = new QuickLRU({ maxSize: 1000 })
const keyv = new Keyv({ store: lru })

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

All the adapters

The official storage adapters are covered by over 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.

Decorators

Community

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.

API

constructor([options])

Returns a new Keyv instance.

options

Type: Object

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

namespace

Type: String
Default: undefined

Namespace for the current instance.

ttl

Type: Number
Default: undefined

Default TTL. Can be overridden by specififying a TTL on .set().

serialize

Type: Function
Default: JSONB.stringify

A custom serialization function.

deserialize

Type: Function
Default: JSONB.parse

A custom deserialization function.

store

Type: Storage adapter instance
Default: new Map()

The storage adapter instance to be used by Keyv.

raw

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(key, value, [ttl])

Set a value.

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

Returns a promise which resolves to true.

.get(key, [options])

Returns a promise which resolves to the retrieved value.

.has(key)

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

.delete(key)

Deletes an entry.

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

.clear()

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.

.iterator()

Returns an async iterator, which iterates over all the key-value pairs in the namespace. When called without a namespace, it iterates over all 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.

License

keyv Β© Luke Childs, released under the MIT License.
Maintained by Microlink with help from contributors.

microlink.io Β· GitHub microlinkhq Β· Twitter @microlinkhq

More Repositories

1

metascraper

Get unified metadata from websites using Open Graph, Microdata, RDFa, Twitter Cards, JSON-LD, HTML, and more.
HTML
2,300
star
2

browserless

browserless is an efficient way to interact with a headless browser built in top of Puppeteer.
JavaScript
1,393
star
3

unavatar

Get unified user avatar from social networks, including Instagram, SoundCloud, Telegram, Twitter, YouTube & more.
JavaScript
946
star
4

sdk

Make any URL embeddable. Turn any URL into a beautiful link preview.
HTML
583
star
5

cards

The easiest way to create and share dynamic images at scale.
JavaScript
389
star
6

youtube-dl-exec

A simple Node.js wrapper for youtube-dl/yt-dlp.
JavaScript
316
star
7

async-ratelimiter

Rate limit made simple, easy, async.
JavaScript
298
star
8

react-json-view

JSON viewer for React
JavaScript
188
star
9

www

Browser as API
JavaScript
120
star
10

splashy

Given an whatever image (GIF, PNG, WebP, AVIF, etc) extract predominant & palette colors.
JavaScript
88
star
11

spotify-url-info

Get metadata from any Spotify URL.
JavaScript
68
star
12

html-get

Get the HTML from any website, using prerendering when necessary.
JavaScript
65
star
13

mql

Microlink Query Language. The official HTTP client to interact with Microlink API for Node.js, browsers & Deno.
JavaScript
47
star
14

nanoclamp

πŸ—œResponsive clamping component for React in 735 bytes.
JavaScript
41
star
15

metatags

Ensure your HTML is previewed beautifully across social networks.
JavaScript
29
star
16

async-memoize-one

memoize the last result, in async way.
JavaScript
21
star
17

recipes

JavaScript
15
star
18

oembed-spec

A parser for oEmbed specification.
JavaScript
14
star
19

function

JavaScript Serverless functions with browser programmatic access.
JavaScript
11
star
20

server-proxy

Interact with Microlink API without exposing your credentials
JavaScript
9
star
21

queue

The high resilient queue for processing URLs.
JavaScript
9
star
22

keyv-s3

Amazon S3 storage adapter for Keyv.
JavaScript
8
star
23

openkey

Fast authentication layer for your SaaS, backed by Redis.
JavaScript
7
star
24

cdn

Content Delivery Network for Microlink assets
JavaScript
6
star
25

analytics

Microservice to retrieve your CloudFlare Analytics.
JavaScript
6
star
26

keyv-redis

Redis storage adapter for Keyv.
JavaScript
6
star
27

ping-url

Fast DNS resolution caching results for a while.
JavaScript
6
star
28

lighthouse-viewer

Lighthouse Viewer as service
JavaScript
6
star
29

cli

A CLI for interacting with Microlink API
JavaScript
5
star
30

geolocation

Get detailed information about the incoming request based on the IP address.
JavaScript
5
star
31

oss

Microservice to get the latest public GitHub repos from a user/organization
JavaScript
4
star
32

local

Runs Microlink Function locally.
JavaScript
4
star
33

html

Get HTML from any URL.
JavaScript
3
star
34

youtube-dl-binary

Tiny tool for downloading the latest `youtube-dl` version available.
JavaScript
3
star
35

open

3
star
36

mql-cli

CLI for interacting with Microlink Query Language.
JavaScript
2
star
37

healthcheck

Microservice to retrieve your CloudFlare Health Checks.
JavaScript
2
star
38

demo-links

A set of links used for demo purposes
2
star
39

meta

Open Graph Image as Service
TypeScript
2
star
40

proxy

Interact with Microlink API using an Edge Function.
JavaScript
2
star
41

logo

Adding logos to any website, powered by Microlink API.
JavaScript
2
star
42

microclap

clap button as service
JavaScript
1
star