feat: implement Redis-based storage for rate limiting, mutex, and semaphore utilities

Author: twlite

apps/website/docs/guide/14-useful-utilities/01-ratelimit.mdx

@@ -74,26 +74,27 @@ By default, rate limiters store data in memory. If you're running multiple serve
 
 ```typescript
 import { RateLimiter, RateLimitStorage } from 'commandkit/ratelimit';
+import { RedisRateLimitStorage } from '@commandkit/redis';
+import { Redis } from 'ioredis';
 
-// Example of how you might use Redis for rate limiting
-class RedisRateLimitStorage implements RateLimitStorage {
-  async get(key: string): Promise<number> {
-    // Get the current count from Redis
-    return (await redis.get(key)) || 0;
-  }
-
-  async set(key: string, value: number): Promise<void> {
-    // Store the count in Redis
-    await redis.set(key, value);
-  }
-
-  async delete(key: string): Promise<void> {
-    // Remove the count from Redis
-    await redis.del(key);
-  }
-}
+// Create Redis client
+const redis = new Redis();
+
+// Use Redis-based rate limit storage
+const limiter = new RateLimiter(10, 60000, new RedisRateLimitStorage(redis));
+```
+
+You can also use the convenience function:
 
-const limiter = new RateLimiter(10, 60000, new RedisRateLimitStorage());
+```typescript
+import { createRateLimiter } from 'commandkit/ratelimit';
+import { RedisRateLimitStorage } from '@commandkit/redis';
+
+const limiter = createRateLimiter({
+  maxRequests: 10,
+  interval: 60000,
+  storage: new RedisRateLimitStorage(redis),
+});
 ```
 
 ## Default Settings

apps/website/docs/guide/14-useful-utilities/02-mutex.mdx

@@ -95,30 +95,28 @@ By default, mutexes store lock information in memory. If you're running multiple
 
 ```typescript
 import { Mutex, MutexStorage } from 'commandkit/mutex';
+import { RedisMutexStorage } from '@commandkit/redis';
+import { Redis } from 'ioredis';
 
-// Example of how you might use Redis for mutex locks
-class RedisMutexStorage implements MutexStorage {
-  async acquire(
-    key: string,
-    timeout?: number,
-    signal?: AbortSignal,
-  ): Promise<boolean> {
-    // Try to acquire a lock in Redis
-    // Return true if successful, false if already locked
-  }
-
-  async release(key: string): Promise<void> {
-    // Release the lock in Redis
-  }
-
-  async isLocked(key: string): Promise<boolean> {
-    // Check if a lock exists in Redis
-  }
-}
+// Create Redis client
+const redis = new Redis();
 
+// Use Redis-based mutex storage
 const mutex = new Mutex({
   timeout: 30000,
-  storage: new RedisMutexStorage(),
+  storage: new RedisMutexStorage(redis),
+});
+```
+
+You can also use the convenience function:
+
+```typescript
+import { createMutex } from 'commandkit/mutex';
+import { RedisMutexStorage } from '@commandkit/redis';
+
+const mutex = createMutex({
+  timeout: 60000,
+  storage: new RedisMutexStorage(redis),
 });
 ```
 

apps/website/docs/guide/14-useful-utilities/03-semaphore.mdx

@@ -113,35 +113,30 @@ By default, semaphores store permit information in memory. If you're running mul
 
 ```typescript
 import { Semaphore, SemaphoreStorage } from 'commandkit/semaphore';
+import { RedisSemaphoreStorage } from '@commandkit/redis';
+import { Redis } from 'ioredis';
 
-// Example of how you might use Redis for semaphore permits
-class RedisSemaphoreStorage implements SemaphoreStorage {
-  async acquire(
-    key: string,
-    timeout?: number,
-    signal?: AbortSignal,
-  ): Promise<boolean> {
-    // Try to acquire a permit in Redis
-    // Return true if successful, false if no permits available
-  }
-
-  async release(key: string): Promise<void> {
-    // Release a permit in Redis
-  }
-
-  async getAvailablePermits(key: string): Promise<number> {
-    // Get the number of available permits from Redis
-  }
-
-  async getTotalPermits(key: string): Promise<number> {
-    // Get the total number of permits from Redis
-  }
-}
+// Create Redis client
+const redis = new Redis();
 
+// Use Redis-based semaphore storage
 const semaphore = new Semaphore({
   permits: 10,
   timeout: 30000,
-  storage: new RedisSemaphoreStorage(),
+  storage: new RedisSemaphoreStorage(redis),
+});
+```
+
+You can also use the convenience function:
+
+```typescript
+import { createSemaphore } from 'commandkit/semaphore';
+import { RedisSemaphoreStorage } from '@commandkit/redis';
+
+const semaphore = createSemaphore({
+  permits: 5,
+  timeout: 60000,
+  storage: new RedisSemaphoreStorage(redis),
 });
 ```
 

apps/website/docs/guide/14-useful-utilities/index.mdx

@@ -97,27 +97,32 @@ const result = await queue.add(async () => await task());
 
 ### Using External Storage
 
