Discord Virtual State (DVS)

DVS is a high-performance, hybrid caching library designed for Discord.js. It sits between your bot and your data, implementing a "Virtual State" architecture that allows you to handle massive amounts of data (Users, Guilds, Members) without exhausting your server's RAM.

Features 🚀

• Hybrid L1/L2 Caching: Automatically manages hot data in RAM (L1) and cold data in Redis (L2).
• Drop-in Collection Replacement: Extends Discord.js Collection, preserving the API and compatible with makeCache.
• Smart LRU Eviction: Automatically moves unused data to L2 storage to free up memory.
• Transparent Hydration: Seamlessly converts raw data from Redis back into fully functional Discord.js structures.
• Fail-safe: If Redis goes down, it degrades gracefully to a standard in-memory cache.

Installation

npm install discord-virtual-state ioredis

Quick Start

The best way to use DVS is via the makeCache option in Discord.js Client.

1. Setup

const { Client, GatewayIntentBits } = require('discord.js');
const { DVSStorage, RedisAdapter } = require('discord-virtual-state');

// 1. Create the Adapter (L2 Storage)
const adapter = new RedisAdapter({
    url: 'redis://localhost:6379',
    namespace: 'mybot:'
});

// 2. Create the Client with Custom Cache
// Note: Pass 'Collection' to ensure compatibility if you have dependency issues
const { Collection } = require('discord.js');

const client = new Client({
    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers],
    // DVSStorage.builder creates a factory for all managers
    makeCache: DVSStorage.builder({
        adapter: adapter,
        Collection: Collection, // Pass the Collection class to avoid type warnings
        maxSize: 100, // Keep only 100 items per manager in RAM
        limits: {
            // Customize limits per Manager type
            GuildMemberManager: 50,
            MessageManager: 10
        }
    })
});

client.login('YOUR_TOKEN');

2. Usage (Virtual State)

DVS manages memory automatically. When you access data:

// 1. Sync Access (L1 - RAM)
// Fast, but might return undefined if the item was evicted to Redis
const member = guild.members.cache.get('memberID');

// 2. Async Access (L2 - Redis)
// If not in RAM, use restore() to fetch from Redis and hydrate it
if (!member) {
    const restoredMember = await guild.members.cache.restore('memberID');
    if (restoredMember) {
        console.log(`Found member: ${restoredMember.displayName}`);
    }
}

How It Works 🛠️

1. Write: Updates depend on Discord.js internal events. When DVS caches an item, it writes to RAM and asynchronously to Redis.
2. Eviction: When maxSize is reached, DVS evicts the least recently used (LRU) items from RAM. They stay safe in Redis.
3. Restoration: restore() fetches data from Redis and re-binds it to the Client, making it usable again.

API Reference

DVSStorage.builder(options)

Creates a factory function compatible with clientOptions.makeCache.

• options.adapter: The L2 storage adapter instance.
• options.maxSize: Global limit for items in RAM (default: Infinity).
• options.limits: Object mapping Manager names (e.g., 'GuildMemberManager') to specific RAM limits.

new RedisAdapter(options)

• options.url: Redis connection string.
• options.client: Existing ioredis instance.
• options.namespace: Key prefix (default: 'dvs:').

DVSManager.restore(key)

Method on the cache instance.

• Attempts to fetch the key from L2 storage and hydrate it. Returns Promise<Value | undefined>.

Created for the DVS Project.