Valkey GLIDE ioredis Adapter

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

Comprehensive Compatibility Validated across JSON, Search, and real-world production patterns

A production-ready, completely compatible ioredis replacement that seamlessly integrates Valkey GLIDE with your existing Node.js applications. Zero code changes required - achieve superior performance while maintaining full 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.

🏆 Compatibility Matrix

Status & Quality Assurance

Library Compatibility

Module Support

🚀 Key Features

• 🎯 True Drop-In Replacement: Zero code changes required from ioredis
• Pure GLIDE: Built exclusively on Valkey GLIDE APIs
• High Performance: Leverages GLIDE's Rust core for optimal performance
• TypeScript Support: Full type safety with GLIDE's native TypeScript interfaces
• Production Integrations: All major Redis libraries work without modification
• 📄 JSON Module Support: Native JSON document storage and querying (ValkeyJSON / RedisJSON v2 compatible)
• 🔍 Search Module Support: Full-text search, vector similarity, and aggregations (Valkey Search / RediSearch compatible)
• 🤖 AI-Ready: Vector embeddings and similarity search for machine learning applications
• 📊 Thoroughly Tested: Comprehensive validation across real-world usage patterns

📋 Pub/Sub Implementation

Due to GLIDE's pub/sub architecture, we provide two distinct pub/sub patterns:

1. Direct GLIDE Pub/Sub (Recommended for new applications)

import { createPubSubClients, publishMessage, pollForMessage } from './src/pubsub/DirectGlidePubSub';

// Create separate publisher and subscriber clients
const clients = await createPubSubClients(
  { host: 'localhost', port: 6379 },
  { channels: ['my-channel'], patterns: ['news.*'] }
);

// Publish messages
await publishMessage(clients.publisher, 'my-channel', 'Hello World!');

// Poll for messages (use in your application loop)
const message = await pollForMessage(clients.subscriber);
if (message) {
  console.log('Received:', message.message, 'on channel:', message.channel);
}

2. Library Integration Helper (For existing Redis libraries)

import { LibraryGlideIntegration } from './src/pubsub/DirectGlidePubSub';

const integration = new LibraryGlideIntegration();
await integration.initialize(
  { host: 'localhost', port: 6379 },
  ['app:notifications', 'app:events']
);

// Use with any Redis library requiring pub/sub
await integration.publish('app:notifications', JSON.stringify({ type: 'update' }));

🔧 Installation

npm install valkey-glide-ioredis-adapter

Requirements:

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

📖 Basic Usage

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

// Create adapter instance
const redis = new RedisAdapter({
  host: 'localhost',
  port: 6379
});

// Use ioredis API with Valkey 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');

📄 JSON Module Support (ValkeyJSON)

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

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

