Back to Projects

redlock-universal

Production-ready distributed Redis locks for Node.js with universal client support and enterprise monitoring

283

Tests (95%+ coverage)

<1ms

Lock acquisition

Universal

Client support

0

Dependencies

The Challenge

The Node.js Redis lock ecosystem was fragmented. Existing solutions either:

  • Support only single Redis instances (simple-redis-mutex)
  • Work with just one Redis client library (node-redlock)
  • Lack production-ready error handling and monitoring
  • Use outdated TypeScript or have poor developer experience
  • Don't implement the full Redlock algorithm correctly

The Solution

Built the first universal Redis lock library that combines distributed safety with universal compatibility:

True Redlock Algorithm

Full Redis-spec implementation with clock drift handling and consensus-based acquisition

Universal Client Support

Native adapter pattern supporting both node-redis v4+ and ioredis v5+ without preference

Performance Optimized

Sub-millisecond lock acquisition with memory leak prevention and zero runtime dependencies

Production Ready

Comprehensive error handling, retry mechanisms, and built-in observability infrastructure

Technical Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Lock API   │     │  Redlock    │     │   Redis     │
│ (Universal) │────▶│  Algorithm  │────▶│  Instances  │
└─────────────┘     └─────────────┘     └─────────────┘
       │                    │                    │
       ▼                    ▼                    ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │     │   Adapter   │     │   Cluster   │
│  Adapters   │     │   Pattern   │     │  Consensus  │
└─────────────┘     └─────────────┘     └─────────────┘

Tech Stack

TypeScriptRedisnode-redisioredisVitestTSupGitHub ActionsESM/CJS

Results & Impact

Technical Achievements

  • ✓ First library with universal Redis client support
  • ✓ True distributed consensus algorithm implementation
  • ✓ Performance optimized (<1ms, <7KB memory)
  • ✓ Production-grade error handling and observability

Open Source Impact

  • ✓ Published on NPM with semantic versioning
  • ✓ Comprehensive documentation and examples
  • ✓ MIT license for maximum adoption
  • ✓ Automated CI/CD pipeline for quality assurance

Key Technical Decisions

Adapter Pattern for Client Abstraction

Built universal adapters to abstract Redis client differences while preserving native performance

Zero Dependencies for Production Reliability

Avoided external dependencies to eliminate supply chain risks and ensure maximum stability

TypeScript-First Development

Built with strict TypeScript for superior developer experience and compile-time safety

Algorithm Correctness Over Convenience

Prioritized Redis-spec compliance and distributed systems correctness over API simplicity

My Role

As sole architect and maintainer, I:

  • Researched and implemented the full Redis Redlock specification
  • Designed the adapter pattern architecture for universal client compatibility
  • Built comprehensive test suite covering unit, integration, and cross-process scenarios
  • Optimized performance to achieve sub-millisecond lock acquisition
  • Established modern development workflow with semantic-release and automated CI/CD
  • Created documentation, examples, and migration guides for community adoption
View SourceNPM Package