Welcome to the Valkeyrie documentation! This directory contains comprehensive guides and API references for using Valkeyrie.

Start here if you're new to Valkeyrie:

1. Getting Started Guide
   • Installation and setup
   • Basic operations (set, get, delete, list)
   • Understanding keys and values
   • Common patterns and best practices

Feature-specific guides for different use cases:

• Schema Validation

  • Type-safe operations with Zod, Valibot, and ArkType
  • Automatic TypeScript type inference
  • Pattern matching and validation timing
  • Error handling

• Factory Methods

  • Creating databases from arrays and iterables
  • Streaming data with fromAsync()
  • Progress tracking and error handling
  • Real-world import/migration examples
  • Custom drivers by passing a driver function to open() and the driverFn option

• Serializers

  • Choosing the right serializer
  • V8, JSON, BSON, MessagePack, and CBOR-X
  • Creating custom serializers
  • Migration between serializers

• Advanced Patterns

  • Watch API - Real-time key monitoring
  • Atomic operations
  • Optimistic concurrency control
  • KvU64 numeric operations
  • Multi-instance concurrency
  • Real-world patterns (sessions, caching, events)

Complete technical reference:

• API Reference

  • All methods with parameters and return types
  • Valkeyrie class methods
  • AtomicOperation methods
  • KvU64 class
  • Complete code examples

• TypeScript Types

  • Core types (Key, Entry, Value)
  • Operation types
  • Schema validation types
  • Type inference
  • Best practices for type safety

• Set up a new database → Getting Started
• Add validation → Schema Validation
• Import data → Factory Methods
• Watch for changes → Watch API
• Atomic transactions → Atomic Operations
• Choose a serializer → Serializers Guide

Recent additions to Valkeyrie (check the CHANGELOG for full history):

// Session management
const db = await Valkeyrie.open('./sessions.db');

await db.set(['sessions', sessionId], userData, {
  expireIn: 24 * 60 * 60 * 1000 // 24 hours
});

More →

// Smart cache with TTL
const cache = await Valkeyrie.open('./cache.db');

await cache.set(['api', endpoint], response, {
  expireIn: 5 * 60 * 1000 // 5 minutes
});

More →

// Import from MongoDB
const db = await Valkeyrie.fromAsync(mongoDbCursor, {
  prefix: ['users'],
  keyProperty: (doc) => doc._id.toString()
});

More →

// Watch metrics
const stream = db.watch([
  ['metrics', 'cpu'],
  ['metrics', 'memory']
]);

for await (const [cpu, memory] of stream) {
  updateDashboard({ cpu: cpu.value, memory: memory.value });
}

More →

Valkeyrie's API is heavily inspired by Deno.kv, making migration straightforward:

// Deno.kv
const kv = await Deno.openKv();
await kv.set(['key'], 'value');

// Valkeyrie
const db = await Valkeyrie.open();
await db.set(['key'], 'value');

Main differences:

• File path is first parameter in open()
• Schema validation available via withSchema()
• Pluggable serializers
• Factory methods (from/fromAsync)

Found an issue or want to improve the docs? See CONTRIBUTING.md.

docs/
├── README.md                    # This file
├── guides/                      # Feature guides
│   ├── getting-started.md      # Beginner tutorial
│   ├── schema-validation.md    # Type safety guide
│   ├── factory-methods.md      # Data import guide
│   ├── serializers.md          # Serialization guide
│   └── advanced-patterns.md    # Advanced features
└── api/                         # API reference
    ├── api-reference.md        # Method reference
    └── types.md                # Type definitions

• Questions? Open a GitHub Discussion
• Bug reports? Open a GitHub Issue
• Feature requests? Open a GitHub Issue

Valkeyrie is MIT licensed. See LICENSE for details.