Valkey GLIDE ioredis Adapter

🎯 TRUE DROP-IN REPLACEMENT powered by Valkey GLIDE's high-performance Rust core

Production-Ready Core Features - BullMQ, Socket.IO, Express Sessions, JSON module fully validated

A production-ready ioredis replacement that seamlessly integrates Valkey GLIDE's high-performance Rust core with your existing Node.js applications. Zero code changes required for core functionality - simply change your import statement and gain the benefits of GLIDE's resilient, high-performance architecture while maintaining API compatibility.

🎯 Pure GLIDE Architecture

This project uses exclusively Valkey GLIDE - a high-performance, language-independent Valkey client library with a Rust core and Node.js wrapper.

🏆 Production Readiness Status

Component	Status	Test Coverage	Production Use
Valkey Data Types	✅ Production Ready	String (37), Hash (13), List (16), Set (19), ZSet (14)	Core operations validated
ValkeyJSON Module	✅ Production Ready	29 commands tested	Document storage ready
Bull/BullMQ Integration	✅ Production Ready	10/10 integration tests	Job queues validated
Express Sessions	✅ Production Ready	10/10 session tests	Web apps validated
Socket.IO	✅ Production Ready	7/7 real-time tests	Live apps validated
Connection Management	✅ Production Ready	24 pipeline tests	Enterprise ready
Cluster Support	🔧 Minor Issues	Core functionality works	TypeScript edge cases

Status & Quality Assurance

Library Compatibility

Module Support

✅ What Works Right Now

🎯 Drop-In Replacement for Core Use Cases

• All Valkey Data Types: String, Hash, List, Set, ZSet operations - fully functional
• Bull/BullMQ Job Queues: Complete integration - production ready
• Express Sessions: Session storage with connect-redis - production ready
• Socket.IO Real-time: Cross-instance messaging - production ready
• JSON Document Storage: 29 ValkeyJSON commands - production ready

🔧 Advanced Features (Minor Limitations)

• Cluster Operations: Core functionality works, some TypeScript edge cases
• Complex Lua Scripts: Basic scripts work, some advanced patterns need refinement
• Enhanced ZSET Operations: Some WITHSCORES result formatting edge cases

🚀 Key Technical Features

• Pure GLIDE Architecture: Built exclusively on Valkey GLIDE APIs (no ioredis dependency)
• High Performance: Leverages GLIDE's Rust core for optimal performance
• TypeScript Ready: Full type safety with comprehensive interfaces
• Zero Migration: Change import statement only - your existing code works

📋 Bull/BullMQ Integration

Complete compatibility with job queue libraries - no code changes required:

import { Redis } from 'valkey-glide-ioredis-adapter';
import Bull from 'bull';

// BullMQ compatibility with createClient factory
const redis = Redis.createClient('client', { host: 'localhost', port: 6379 });

// Works with Bull directly
const queue = new Bull('email', { 
  redis: { host: 'localhost', port: 6379 } 
});

// Custom Lua scripts work via defineCommand
redis.defineCommand('customLua', {
  lua: 'return redis.call("set", KEYS[1], ARGV[1])',
  numberOfKeys: 1
});

// Blocking operations for job processing
const job = await redis.brpop('job:queue', 10);

🔧 Installation

npm install valkey-glide-ioredis-adapter

Requirements:

• Node.js 18+ (ES2022 support)
• Valkey 6.0+ or Redis 6.0+ server
• TypeScript 4.5+ (for TypeScript projects)

📖 Basic Usage

import { Redis } from 'valkey-glide-ioredis-adapter';

// Create Redis client (ioredis-compatible)
const redis = new Redis({
  host: 'localhost',
  port: 6379
});

// Use ioredis API with Valkey GLIDE backend
await redis.set('key', 'value');
const value = await redis.get('key');

// ZSET operations with proper result translation
const members = await redis.zrange('myset', 0, -1, 'WITHSCORES');

// Stream operations using native GLIDE methods
await redis.xadd('mystream', '*', 'field', 'value');
const messages = await redis.xread('STREAMS', 'mystream', '0');

// Works with all ioredis constructors
const redis1 = new Redis(6379);                    // port only
const redis2 = new Redis(6379, 'localhost');       // port, host
const redis3 = new Redis('redis://localhost:6379'); // URL

📄 JSON Module Support (ValkeyJSON)

Store and query JSON documents natively with full RedisJSON v2 compatibility:

import { Redis } from 'valkey-glide-ioredis-adapter';

const redis = new Redis({ host: 'localhost', port: 6379 });