-By default, these utilities store their data in memory. But if you're running multiple instances of your application (like on different servers), you'll want to use external storage like Redis so they can share information.
+All utilities support custom storage implementations for distributed environments:
 
 ```typescript
-// Example of how you might use Redis for rate limiting
-class RedisRateLimitStorage implements RateLimitStorage {
-  async get(key: string): Promise<number> {
-    // Get the current count from Redis
-    return (await redis.get(key)) || 0;
-  }
-  async set(key: string, value: number): Promise<void> {
-    // Store the count in Redis
-    await redis.set(key, value);
-  }
-  async delete(key: string): Promise<void> {
-    // Remove the count from Redis
-    await redis.del(key);
-  }
-}
+// Redis storage implementations are available from @commandkit/redis
+import {
+  RedisRateLimitStorage,
+  RedisMutexStorage,
+  RedisSemaphoreStorage,
+} from '@commandkit/redis';
+import { Redis } from 'ioredis';
+
+const redis = new Redis();
+
+// Rate limiting with Redis
+const rateLimiter = createRateLimiter({
+  storage: new RedisRateLimitStorage(redis),
+});
+
+// Mutex with Redis
+const mutex = createMutex({
+  storage: new RedisMutexStorage(redis),
+});
 
-const limiter = createRateLimiter({
-  storage: new RedisRateLimitStorage(),
+// Semaphore with Redis
+const semaphore = createSemaphore({
+  storage: new RedisSemaphoreStorage(redis),
 });
 ```
 

packages/redis/README.md

@@ -47,4 +47,127 @@ const redis = new Redis();
 const redisProvider = new RedisCacheProvider(redis);
 
 setCacheProvider(redisProvider)
+```
+
+## Redis Mutex Storage
+
+This package also provides a Redis-based mutex storage implementation for distributed locking:
+
+```ts
+import { createMutex } from 'commandkit/mutex';
+import { RedisMutexStorage } from '@commandkit/redis';
+import { Redis } from 'ioredis';
+
+// Create Redis client
+const redis = new Redis();
+
+// Create Redis-based mutex storage
+const redisMutexStorage = new RedisMutexStorage(redis);
+
+// Create mutex with Redis storage
+const mutex = createMutex({
+  timeout: 30000,
+  storage: redisMutexStorage,
+});
+
+// Use the mutex for distributed locking
+const result = await mutex.withLock('shared-resource', async () => {
+  // This code runs with exclusive access across all instances
+  return await updateSharedResource();
+});
+```
+
+### Redis Mutex Features
+
+- **Distributed Locking**: Works across multiple application instances
+- **Automatic Expiration**: Locks automatically expire to prevent deadlocks
+- **Abort Signal Support**: Can be cancelled using AbortSignal
+- **Atomic Operations**: Uses Lua scripts for atomic lock operations
+- **Lock Extension**: Extend lock timeouts if needed
+- **Force Release**: Emergency release of locks (use with caution)
+
+### Advanced Mutex Usage
+
+```ts
+import { RedisMutexStorage } from '@commandkit/redis';
+
+const redisStorage = new RedisMutexStorage(redis);
+
+// Get detailed lock information
+const lockInfo = await redisStorage.getLockInfo('my-resource');
+console.log(`Locked: ${lockInfo.locked}, TTL: ${lockInfo.ttl}ms`);
+
+// Extend a lock
+const extended = await redisStorage.extendLock('my-resource', 60000);
+if (extended) {
+  console.log('Lock extended by 60 seconds');
+}
+
+// Force release a lock (emergency use only)
+await redisStorage.forceRelease('my-resource');
+```
+
+## Redis Semaphore Storage
+
+This package also provides a Redis-based semaphore storage implementation for distributed concurrency control:
+
+```ts
+import { createSemaphore } from 'commandkit/semaphore';
+import { RedisSemaphoreStorage } from '@commandkit/redis';
+import { Redis } from 'ioredis';
+
+// Create Redis client
+const redis = new Redis();
+
+// Create Redis-based semaphore storage
+const redisSemaphoreStorage = new RedisSemaphoreStorage(redis);
+
+// Create semaphore with Redis storage
+const semaphore = createSemaphore({
+  permits: 5,
+  timeout: 30000,
+  storage: redisSemaphoreStorage,
+});
+
+// Use the semaphore for distributed concurrency control
+const result = await semaphore.withPermit('database-connection', async () => {
+  // This code runs with limited concurrency across all instances
+  return await executeDatabaseQuery();
+});
+```
+
+### Redis Semaphore Features
+
+- **Distributed Concurrency Control**: Works across multiple application instances
+- **Automatic Initialization**: Semaphores are automatically initialized when first used
+- **Abort Signal Support**: Can be cancelled using AbortSignal
+- **Atomic Operations**: Uses Lua scripts for atomic permit operations
+- **Dynamic Permit Management**: Increase or decrease permits at runtime
+- **Semaphore Information**: Get detailed information about permit usage
+
+### Advanced Semaphore Usage
+
+```ts
+import { RedisSemaphoreStorage } from '@commandkit/redis';
+
+const redisStorage = new RedisSemaphoreStorage(redis);
+
+// Get detailed semaphore information
+const info = await redisStorage.getSemaphoreInfo('database');
+console.log(`Total: ${info.total}, Available: ${info.available}, Acquired: ${info.acquired}`);
+
+// Initialize a semaphore with specific permits
+await redisStorage.initialize('api-endpoint', 10);
+
+// Increase permits dynamically
+await redisStorage.increasePermits('database', 5);
+
+// Decrease permits dynamically
+await redisStorage.decreasePermits('api-endpoint', 2);
+
+// Reset semaphore to initial state
+await redisStorage.reset('database');
+
+// Clear semaphore completely
+await redisStorage.clear('old-semaphore');
 ```

packages/redis/src/index.ts

@@ -150,3 +150,7 @@ export class RedisPlugin extends RuntimePlugin<RedisOptions> {
 export function redis(options?: RedisOptions) {
   return new RedisPlugin(options ?? {});
 }
+
+export * from './ratelimit-storage';
+export * from './mutex-storage';
+export * from './semaphore-storage';