tessl/npm-keyv

Simple key-value storage with support for multiple backends

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Keyv

Name: tessl/npm-keyv
Author: tessl

Keyv is a simple key-value storage library that provides a consistent interface for key-value storage across multiple backends via storage adapters. It supports TTL-based expiry, making it suitable as both a cache and persistent key-value store, with built-in event handling, hooks system, and comprehensive type safety.

Package Information

Package Name: keyv
Package Type: npm
Language: TypeScript
Installation: npm install keyv

Core Imports

import Keyv from "keyv";
import { KeyvHooks, type KeyvOptions, type KeyvStoreAdapter } from "keyv";

For CommonJS:

const Keyv = require("keyv");
const { KeyvHooks } = require("keyv");

Basic Usage

import Keyv from "keyv";

// Create instance with in-memory storage
const keyv = new Keyv();

// Basic operations
await keyv.set('user:1', { name: 'Alice', age: 30 }); // true
const user = await keyv.get('user:1'); // { name: 'Alice', age: 30 }
await keyv.delete('user:1'); // true

// TTL support (expires in 1 minute)
await keyv.set('temp-data', 'expires soon', 60000);

// Type safety
const keyv_typed = new Keyv<string>();
await keyv_typed.set('message', 'hello world');
const message = await keyv_typed.get('message'); // string | undefined

Architecture

Keyv is built around several key components:

Core Storage Operations: Promise-based get/set/delete with TTL support and batch operations
Storage Adapter System: Pluggable backends (Redis, MongoDB, SQLite, PostgreSQL, MySQL, etc.)
Event System: Built-in EventEmitter for connection errors, clear, and disconnect events
Hook System: Pre/post operation hooks for custom functionality on all CRUD operations
Statistics Tracking: Built-in hit/miss/set/delete operation counters
Compression Support: Optional compression with gzip, brotli, and lz4 adapters
Namespace Support: Key isolation to avoid collisions in shared storage backends

Capabilities

Core Storage Operations

Primary key-value storage functionality including get, set, delete operations with TTL support and batch operations for performance.

class Keyv<GenericValue = any> {
  constructor(options?: KeyvOptions);
  constructor(store?: KeyvStoreAdapter | KeyvOptions | Map<any, any>, options?: Omit<KeyvOptions, 'store'>);
  
  get<Value = GenericValue>(key: string, options?: {raw?: boolean}): Promise<StoredDataNoRaw<Value> | StoredDataRaw<Value>>;
  get<Value = GenericValue>(key: string[], options?: {raw?: boolean}): Promise<Array<StoredDataNoRaw<Value>> | Array<StoredDataRaw<Value>>>;
  set<Value = GenericValue>(key: string, value: Value, ttl?: number): Promise<boolean>;
  delete(key: string | string[]): Promise<boolean>;
  clear(): Promise<void>;
  has(key: string | string[]): Promise<boolean | boolean[]>;
  
  // Iterator for async iteration over entries (when supported by storage adapter)
  iterator?: IteratorFunction;
}

Core Storage Operations

Batch Operations

High-performance batch operations for working with multiple keys simultaneously, with optimizations for storage adapters that support native batch operations.

getMany<Value = GenericValue>(keys: string[], options?: {raw?: boolean}): Promise<Array<StoredDataNoRaw<Value>> | Array<StoredDataRaw<Value>>>;
setMany<Value = GenericValue>(entries: KeyvEntry[]): Promise<boolean[]>;
deleteMany(keys: string[]): Promise<boolean>;
hasMany(keys: string[]): Promise<boolean[]>;

interface KeyvEntry {
  key: string;
  value: any;
  ttl?: number;
}

Batch Operations

Raw Data Access

Direct access to internal data structures including TTL metadata, useful for debugging and advanced use cases where expiry information is needed.

getRaw<Value = GenericValue>(key: string): Promise<StoredDataRaw<Value> | undefined>;
getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<StoredDataRaw<Value>>>;

type DeserializedData<Value> = {
  value?: Value;
  expires?: number | undefined;
};

type StoredDataRaw<Value> = DeserializedData<Value> | undefined;

Raw Data Access

Storage Adapters

Pluggable storage backend system with support for Redis, MongoDB, SQLite, PostgreSQL, MySQL, and any Map-compatible storage.

interface KeyvStoreAdapter {
  opts: any;
  namespace?: string;
  get<Value>(key: string): Promise<StoredData<Value> | undefined>;
  set(key: string, value: any, ttl?: number): any;
  delete(key: string): Promise<boolean>;
  clear(): Promise<void>;
  // Optional methods
  setMany?(values: Array<{key: string; value: any; ttl?: number}>): Promise<void>;
  getMany?<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
  has?(key: string): Promise<boolean>;
  hasMany?(keys: string[]): Promise<boolean[]>;
  deleteMany?(key: string[]): Promise<boolean>;
  disconnect?(): Promise<void>;
  iterator?<Value>(namespace?: string): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
}

Storage Adapters

Events and Hooks

Event system for connection monitoring and lifecycle management, plus hooks system for custom functionality on CRUD operations.

enum KeyvHooks {
  PRE_SET = 'preSet',
  POST_SET = 'postSet',
  PRE_GET = 'preGet',
  POST_GET = 'postGet',
  PRE_GET_MANY = 'preGetMany',
  POST_GET_MANY = 'postGetMany',
  PRE_GET_RAW = 'preGetRaw',
  POST_GET_RAW = 'postGetRaw',
  PRE_GET_MANY_RAW = 'preGetManyRaw',
  POST_GET_MANY_RAW = 'postGetManyRaw',
  PRE_DELETE = 'preDelete',
  POST_DELETE = 'postDelete'
}

Events and Hooks

Configuration and Properties

Configuration options and runtime property management for customizing serialization, compression, namespacing, and error handling behavior.

interface KeyvOptions {
  emitErrors?: boolean;
  namespace?: string;
  serialize?: Serialize;
  deserialize?: Deserialize;
  store?: KeyvStoreAdapter | Map<any, any> | any;
  ttl?: number;
  compression?: CompressionAdapter | any;
  stats?: boolean;
  useKeyPrefix?: boolean;
  throwOnErrors?: boolean;
}

interface CompressionAdapter {
  compress(value: any, options?: any): Promise<any>;
  decompress(value: any, options?: any): Promise<any>;
  serialize<Value>(data: DeserializedData<Value>): Promise<string> | string;
  deserialize<Value>(data: string): Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;
}

Configuration and Properties

Types

type StoredDataNoRaw<Value> = Value | undefined;
type StoredData<Value> = StoredDataNoRaw<Value> | StoredDataRaw<Value>;

type Serialize = <Value>(data: DeserializedData<Value>) => Promise<string> | string;
type Deserialize = <Value>(data: string) => Promise<DeserializedData<Value> | undefined> | DeserializedData<Value> | undefined;

type IteratorFunction = (argument: any) => AsyncGenerator<any, void>;