// Store JSON documents
await redis.jsonSet('user:123', '$', {
  name: 'John Doe',
  age: 30,
  address: {
    city: 'San Francisco',
    country: 'USA'
  },
  hobbies: ['programming', 'gaming']
});

// Query with JSONPath
const name = await redis.jsonGet('user:123', '$.name');
const city = await redis.jsonGet('user:123', '$.address.city');

// Update specific paths
await redis.jsonNumIncrBy('user:123', '$.age', 1);
await redis.jsonArrAppend('user:123', '$.hobbies', 'reading');

// Array operations
const hobbyCount = await redis.jsonArrLen('user:123', '$.hobbies');
const removedHobby = await redis.jsonArrPop('user:123', '$.hobbies', 0);

29 JSON Commands Available: Complete ValkeyJSON/RedisJSON v2 compatibility with jsonSet, jsonGet, jsonDel, jsonType, jsonNumIncrBy, jsonArrAppend, jsonObjKeys, jsonToggle, and more!

🧪 Testing JSON Module

Use valkey-bundle for testing JSON functionality:

# Start valkey-bundle with JSON module
docker-compose -f docker-compose.valkey-bundle.yml up -d

# Test JSON functionality
npm test tests/unit/json-commands.test.mjs

# Clean up
docker-compose -f docker-compose.valkey-bundle.yml down

See TESTING-VALKEY-MODULES.md for complete testing guide.

✅ Real-World Compatibility Validation

We've validated our adapter against 19 real-world usage patterns found in production applications across GitHub and Stack Overflow. All tests pass, proving true drop-in compatibility:

✅ Production Patterns Validated

Pattern Category	Examples	Status
Basic Operations	String operations, complex operations with WITHSCORES	✅ Validated
Hash Operations	Object-based hset, individual operations, analytics	✅ Validated
Bull Queue Integration	Job serialization, configuration patterns	✅ Validated
Session Store	Express sessions with TTL, user data storage	✅ Validated
Caching Patterns	JSON serialization, cache miss/hit patterns	✅ Validated
Analytics & Counters	Page views, user activity tracking	✅ Validated
Task Queues	List-based queues with lpush/rpop	✅ Validated
Rate Limiting	Sliding window with sorted sets	✅ Validated
Pub/Sub	Channel subscriptions and publishing	✅ Validated
Error Handling	Connection resilience, type mismatches	✅ Validated

📊 Test Coverage Breakdown

// All these real-world patterns work without any code changes:

// 1. Bull Queue Pattern (from production configs)
const redis = new Redis({ host: 'localhost', port: 6379 });
// Works with Bull without any modifications

// 2. Express Session Pattern
await redis.setex('sess:abc123', 1800, JSON.stringify(sessionData));

// 3. Complex Operations (from ioredis examples)
await redis.zadd('sortedSet', 1, 'one', 2, 'dos');
const result = await redis.zrange('sortedSet', 0, 2, 'WITHSCORES'); // ✅ Works perfectly

// 4. Caching Pattern with JSON
await redis.setex(cacheKey, 3600, JSON.stringify(userData));
const cached = JSON.parse(await redis.get(cacheKey));

// 5. Rate Limiting Pattern
await redis.zadd(`rate_limit:${userId}`, Date.now(), `req:${Date.now()}`);
await redis.zremrangebyscore(key, 0, Date.now() - 60000);

🔍 Patterns Sourced From:

• GitHub repositories with 1000+ stars
• Stack Overflow top-voted solutions
• Production applications from major companies
• Popular Redis library documentation examples

🧪 Run Validation Tests:

npm test tests/integration/real-world-patterns.test.ts

🎯 Performance Benefits

• Native GLIDE Methods: Uses GLIDE's optimized implementations instead of generic Redis commands
• Result Translation: Efficient conversion between GLIDE's structured responses and ioredis formats
• Type Safety: Leverages GLIDE's TypeScript interfaces for better development experience
• Rust Core: Benefits from GLIDE's high-performance Rust implementation

📚 Documentation

• 🔄 Migration Guide: Zero-code migration from ioredis
• 🏆 Compatibility Matrix: Complete compatibility validation results
• Pub/Sub Guide: Comprehensive guide to both pub/sub patterns
• Development Rules: Pure GLIDE development principles
• API Migration: Detailed mapping from ioredis to GLIDE

🧪 Testing & Validation

✅ Validated Production Use Cases

# Core Valkey Operations (All Pass)
npm test tests/unit/string-commands.test.mjs   # String ops: 37 tests ✅
npm test tests/unit/hash-commands.test.mjs     # Hash ops: 13 tests ✅  
npm test tests/unit/list-commands.test.mjs     # List ops: 16 tests ✅
npm test tests/unit/set-commands.test.mjs      # Set ops: 19 tests ✅
npm test tests/unit/zset-commands.test.mjs     # ZSet ops: 14 tests ✅