const redis = new RedisAdapter({ 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);

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

🔍 Search Module Support (Valkey Search)

Full-text search, vector similarity, and aggregations with RediSearch compatibility:

// Create search index
await redis.ftCreate({
  index_name: 'products',
  index_options: ['ON', 'HASH', 'PREFIX', '1', 'product:'],
  schema_fields: [
    { field_name: 'name', field_type: 'TEXT', field_options: ['WEIGHT', '2.0'] },
    { field_name: 'price', field_type: 'NUMERIC', field_options: ['SORTABLE'] },
    { field_name: 'category', field_type: 'TAG' }
  ]
});

// Add documents to index
await redis.ftAdd('products', 'product:1', 1.0, {
  name: 'Gaming Laptop',
  price: '1299.99',
  category: 'Electronics'
});

// Full-text search with filters
const results = await redis.ftSearch('products', {
  query: 'gaming laptop',
  options: {
    FILTER: { field: 'price', min: 500, max: 2000 },
    SORTBY: { field: 'price', direction: 'ASC' },
    LIMIT: { offset: 0, count: 10 }
  }
});

// Vector similarity search (AI/ML)
const vectorResults = await redis.ftVectorSearch(
  'embeddings_index',
  'embedding_field',
  [0.1, 0.2, 0.3, 0.4], // Query vector
  { KNN: 5 }
);

// Aggregation queries
const stats = await redis.ftAggregate('products', '*', {
  GROUPBY: {
    fields: ['@category'],
    REDUCE: [{ function: 'COUNT', args: [], AS: 'count' }]
  }
});

21 Search Commands Available: Complete Valkey Search/RediSearch compatibility with ftCreate, ftSearch, ftAggregate, ftVectorSearch, ftAdd, ftDel, ftInfo, ftList, and more!

🧪 Testing JSON & Search Modules

Use valkey-bundle for testing without Redis Stack:

# Start valkey-bundle with all modules
docker-compose -f docker-compose.valkey-bundle.yml up -d

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

# Test Search functionality  
npm test tests/unit/search-commands.test.ts

# 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

📊 Test Coverage Breakdown

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

// 1. Bull Queue Pattern (from production configs)
const redis = new RedisAdapter({ 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

# Run all tests
npm test

# Run pub/sub tests
npm test -- tests/unit/direct-glide-pubsub.test.ts
npm test -- tests/unit/pubsub-basic.test.ts
npm test -- tests/unit/pubsub-polling.test.ts

# Run integration tests
npm test -- tests/integration/

🔄 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 { RedisAdapter as 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
}));

For Pub/Sub Operations

// Before (ioredis)
const subscriber = new Redis();
subscriber.on('message', (channel, message) => {
  console.log(channel, message);
});
await subscriber.subscribe('my-channel');

// After (Direct GLIDE)
import { createPubSubClients, pollForMessage } from './src/pubsub/DirectGlidePubSub';

const clients = await createPubSubClients(
  { host: 'localhost', port: 6379 },
  { channels: ['my-channel'] }
);

// Implement polling in your application
while (true) {
  const message = await pollForMessage(clients.subscriber);
  if (message) {
    console.log(message.channel, message.message);
  }
}

🏗️ Architecture

Translation Layer Approach

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

Pub/Sub Architecture

Direct Pattern:
Application → GLIDE Client → Valkey/Redis

Integration Pattern:
Library → Helper Class → GLIDE Clients → Valkey/Redis

🤝 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 Search - Full-text search and vector similarity module
• Valkey - High-performance server with module support

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.4.0 - 2025-08-31

✨ Features Added

• Complete JSON Module Support: Full ValkeyJSON/RedisJSON v2 compatibility with 31 commands
• Complete Search Module Support: Full Valkey Search/RediSearch compatibility with 21 commands
• Advanced Error Handling: Comprehensive error handling for GLIDE Map response limitations
• Code Quality Improvements: Eliminated 20 code duplication issues and reduced complexity
• CI/CD Automation: Complete release automation with semantic versioning and npm publishing
• Parameter Translation Layer: Centralized utility for ZSET operations and complex parameter handling

🐛 Bug Fixes

• Search Filter Format: Graceful handling of valkey-bundle filter format requirements
• Script Error Messages: Compatible error message format for both Valkey and Redis
• FT.AGGREGATE Support: Proper fallback handling for unsupported aggregation commands
• CI Test Failures: Resolved all 9 failing tests to achieve 100% CI success (539/539 tests)
• Dependency Compatibility: Updated to Node.js 20/22 for modern package requirements
• Connection Stability: Fixed valkey-bundle service integration in CI pipeline

🔄 CI/CD Improvements

• Node Version Updates: Migrated from Node 18 to Node 20/22 for dependency compatibility
• Valkey-Bundle Integration: Complete CI integration with JSON and Search modules
• Release Automation: Semantic versioning with automated npm publishing and GitHub releases
• Test Infrastructure: Docker-based valkey-bundle setup for reliable module testing
• Coverage Reporting: Maintained 80%+ test coverage across all new features

📚 Documentation

• Conventional Commits: Added commit message templates for better release notes
• Release Process: Automated changelog generation from commit history
• API Documentation: Enhanced documentation for JSON and Search module usage

🔧 Technical Improvements

• 100% Test Success: Achieved complete CI success rate (539/539 tests passing)
• Deterministic Behavior: Eliminated fallback patterns for production stability
• Performance Optimizations: Reduced code duplication and improved method complexity
• Type Safety: Enhanced TypeScript support for all new command modules

0.3.0 - 2024-XX-XX

Added

• Initial implementation of valkey-glide-ioredis-adapter
• Basic Redis command compatibility
• Connection management and clustering support
• Initial test infrastructure