Valkeyrie - Key-Value Store

---

Valkeyrie is a high-performance key-value store for Node.js applications that solves the problem of efficient data storage and retrieval in JavaScript environments. It brings the powerful Deno.kv API to Node.js, enabling developers to store complex data structures with atomic guarantees without the complexity of setting up external databases. Whether you need a lightweight database for your application, a caching layer, or a way to persist application state, Valkeyrie provides a simple yet powerful solution built on SQLite.

This is a work in progress, but the API and everything already implemented is stable and ready for production.

Table of Contents

• Features
• Installation
• Building from Source
• Quick Start
• Key Concepts
  • Hierarchical Keys
  • Value Types
  • Atomic Operations
  • Serializers
• Documentation
• Contributing
• Benchmarks
• License

Features

• Simple and intuitive API - Easy to learn and use
• Rich data type support - Store and retrieve complex data structures
• Hierarchical keys - Organize data with multi-part keys
• Atomic operations - Perform multiple operations in a single transaction
• Efficient querying - List data with prefix and range queries
• Data expiration - Set time-to-live for values
• High performance - Built on SQLite with optimized operations
• Specialized numeric type - 64-bit unsigned integers for counters

Installation

# Using pnpm
pnpm add valkeyrie

# Using npm
npm install valkeyrie

# Using yarn
yarn add valkeyrie

Quick Start

import { Valkeyrie, KvU64 } from 'valkeyrie';

// Open a database
const db = await Valkeyrie.open();

// Store values
await db.set(['users', 'user1'], { name: 'John Doe', age: 30 });
await db.set(['counters', 'visitors'], new KvU64(1000n));

// Retrieve values
const user = await db.get(['users', 'user1']);
console.log(user.value); // { name: 'John Doe', age: 30 }

// List values with a common prefix
for await (const entry of db.list({ prefix: ['users'] })) {
  console.log(entry.key, entry.value);
}

// Perform atomic operations
await db.atomic()
  .check({ key: ['users', 'user1'], versionstamp: user.versionstamp })
  .set(['users', 'user1'], { ...user.value, lastLogin: new Date() })
  .sum(['counters', 'visitors'], 1n)
  .commit();

// Database management
// Clear all data but keep the database file
await db.clear();
// Or completely destroy the database (deletes the file)
// await db.destroy();

// Close the database when done
await db.close();

Key Concepts

Hierarchical Keys

Keys in Valkeyrie are arrays of parts, allowing for hierarchical organization:

// User data
await db.set(['users', 'user1', 'profile'], { ... });
await db.set(['users', 'user1', 'settings'], { ... });

Value Types

Valkeyrie supports a wide range of value types:

• Primitive types: string, number, boolean, bigint, null, undefined
• Binary data: Uint8Array, ArrayBuffer
• Complex types: objects, arrays, Map, Set
• Date objects, RegExp objects
• KvU64 (specialized 64-bit unsigned integer)

Important Note: KvU64 instances can only be used as top-level values, not nested within objects or arrays.

Atomic Operations

Perform multiple operations atomically with optimistic concurrency control:

await db.atomic()
  .set(['users', 'user1'], { name: 'John' })
  .set(['users', 'user2'], { name: 'Jane' })
  .delete(['users', 'user3'])
  .commit();

Serializers

Valkeyrie supports pluggable serializers that allow you to customize how values are stored in the database:

• V8 Serializer (Default) - Uses Node.js's built-in node:v8 module for efficient binary serialization
• JSON Serializer - Human-readable format compatible with other programming languages
• BSON Serializer - Uses MongoDB's BSON format for efficient binary serialization
• MessagePack Serializer - Uses the msgpackr library for compact binary serialization
• CBOR-X Serializer - Uses the cbor-x library for high-performance CBOR serialization
• Custom Serializers - Create your own serializers for specialized needs like compression or encryption

import { Valkeyrie } from 'valkeyrie';
import { bsonSerializer } from 'valkeyrie/serializers/bson';
import { cborXSerializer } from 'valkeyrie/serializers/cbor-x';

// Using the BSON serializer
const dbBson = await Valkeyrie.open('./data.db', {
  serializer: bsonSerializer
});

// Using the CBOR-X serializer
const dbCbor = await Valkeyrie.open('./cbor-data.db', {
  serializer: cborXSerializer
});

For detailed information about serializers, see the Serializers section in the documentation.

Documentation

For complete documentation, see Documentation.

Contributing

For detailed information on how to contribute to this project, please see our Contributing Guide.

Benchmarks

Valkeyrie includes a comprehensive benchmarking suite to measure performance:

# Run all benchmarks
pnpm benchmark

# Run specific benchmark suites
pnpm benchmark:basic    # Basic operations
pnpm benchmark:list     # List operations
pnpm benchmark:atomic   # Atomic operations

License

Valkeyrie is licensed under the MIT License. See the License file for details.