# Advanced Modules (All Pass)
npm test tests/unit/json-commands.test.mjs     # JSON documents: 29 tests ✅
npm test tests/unit/stream-commands.test.mjs   # Stream ops: 15 tests ✅
npm test tests/unit/script-commands.test.mjs   # Lua scripts: 12 tests ✅
npm test tests/unit/transaction-commands.test.mjs # Transactions: 3 tests ✅

# Real-World Integrations (All Pass)
npm test tests/integration/bullmq/            # Job queues: Bull/BullMQ ✅
npm test tests/integration/socketio/          # Real-time: Socket.IO ✅  
npm test tests/integration/session-store/     # Sessions: Express/connect-redis ✅

🎯 Production Confidence

What This Means for You:

• ✅ Immediate Use: Drop-in replacement for most common ioredis use cases
• ✅ Battle Tested: Major server libraries (Bull, Socket.IO, sessions) validated
• ✅ Enterprise Ready: Connection management, transactions, pipelines work
• 🔧 Minor Gaps: Some advanced edge cases being refined (non-blocking)

🚀 Quick Validation

# Test your specific use case
npm test -- --testNamePattern="your-pattern"  # Run targeted tests
npm test tests/integration/                   # Test all integrations

🔄 Zero-Code Migration from ioredis

🎯 Step 1: Simple Import Change

// Before (ioredis)
import Redis from 'ioredis';
const redis = new Redis({ host: 'localhost', port: 6379 });

// After (GLIDE adapter) - Just change the import!
import { Redis } from 'valkey-glide-ioredis-adapter';
const redis = new Redis({ host: 'localhost', port: 6379 });

✅ Everything Else Stays The Same

// All your existing code works without changes:
await redis.set('key', 'value');
await redis.hset('hash', 'field', 'value');
await redis.zadd('zset', 1, 'member');
const results = await redis.zrange('zset', 0, -1, 'WITHSCORES');

// Bull queues work without changes:
const queue = new Bull('email', { redis: { host: 'localhost', port: 6379 } });

// Express sessions work without changes:
app.use(session({
  store: new RedisStore({ client: redis }),
  // ... other options
}));

✅ Cluster Support

import { Cluster } from 'valkey-glide-ioredis-adapter';

// Cluster client (ioredis-compatible constructor)
const cluster = new Cluster([
  { host: '127.0.0.1', port: 7000 },
  { host: '127.0.0.1', port: 7001 },
  { host: '127.0.0.1', port: 7002 }
], {
  // Cluster options
  redirection: 'follow',
  retryDelayOnFailover: 100
});

// Works with Bull cluster
const clusterQueue = new Bull('cluster-jobs', {
  createClient: (type) => Cluster.createClient(type, {
    nodes: [/* cluster nodes */]
  })
});

🏗️ Architecture

Translation Layer Approach

Application Code
       ↓
ioredis API
       ↓
Parameter Translation
       ↓
Native GLIDE Methods
       ↓
Result Translation
       ↓
ioredis Results

Core Components

src/
├── BaseClient.ts         # Core GLIDE client wrapper
├── Redis.ts              # ioredis-compatible Redis class  
├── Cluster.ts            # ioredis-compatible Cluster class
├── StandaloneClient.ts   # Standalone-specific implementation
├── ClusterClient.ts      # Cluster-specific implementation
└── utils/                # Translation and utility functions

🤝 Contributing

This project follows pure GLIDE principles:

• Use only GLIDE APIs
• Implement custom logic when needed
• Maintain ioredis compatibility through translation
• Comprehensive testing required

📄 License

Apache-2.0 License - see LICENSE file for details.

🔗 Related Projects

Core Dependencies

• Valkey GLIDE - The underlying high-performance Rust-based client that powers this adapter
• ioredis - The original Redis client whose API we maintain full compatibility with

Compatible Libraries (Tested & Validated)

• Bull - Redis-based queue for Node.js, fully compatible
• BullMQ - Modern Redis-based queue with advanced features
• Bee Queue - Simple, fast, robust job/task queue for Node.js
• connect-redis - Redis session store for Express/Connect
• express-rate-limit - Rate limiting middleware for Express
• socket.io-redis-adapter - Socket.IO adapter for horizontal scaling

Module Ecosystems

• ValkeyJSON - JSON document storage and manipulation module
• Valkey - High-performance server with module support