Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/kv
Redis client and rate limiting utilities for Carbon applications using ioredis.
Installation
This package is part of the Carbon monorepo and is available as @carbon/kv.
Environment Variables
REDIS_URL="redis://user:password@host:port"
Usage
Redis Client
import { redis } from "@carbon/kv";
// Basic operations
await redis.set("key", "value");
await redis.set("key", "value", "EX", 300); // With 5 min expiration
const value = await redis.get("key");
await redis.del("key");
Rate Limiting
The Ratelimit class provides a drop-in replacement for @upstash/ratelimit using ioredis.
import { Ratelimit, redis } from "@carbon/kv";
const ratelimit = new Ratelimit({
redis,
limiter: Ratelimit.slidingWindow(10, "1 h"), // 10 requests per hour
analytics: true, // Compatibility option (no-op)
});
// Check rate limit
const { success, limit, remaining, reset } = await ratelimit.limit(identifier);
if (!success) {
// Rate limited - return 429
}
Algorithms
Sliding Window
Combines two fixed windows with weighted scoring for smooth rate limiting. Prevents boundary burst issues.
Ratelimit.slidingWindow(tokens, window);
// Examples
Ratelimit.slidingWindow(10, "1 h"); // 10 requests per hour
Ratelimit.slidingWindow(100, "1 m"); // 100 requests per minute
Ratelimit.slidingWindow(5, "10 s"); // 5 requests per 10 seconds
Fixed Window
Simple counter that resets at fixed intervals. Low memory usage but can allow bursts at boundaries.
Ratelimit.fixedWindow(tokens, window);
// Examples
Ratelimit.fixedWindow(100, "1 m"); // 100 requests per minute
Ratelimit.fixedWindow(1000, "1 h"); // 1000 requests per hour
Token Bucket
Refillable bucket that allows controlled bursts while maintaining average rate.
Ratelimit.tokenBucket(refillRate, interval, maxTokens?);
// Examples
Ratelimit.tokenBucket(1, "1 s", 10); // 1 token/sec, burst up to 10
Ratelimit.tokenBucket(10, "1 m", 50); // 10 tokens/min, burst up to 50
Configuration Options
interface RatelimitConfig {
redis: Redis; // ioredis client instance
limiter: () => Algorithm; // Algorithm factory
prefix?: string; // Key prefix (default: "@upstash/ratelimit")
ephemeralCache?: boolean | Map<string, number>; // In-memory cache for blocked IDs
timeout?: number; // Redis timeout in ms (default: 5000)
analytics?: boolean; // Compatibility option (no-op)
}
Response Object
interface RatelimitResponse {
success: boolean; // Whether request is allowed
limit: number; // Maximum requests in window
remaining: number; // Remaining requests in window
reset: number; // Unix timestamp (ms) when limit resets
pending: Promise<unknown>; // Resolves when operations complete
}
Additional Methods
// Get remaining without consuming
const { remaining, reset, limit } = await ratelimit.getRemaining(identifier);
// Reset rate limit for identifier
await ratelimit.resetUsedTokens(identifier);
// Block until allowed or timeout
const result = await ratelimit.blockUntilReady(identifier, timeoutMs);
Duration Format
Durations can be specified with or without spaces:
ms- milliseconds:"100ms","100 ms"s- seconds:"10s","10 s"m- minutes:"5m","5 m"h- hours:"1h","1 h"d- days:"7d","7 d"
Migration from @upstash/ratelimit
- Update imports:
// Before
import { Ratelimit } from "@upstash/ratelimit";
import { redis } from "@carbon/kv";
// After
import { Ratelimit, redis } from "@carbon/kv";
- Update environment variables:
# Before
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."
# After
REDIS_URL="redis://..."
- Update
redis.set()calls with expiration:
// Before (Upstash syntax)
await redis.set(key, value, { ex: 300 });
// After (ioredis syntax)
await redis.set(key, value, "EX", 300);
Testing
npm test # Run tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage