sidekiq-ts 1.1.0 → 1.2.0

package/README.md

@@ -12,6 +12,7 @@ A TypeScript implementation of [Sidekiq](https://sidekiq.org/) for Node.js. Proc
 - **Leader election** - Coordinate across distributed workers
 - **Cron jobs** - Periodic job scheduling with standard cron expressions
 - **Middleware** - Customize job enqueueing and execution
+- **Rate limiting** - Control concurrent operations and API call rates
 - **CLI** - Run workers from the command line
 - **Testing utilities** - Fake and inline modes for testing
 
@@ -396,6 +397,157 @@ class TimingMiddleware {
 Sidekiq.useServerMiddleware(TimingMiddleware);
 ```
 
+## Rate Limiting
+
+Limit concurrent operations or API call rates across all workers. Similar to [Sidekiq Enterprise rate limiting](https://github.com/sidekiq/sidekiq/wiki/Ent-Rate-Limiting).
+
+### Creating Limiters
+
+```typescript
+import { Limiter } from "sidekiq-ts";
+
+// Limit concurrent operations (distributed mutex)
+const apiLimiter = Limiter.concurrent("external-api", 50);
+
+// Limit operations per time boundary (resets at interval start)
+const emailLimiter = Limiter.bucket("email-send", 100, "minute");
+
+// Limit operations in a rolling window
+const requestLimiter = Limiter.window("api-requests", 1000, "hour");
+```
+
+### Using in Jobs
+
+```typescript
+import { Job, Limiter } from "sidekiq-ts";
+
+const stripeLimiter = Limiter.concurrent("stripe-api", 25);
+
+class ChargeCustomerJob extends Job<[string, number]> {
+  async perform(customerId: string, amount: number) {
+    await stripeLimiter.withinLimit(async () => {
+      await stripe.charges.create({
+        customer: customerId,
+        amount,
+      });
+    });
+  }
+}
+```
+
+When the limit is exceeded, `withinLimit()` throws an `OverLimitError`.
+
+### Auto-Reschedule with Middleware
+
+To automatically reschedule jobs when rate limited (like Sidekiq Enterprise):
+
+```typescript
+import { Sidekiq, ensureRateLimitMiddleware } from "sidekiq-ts";
+
+// Add the middleware before starting the worker
+ensureRateLimitMiddleware(Sidekiq.defaultConfiguration);
+
+const runner = await Sidekiq.run();
+```
+
+The middleware catches `OverLimitError` and reschedules the job with backoff (~5 minutes + jitter). After 20 reschedules, the job fails normally.
+
+### Limiter Types
+
+#### Concurrent Limiter
+
+Limits how many operations can run simultaneously across all workers:
+
+```typescript
+// Max 10 concurrent Stripe API calls
+const limiter = Limiter.concurrent("stripe", 10, {
+  lockTimeout: 180, // Auto-release lock after 180 seconds (default)
+});
+```
+
+#### Bucket Limiter
+
+Allows N operations per time interval, resetting at boundaries:
+
+```typescript
+// 100 emails per minute, resets at :00 of each minute
+const limiter = Limiter.bucket("email", 100, "minute");
+
+// With numeric interval (seconds)
+const limiter = Limiter.bucket("sms", 50, 30); // 50 per 30 seconds
+```
+
+Intervals: `"second"`, `"minute"`, `"hour"`, `"day"`, or number of seconds.
+
+#### Window Limiter
+
+Allows N operations in a rolling time window:
+
+```typescript
+// 1000 requests per hour, rolling window
+const limiter = Limiter.window("api", 1000, "hour");
+```
+
+### Limiter Methods
+
+```typescript
+// Execute within the rate limit
+await limiter.withinLimit(async () => {
+  await doWork();
+});
+
+// Check current status (non-blocking)
+const status = await limiter.check();
+console.log(status.allowed);  // true if under limit
+console.log(status.current);  // current usage
+console.log(status.limit);    // max allowed
+
+// Reset the limiter
+await limiter.reset();
+```
+
+### Dynamic Limiters
+
+Create per-user or per-resource limiters with dynamic names:
+
+```typescript
+class UserApiCallJob extends Job<[string, string]> {
+  async perform(userId: string, endpoint: string) {
+    // Each user gets their own rate limit
+    const userLimiter = Limiter.window(`user-${userId}-api`, 100, "minute");
+
+    await userLimiter.withinLimit(async () => {
+      await fetch(endpoint);
+    });
+  }
+}
+```
+
+Redis keys are created per unique name: `limiter:user-123-api`, `limiter:user-456-api`, etc.
+
+For high-throughput scenarios, cache limiter instances:
+
+```typescript
+const userLimiters = new Map<string, ILimiter>();
+
+function getUserLimiter(userId: string): ILimiter {
+  let limiter = userLimiters.get(userId);
+  if (!limiter) {
+    limiter = Limiter.window(`user-${userId}-api`, 100, "minute");
+    userLimiters.set(userId, limiter);
+  }
+  return limiter;
+}
+```
+
+### Custom Key Prefix
+
+```typescript
+const limiter = Limiter.concurrent("api", 10, {
+  keyPrefix: "myapp", // Redis key: myapp:api (default: limiter:api)
+});
+```
+
 ## Leader Election
 
 For tasks that should only run on one worker (like cron jobs), use leader election:
@@ -633,66 +785,46 @@ The worker handles these signals:
 | `SIGTSTP` | Quiet mode (stop accepting new jobs) |
 | `SIGTTIN` | Dump current job state to logs |
 
-The shutdown timeout (default: 25 seconds) allows in-flight jobs to complete before forced termination.
+### Quiet Mode
 
-## Production Deployment
+When a worker enters quiet mode (`runner.quiet()` or `SIGTSTP`):
 
-### Process Manager
+1. Stops polling queues for new jobs
+2. In-flight jobs continue running to completion
+3. Worker stays alive but idle
 
-Use a process manager like systemd, PM2, or Docker:
+This is useful for graceful deploys—quiet the old workers, start new ones, then stop the old workers.
 
-**systemd example:**
+### Stop/Shutdown
 
-```ini
-[Unit]
-Description=Sidekiq Worker
-After=network.target redis.service
+When `runner.stop()` is called (or `SIGINT`/`SIGTERM` received):
 
-[Service]
-Type=simple
-User=app
-WorkingDirectory=/app
-ExecStart=/usr/bin/npx sidekiq -C /app/sidekiq.json
-Restart=always
-RestartSec=5
+1. **Quiet first** — Stops accepting new jobs
+2. **Signal jobs** — Aborts the `AbortSignal` so jobs can detect shutdown via `this.signal` or `this.interrupted()`
+3. **Wait for jobs** — Waits up to `timeout` seconds (default: 25) for in-flight jobs to complete
+4. **Requeue incomplete jobs** — Any jobs still running after the timeout are pushed back to their Redis queues (`RPUSH queue:<name>`) so another worker can pick them up
+5. **Cleanup Redis** — Removes this worker from the `processes` set and deletes heartbeat keys
 
-[Install]
-WantedBy=multi-user.target
-```
+### Redis Cleanup on Shutdown
 
-**PM2 example:**
+When a worker shuts down cleanly, it removes its presence from Redis:
 
-```javascript
-// ecosystem.config.js
-module.exports = {
-  apps: [{
-    name: "sidekiq-worker",
-    script: "npx",
-    args: "sidekiq -C sidekiq.json",
-    instances: 2,
-    exec_mode: "cluster",
-  }]
-};
+```
+SREM processes <identity>       # Remove from active processes set
+UNLINK <identity>:work          # Delete work-in-progress tracking
+UNLINK <identity>               # Delete heartbeat data
 ```
 
-**Docker example:**
+Jobs that didn't complete within the timeout are requeued:
 
-```dockerfile
-FROM node:24-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY dist ./dist
-COPY sidekiq.json ./
-CMD ["npx", "sidekiq", "-C", "sidekiq.json"]
 ```
-
-```bash
-# Build and run
-docker build -t my-worker .
-docker run -e REDIS_URL=redis://host:6379 my-worker
+RPUSH queue:<name> <job-payload>  # Push back to queue for retry
 ```
 
+This ensures no jobs are lost during deployments or restarts.
+
+## Production
+
 ### Redis Configuration
 
 For production Redis:

package/dist/index.d.ts

@@ -8,9 +8,10 @@ export { IterableJob } from "./iterable.js";
 export { IterableAbort, IterableInterrupted, JobSkipError, } from "./iterable-errors.js";
 export { Job } from "./job.js";
 export { DefaultJobLogger } from "./job-logger.js";
+export type { AcquireResult, BucketLimiterOptions, ConcurrentLimiterOptions, ILimiter, LimiterOptions, TimeInterval, WindowLimiterOptions, } from "./limiter/index.js";
+export { BucketLimiter, ConcurrentLimiter, ensureRateLimitMiddleware, Limiter, OverLimitError, RateLimitMiddleware, WindowLimiter, } from "./limiter/index.js";
 export { createLogger, Formatters, SidekiqLogger } from "./logger.js";
 export { Runner } from "./runner.js";
 export { Sidekiq } from "./sidekiq.js";
 export { EmptyQueueError, Queues, Testing } from "./testing.js";
-export type * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,KAAK,EACL,YAAY,EACZ,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChE,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,KAAK,EACL,YAAY,EACZ,OAAO,GACR,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACxB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -8,6 +8,8 @@ export { IterableJob } from "./iterable.js";
 export { IterableAbort, IterableInterrupted, JobSkipError, } from "./iterable-errors.js";
 export { Job } from "./job.js";
 export { DefaultJobLogger } from "./job-logger.js";
+// Rate limiting
+export { BucketLimiter, ConcurrentLimiter, ensureRateLimitMiddleware, Limiter, OverLimitError, RateLimitMiddleware, WindowLimiter, } from "./limiter/index.js";
 export { createLogger, Formatters, SidekiqLogger } from "./logger.js";
 export { Runner } from "./runner.js";
 export { Sidekiq } from "./sidekiq.js";

package/dist/limiter/base.d.ts

@@ -0,0 +1,16 @@
+import type { AcquireResult, ILimiter, LimiterOptions, RedisProvider } from "./types.js";
+export declare abstract class BaseLimiter implements ILimiter {
+    readonly name: string;
+    protected readonly keyPrefix: string;
+    protected readonly getRedis: RedisProvider;
+    constructor(name: string, options?: LimiterOptions, redisProvider?: RedisProvider);
+    protected get redisKey(): string;
+    /** Attempt to acquire the limit. Implemented by subclasses. */
+    protected abstract tryAcquire(): Promise<AcquireResult>;
+    /** Release any held resources. Override in ConcurrentLimiter. */
+    protected release(): Promise<void>;
+    check(): Promise<AcquireResult>;
+    reset(): Promise<void>;
+    withinLimit<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/limiter/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/limiter/base.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,8BAAsB,WAAY,YAAW,QAAQ;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;gBAGzC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,EAC5B,aAAa,CAAC,EAAE,aAAa;IAQ/B,SAAS,KAAK,QAAQ,IAAI,MAAM,CAE/B;IAED,+DAA+D;IAC/D,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IAEvD,iEAAiE;cACjD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAIzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAiB3D"}

package/dist/limiter/base.js

@@ -0,0 +1,43 @@
+import { Sidekiq } from "../sidekiq.js";
+import { OverLimitError } from "./errors.js";
+export class BaseLimiter {
+    name;
+    keyPrefix;
+    getRedis;
+    constructor(name, options = {}, redisProvider) {
+        this.name = name;
+        this.keyPrefix = options.keyPrefix ?? "limiter";
+        this.getRedis =
+            redisProvider ?? (() => Sidekiq.defaultConfiguration.getRedisClient());
+    }
+    get redisKey() {
+        return `${this.keyPrefix}:${this.name}`;
+    }
+    /** Release any held resources. Override in ConcurrentLimiter. */
+    async release() {
+        // Default: no-op
+    }
+    check() {
+        return this.tryAcquire();
+    }
+    async reset() {
+        const redis = await this.getRedis();
+        await redis.del(this.redisKey);
+    }
+    async withinLimit(fn) {
+        const result = await this.tryAcquire();
+        if (!result.allowed) {
+            throw new OverLimitError(this.name, {
+                retryAfter: result.retryAfter,
+                current: result.current,
+                limit: result.limit,
+            });
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            await this.release();
+        }
+    }
+}

package/dist/limiter/bucket.d.ts

@@ -0,0 +1,15 @@
+import { BaseLimiter } from "./base.js";
+import type { AcquireResult, BucketLimiterOptions, RedisProvider, TimeInterval } from "./types.js";
+/**
+ * Limits operations per time boundary (e.g., 100 per minute).
+ * Resets at fixed time boundaries (start of minute, hour, etc).
+ */
+export declare class BucketLimiter extends BaseLimiter {
+    private readonly maxCount;
+    private readonly intervalSeconds;
+    constructor(name: string, maxCount: number, interval: TimeInterval | number, options?: BucketLimiterOptions, redisProvider?: RedisProvider);
+    private getBucketTimestamp;
+    protected tryAcquire(): Promise<AcquireResult>;
+    check(): Promise<AcquireResult>;
+}
+//# sourceMappingURL=bucket.d.ts.map

package/dist/limiter/bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../../src/limiter/bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AASpB;;;GAGG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAGvC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,OAAO,GAAE,oBAAyB,EAClC,aAAa,CAAC,EAAE,aAAa;IAQ/B,OAAO,CAAC,kBAAkB;cAOV,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IA8B9C,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;CAYtC"}

package/dist/limiter/bucket.js

@@ -0,0 +1,61 @@
+import { BaseLimiter } from "./base.js";
+import { LUA_BUCKET_ACQUIRE } from "./lua-scripts.js";
+const INTERVAL_SECONDS = {
+    second: 1,
+    minute: 60,
+    hour: 3600,
+    day: 86_400,
+};
+/**
+ * Limits operations per time boundary (e.g., 100 per minute).
+ * Resets at fixed time boundaries (start of minute, hour, etc).
+ */
+export class BucketLimiter extends BaseLimiter {
+    maxCount;
+    intervalSeconds;
+    constructor(name, maxCount, interval, options = {}, redisProvider) {
+        super(name, options, redisProvider);
+        this.maxCount = maxCount;
+        this.intervalSeconds =
+            typeof interval === "number" ? interval : INTERVAL_SECONDS[interval];
+    }
+    getBucketTimestamp() {
+        const now = Math.floor(Date.now() / 1000);
+        const bucketStart = Math.floor(now / this.intervalSeconds) * this.intervalSeconds;
+        return String(bucketStart);
+    }
+    async tryAcquire() {
+        const redis = await this.getRedis();
+        const bucketTs = this.getBucketTimestamp();
+        const result = (await redis.eval(LUA_BUCKET_ACQUIRE, {
+            keys: [this.redisKey],
+            arguments: [
+                String(this.maxCount),
+                bucketTs,
+                String(this.intervalSeconds + 1),
+            ],
+        }));
+        const [allowed, current] = result;
+        // Calculate actual retry time until next bucket
+        const now = Date.now() / 1000;
+        const bucketEnd = Math.floor(now / this.intervalSeconds) * this.intervalSeconds +
+            this.intervalSeconds;
+        const actualRetry = bucketEnd - now;
+        return {
+            allowed: allowed === 1,
+            current,
+            limit: this.maxCount,
+            retryAfter: allowed === 0 ? actualRetry : undefined,
+        };
+    }
+    async check() {
+        const redis = await this.getRedis();
+        const bucketTs = this.getBucketTimestamp();
+        const current = Number(await redis.hGet(this.redisKey, bucketTs)) || 0;
+        return {
+            allowed: current < this.maxCount,
+            current,
+            limit: this.maxCount,
+        };
+    }
+}

package/dist/limiter/concurrent.d.ts

@@ -0,0 +1,17 @@
+import { BaseLimiter } from "./base.js";
+import type { AcquireResult, ConcurrentLimiterOptions, RedisProvider } from "./types.js";
+/**
+ * Limits concurrent executions across all processes.
+ * Uses Redis ZSET with expiring locks for distributed mutex behavior.
+ */
+export declare class ConcurrentLimiter extends BaseLimiter {
+    private readonly maxConcurrent;
+    private readonly lockTimeout;
+    private currentLockId?;
+    constructor(name: string, maxConcurrent: number, options?: ConcurrentLimiterOptions, redisProvider?: RedisProvider);
+    private generateLockId;
+    protected tryAcquire(): Promise<AcquireResult>;
+    protected release(): Promise<void>;
+    check(): Promise<AcquireResult>;
+}
+//# sourceMappingURL=concurrent.d.ts.map

package/dist/limiter/concurrent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrent.d.ts","sourceRoot":"","sources":["../../src/limiter/concurrent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAKxC,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,aAAa,CAAC,CAAS;gBAG7B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,wBAA6B,EACtC,aAAa,CAAC,EAAE,aAAa;IAO/B,OAAO,CAAC,cAAc;cAIN,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;cA6BpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAalC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;CActC"}

package/dist/limiter/concurrent.js

@@ -0,0 +1,66 @@
+import { BaseLimiter } from "./base.js";
+import { LUA_CONCURRENT_ACQUIRE, LUA_CONCURRENT_RELEASE, } from "./lua-scripts.js";
+/**
+ * Limits concurrent executions across all processes.
+ * Uses Redis ZSET with expiring locks for distributed mutex behavior.
+ */
+export class ConcurrentLimiter extends BaseLimiter {
+    maxConcurrent;
+    lockTimeout;
+    currentLockId;
+    constructor(name, maxConcurrent, options = {}, redisProvider) {
+        super(name, options, redisProvider);
+        this.maxConcurrent = maxConcurrent;
+        this.lockTimeout = options.lockTimeout ?? 180;
+    }
+    generateLockId() {
+        return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+    async tryAcquire() {
+        const redis = await this.getRedis();
+        const lockId = this.generateLockId();
+        const now = Date.now() / 1000;
+        const result = (await redis.eval(LUA_CONCURRENT_ACQUIRE, {
+            keys: [this.redisKey],
+            arguments: [
+                String(this.maxConcurrent),
+                lockId,
+                String(now),
+                String(this.lockTimeout),
+            ],
+        }));
+        const [allowed, current, retryAfter] = result;
+        if (allowed === 1) {
+            this.currentLockId = lockId;
+        }
+        return {
+            allowed: allowed === 1,
+            current,
+            limit: this.maxConcurrent,
+            retryAfter: retryAfter > 0 ? retryAfter : undefined,
+        };
+    }
+    async release() {
+        if (!this.currentLockId) {
+            return;
+        }
+        const redis = await this.getRedis();
+        await redis.eval(LUA_CONCURRENT_RELEASE, {
+            keys: [this.redisKey],
+            arguments: [this.currentLockId],
+        });
+        this.currentLockId = undefined;
+    }
+    async check() {
+        const redis = await this.getRedis();
+        const now = Date.now() / 1000;
+        // Remove expired and count without acquiring
+        await redis.zRemRangeByScore(this.redisKey, "-inf", String(now));
+        const current = await redis.zCard(this.redisKey);
+        return {
+            allowed: current < this.maxConcurrent,
+            current,
+            limit: this.maxConcurrent,
+        };
+    }
+}

package/dist/limiter/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a rate limit is exceeded.
+ * Can be caught by RateLimitMiddleware to reschedule jobs.
+ */
+export declare class OverLimitError extends Error {
+    readonly limiterName: string;
+    readonly retryAfter?: number;
+    readonly current?: number;
+    readonly limit?: number;
+    constructor(limiterName: string, options?: {
+        retryAfter?: number;
+        current?: number;
+        limit?: number;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/limiter/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/limiter/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAGtB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;CAStE"}

package/dist/limiter/errors.js

@@ -0,0 +1,18 @@
+/**
+ * Thrown when a rate limit is exceeded.
+ * Can be caught by RateLimitMiddleware to reschedule jobs.
+ */
+export class OverLimitError extends Error {
+    limiterName;
+    retryAfter;
+    current;
+    limit;
+    constructor(limiterName, options) {
+        super(`Rate limit exceeded for limiter: ${limiterName}`);
+        this.name = "OverLimitError";
+        this.limiterName = limiterName;
+        this.retryAfter = options?.retryAfter;
+        this.current = options?.current;
+        this.limit = options?.limit;
+    }
+}

package/dist/limiter/index.d.ts

@@ -0,0 +1,69 @@
+import type { BucketLimiterOptions, ConcurrentLimiterOptions, ILimiter, RedisProvider, TimeInterval, WindowLimiterOptions } from "./types.js";
+export { BucketLimiter } from "./bucket.js";
+export { ConcurrentLimiter } from "./concurrent.js";
+export * from "./errors.js";
+export { ensureRateLimitMiddleware, RateLimitMiddleware, } from "./middleware.js";
+export * from "./types.js";
+export { WindowLimiter } from "./window.js";
+/**
+ * Factory class for creating rate limiters.
+ * Provides a Sidekiq Enterprise-compatible API.
+ *
+ * @example
+ * ```typescript
+ * import { Limiter } from "sidekiq-ts";
+ *
+ * // Limit concurrent API calls to 50
+ * const apiLimiter = Limiter.concurrent("external-api", 50);
+ *
+ * // Limit to 100 emails per minute
+ * const emailLimiter = Limiter.bucket("email-send", 100, "minute");
+ *
+ * // Limit to 1000 requests per hour (rolling window)
+ * const rateLimiter = Limiter.window("api-requests", 1000, "hour");
+ *
+ * // Use in a job
+ * class ApiCallJob extends Job<[string]> {
+ *   async perform(endpoint: string) {
+ *     await apiLimiter.withinLimit(async () => {
+ *       await fetch(endpoint);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class Limiter {
+    /**
+     * Create a concurrent limiter (distributed mutex with count).
+     * Limits concurrent executions across all processes.
+     *
+     * @param name - Unique identifier for the limiter
+     * @param maxCount - Maximum concurrent operations allowed
+     * @param options - Additional options (lockTimeout, keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static concurrent(name: string, maxCount: number, options?: ConcurrentLimiterOptions, redisProvider?: RedisProvider): ILimiter;
+    /**
+     * Create a bucket limiter (count per time boundary).
+     * Resets at fixed time boundaries (start of minute, hour, etc).
+     *
+     * @param name - Unique identifier for the limiter
+     * @param count - Operations allowed per interval
+     * @param interval - Time interval ("second", "minute", "hour", "day") or seconds
+     * @param options - Additional options (keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static bucket(name: string, count: number, interval: TimeInterval | number, options?: BucketLimiterOptions, redisProvider?: RedisProvider): ILimiter;
+    /**
+     * Create a window limiter (rolling window).
+     * Window starts from first operation and slides continuously.
+     *
+     * @param name - Unique identifier for the limiter
+     * @param count - Operations allowed within window
+     * @param interval - Window size ("second", "minute", "hour", "day") or seconds
+     * @param options - Additional options (keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static window(name: string, count: number, interval: TimeInterval | number, options?: WindowLimiterOptions, redisProvider?: RedisProvider): ILimiter;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/limiter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/limiter/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EACxB,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qBAAa,OAAO;IAClB;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,QAAQ;IAIX;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,OAAO,CAAC,EAAE,oBAAoB,EAC9B,aAAa,CAAC,EAAE,aAAa,GAC5B,QAAQ;IAIX;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,OAAO,CAAC,EAAE,oBAAoB,EAC9B,aAAa,CAAC,EAAE,aAAa,GAC5B,QAAQ;CAGZ"}

package/dist/limiter/index.js

@@ -0,0 +1,77 @@
+import { BucketLimiter } from "./bucket.js";
+import { ConcurrentLimiter } from "./concurrent.js";
+import { WindowLimiter } from "./window.js";
+export { BucketLimiter } from "./bucket.js";
+export { ConcurrentLimiter } from "./concurrent.js";
+export * from "./errors.js";
+export { ensureRateLimitMiddleware, RateLimitMiddleware, } from "./middleware.js";
+export * from "./types.js";
+export { WindowLimiter } from "./window.js";
+/**
+ * Factory class for creating rate limiters.
+ * Provides a Sidekiq Enterprise-compatible API.
+ *
+ * @example
+ * ```typescript
+ * import { Limiter } from "sidekiq-ts";
+ *
+ * // Limit concurrent API calls to 50
+ * const apiLimiter = Limiter.concurrent("external-api", 50);
+ *
+ * // Limit to 100 emails per minute
+ * const emailLimiter = Limiter.bucket("email-send", 100, "minute");
+ *
+ * // Limit to 1000 requests per hour (rolling window)
+ * const rateLimiter = Limiter.window("api-requests", 1000, "hour");
+ *
+ * // Use in a job
+ * class ApiCallJob extends Job<[string]> {
+ *   async perform(endpoint: string) {
+ *     await apiLimiter.withinLimit(async () => {
+ *       await fetch(endpoint);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/complexity/noStaticOnlyClass: Factory class provides namespace for limiter creation
+export class Limiter {
+    /**
+     * Create a concurrent limiter (distributed mutex with count).
+     * Limits concurrent executions across all processes.
+     *
+     * @param name - Unique identifier for the limiter
+     * @param maxCount - Maximum concurrent operations allowed
+     * @param options - Additional options (lockTimeout, keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static concurrent(name, maxCount, options, redisProvider) {
+        return new ConcurrentLimiter(name, maxCount, options, redisProvider);
+    }
+    /**
+     * Create a bucket limiter (count per time boundary).
+     * Resets at fixed time boundaries (start of minute, hour, etc).
+     *
+     * @param name - Unique identifier for the limiter
+     * @param count - Operations allowed per interval
+     * @param interval - Time interval ("second", "minute", "hour", "day") or seconds
+     * @param options - Additional options (keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static bucket(name, count, interval, options, redisProvider) {
+        return new BucketLimiter(name, count, interval, options, redisProvider);
+    }
+    /**
+     * Create a window limiter (rolling window).
+     * Window starts from first operation and slides continuously.
+     *
+     * @param name - Unique identifier for the limiter
+     * @param count - Operations allowed within window
+     * @param interval - Window size ("second", "minute", "hour", "day") or seconds
+     * @param options - Additional options (keyPrefix)
+     * @param redisProvider - Optional custom Redis provider
+     */
+    static window(name, count, interval, options, redisProvider) {
+        return new WindowLimiter(name, count, interval, options, redisProvider);
+    }
+}

package/dist/limiter/lua-scripts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ConcurrentLimiter: Acquire a slot with expiring lock
+ * KEYS[1] = limiter key (ZSET of lockId -> expireTime)
+ * ARGV[1] = max concurrent
+ * ARGV[2] = lock ID (unique per request)
+ * ARGV[3] = current time (seconds)
+ * ARGV[4] = lock timeout (seconds)
+ * Returns: [allowed (0/1), current count, retry_after]
+ */
+export declare const LUA_CONCURRENT_ACQUIRE = "\nlocal key = KEYS[1]\nlocal max_concurrent = tonumber(ARGV[1])\nlocal lock_id = ARGV[2]\nlocal now = tonumber(ARGV[3])\nlocal lock_timeout = tonumber(ARGV[4])\n\n-- Remove expired locks\nredis.call(\"ZREMRANGEBYSCORE\", key, \"-inf\", now)\n\n-- Check current count\nlocal current = redis.call(\"ZCARD\", key)\nif current < max_concurrent then\n  -- Add lock with expiration time as score\n  local expire_at = now + lock_timeout\n  redis.call(\"ZADD\", key, expire_at, lock_id)\n  redis.call(\"EXPIRE\", key, lock_timeout + 10)\n  return {1, current + 1, 0}\nend\n\n-- Get time until next slot frees up\nlocal oldest = redis.call(\"ZRANGE\", key, 0, 0, \"WITHSCORES\")\nlocal retry_after = 0\nif oldest[2] then\n  retry_after = math.max(0, tonumber(oldest[2]) - now)\nend\nreturn {0, current, retry_after}\n";
+/**
+ * ConcurrentLimiter: Release a lock
+ * KEYS[1] = limiter key
+ * ARGV[1] = lock ID
+ */
+export declare const LUA_CONCURRENT_RELEASE = "\nredis.call(\"ZREM\", KEYS[1], ARGV[1])\nreturn 1\n";
+/**
+ * BucketLimiter: Increment counter at time boundary
+ * KEYS[1] = limiter key
+ * ARGV[1] = max count
+ * ARGV[2] = current bucket timestamp (boundary)
+ * ARGV[3] = TTL seconds
+ * Returns: [allowed (0/1), current count, seconds until reset]
+ */
+export declare const LUA_BUCKET_ACQUIRE = "\nlocal key = KEYS[1]\nlocal max_count = tonumber(ARGV[1])\nlocal bucket_ts = ARGV[2]\nlocal ttl = tonumber(ARGV[3])\n\n-- Use hash: field is bucket timestamp, value is count\nlocal current = tonumber(redis.call(\"HGET\", key, bucket_ts) or \"0\")\n\nif current < max_count then\n  redis.call(\"HINCRBY\", key, bucket_ts, 1)\n  redis.call(\"EXPIRE\", key, ttl)\n  -- Clean old buckets\n  local fields = redis.call(\"HKEYS\", key)\n  for _, f in ipairs(fields) do\n    if f ~= bucket_ts then\n      redis.call(\"HDEL\", key, f)\n    end\n  end\n  return {1, current + 1, 0}\nend\n\nreturn {0, current, ttl}\n";
+/**
+ * WindowLimiter: Sliding window using sorted set
+ * KEYS[1] = limiter key (ZSET of request timestamps)
+ * ARGV[1] = max count
+ * ARGV[2] = window size (seconds)
+ * ARGV[3] = current time (seconds, with decimals)
+ * ARGV[4] = request ID (unique)
+ * Returns: [allowed (0/1), current count, retry_after]
+ */
+export declare const LUA_WINDOW_ACQUIRE = "\nlocal key = KEYS[1]\nlocal max_count = tonumber(ARGV[1])\nlocal window_size = tonumber(ARGV[2])\nlocal now = tonumber(ARGV[3])\nlocal request_id = ARGV[4]\n\nlocal window_start = now - window_size\n\n-- Remove entries outside window\nredis.call(\"ZREMRANGEBYSCORE\", key, \"-inf\", window_start)\n\n-- Count entries in window\nlocal current = redis.call(\"ZCARD\", key)\n\nif current < max_count then\n  redis.call(\"ZADD\", key, now, request_id)\n  redis.call(\"EXPIRE\", key, math.ceil(window_size) + 1)\n  return {1, current + 1, 0}\nend\n\n-- Calculate retry_after based on oldest entry\nlocal oldest = redis.call(\"ZRANGE\", key, 0, 0, \"WITHSCORES\")\nlocal retry_after = 0\nif oldest[2] then\n  retry_after = math.max(0, (tonumber(oldest[2]) + window_size) - now)\nend\nreturn {0, current, retry_after}\n";
+//# sourceMappingURL=lua-scripts.d.ts.map

package/dist/limiter/lua-scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lua-scripts.d.ts","sourceRoot":"","sources":["../../src/limiter/lua-scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,6yBA2BlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,yDAGlC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,omBAuB9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,kzBA4B9B,CAAC"}

package/dist/limiter/lua-scripts.js

@@ -0,0 +1,116 @@
+/**
+ * ConcurrentLimiter: Acquire a slot with expiring lock
+ * KEYS[1] = limiter key (ZSET of lockId -> expireTime)
+ * ARGV[1] = max concurrent
+ * ARGV[2] = lock ID (unique per request)
+ * ARGV[3] = current time (seconds)
+ * ARGV[4] = lock timeout (seconds)
+ * Returns: [allowed (0/1), current count, retry_after]
+ */
+export const LUA_CONCURRENT_ACQUIRE = `
+local key = KEYS[1]
+local max_concurrent = tonumber(ARGV[1])
+local lock_id = ARGV[2]
+local now = tonumber(ARGV[3])
+local lock_timeout = tonumber(ARGV[4])
+
+-- Remove expired locks
+redis.call("ZREMRANGEBYSCORE", key, "-inf", now)
+
+-- Check current count
+local current = redis.call("ZCARD", key)
+if current < max_concurrent then
+  -- Add lock with expiration time as score
+  local expire_at = now + lock_timeout
+  redis.call("ZADD", key, expire_at, lock_id)
+  redis.call("EXPIRE", key, lock_timeout + 10)
+  return {1, current + 1, 0}
+end
+
+-- Get time until next slot frees up
+local oldest = redis.call("ZRANGE", key, 0, 0, "WITHSCORES")
+local retry_after = 0
+if oldest[2] then
+  retry_after = math.max(0, tonumber(oldest[2]) - now)
+end
+return {0, current, retry_after}
+`;
+/**
+ * ConcurrentLimiter: Release a lock
+ * KEYS[1] = limiter key
+ * ARGV[1] = lock ID
+ */
+export const LUA_CONCURRENT_RELEASE = `
+redis.call("ZREM", KEYS[1], ARGV[1])
+return 1
+`;
+/**
+ * BucketLimiter: Increment counter at time boundary
+ * KEYS[1] = limiter key
+ * ARGV[1] = max count
+ * ARGV[2] = current bucket timestamp (boundary)
+ * ARGV[3] = TTL seconds
+ * Returns: [allowed (0/1), current count, seconds until reset]
+ */
+export const LUA_BUCKET_ACQUIRE = `
+local key = KEYS[1]
+local max_count = tonumber(ARGV[1])
+local bucket_ts = ARGV[2]
+local ttl = tonumber(ARGV[3])
+
+-- Use hash: field is bucket timestamp, value is count
+local current = tonumber(redis.call("HGET", key, bucket_ts) or "0")
+
+if current < max_count then
+  redis.call("HINCRBY", key, bucket_ts, 1)
+  redis.call("EXPIRE", key, ttl)
+  -- Clean old buckets
+  local fields = redis.call("HKEYS", key)
+  for _, f in ipairs(fields) do
+    if f ~= bucket_ts then
+      redis.call("HDEL", key, f)
+    end
+  end
+  return {1, current + 1, 0}
+end
+
+return {0, current, ttl}
+`;
+/**
+ * WindowLimiter: Sliding window using sorted set
+ * KEYS[1] = limiter key (ZSET of request timestamps)
+ * ARGV[1] = max count
+ * ARGV[2] = window size (seconds)
+ * ARGV[3] = current time (seconds, with decimals)
+ * ARGV[4] = request ID (unique)
+ * Returns: [allowed (0/1), current count, retry_after]
+ */
+export const LUA_WINDOW_ACQUIRE = `
+local key = KEYS[1]
+local max_count = tonumber(ARGV[1])
+local window_size = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local request_id = ARGV[4]
+
+local window_start = now - window_size
+
+-- Remove entries outside window
+redis.call("ZREMRANGEBYSCORE", key, "-inf", window_start)
+
+-- Count entries in window
+local current = redis.call("ZCARD", key)
+
+if current < max_count then
+  redis.call("ZADD", key, now, request_id)
+  redis.call("EXPIRE", key, math.ceil(window_size) + 1)
+  return {1, current + 1, 0}
+end
+
+-- Calculate retry_after based on oldest entry
+local oldest = redis.call("ZRANGE", key, 0, 0, "WITHSCORES")
+local retry_after = 0
+if oldest[2] then
+  retry_after = math.max(0, (tonumber(oldest[2]) + window_size) - now)
+end
+return {0, current, retry_after}
+`;

package/dist/limiter/middleware.d.ts

@@ -0,0 +1,21 @@
+import type { Config } from "../config.js";
+import type { JobPayload } from "../types.js";
+/**
+ * Server middleware that catches OverLimitError and reschedules jobs.
+ * Follows Sidekiq Enterprise behavior:
+ * - Linear backoff starting at ~5 minutes
+ * - Maximum 20 reschedules (~1 day total)
+ * - After max reschedules, job fails normally
+ */
+export declare class RateLimitMiddleware {
+    config?: Config;
+    call(_instance: unknown, payload: JobPayload, _queue: string, next: () => Promise<unknown> | unknown): Promise<unknown>;
+    private handleOverLimit;
+    private calculateBackoff;
+}
+/**
+ * Ensures the RateLimitMiddleware is registered.
+ * Call this in your configuration if using rate limiters in jobs.
+ */
+export declare const ensureRateLimitMiddleware: (config: Config) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/limiter/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/limiter/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAS9C;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAEV,IAAI,CACR,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GACrC,OAAO,CAAC,OAAO,CAAC;YAWL,eAAe;IA8B7B,OAAO,CAAC,gBAAgB;CASzB;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,IAI1D,CAAC"}

package/dist/limiter/middleware.js

@@ -0,0 +1,62 @@
+import { dumpJson } from "../json.js";
+import { OverLimitError } from "./errors.js";
+/** Maximum number of times a job can be rescheduled due to rate limiting */
+const MAX_OVERRATED = 20;
+/** Base delay in seconds for rate limit reschedule (5 minutes) */
+const BASE_DELAY_SECONDS = 300;
+/**
+ * Server middleware that catches OverLimitError and reschedules jobs.
+ * Follows Sidekiq Enterprise behavior:
+ * - Linear backoff starting at ~5 minutes
+ * - Maximum 20 reschedules (~1 day total)
+ * - After max reschedules, job fails normally
+ */
+export class RateLimitMiddleware {
+    config;
+    async call(_instance, payload, _queue, next) {
+        try {
+            return await next();
+        }
+        catch (error) {
+            if (error instanceof OverLimitError) {
+                return this.handleOverLimit(payload, error);
+            }
+            throw error;
+        }
+    }
+    async handleOverLimit(payload, error) {
+        const overrated = (payload.overrated ?? 0) + 1;
+        payload.overrated = overrated;
+        if (overrated > MAX_OVERRATED) {
+            // Exceeded max reschedules, let it fail normally
+            throw error;
+        }
+        // Calculate backoff: linear ~5 min + jitter
+        const delay = this.calculateBackoff(overrated, error.retryAfter);
+        const retryAt = Date.now() / 1000 + delay;
+        // Add to retry queue
+        const redis = await this.config?.getRedisClient();
+        if (!redis) {
+            throw error;
+        }
+        await redis.zAdd("retry", [{ score: retryAt, value: dumpJson(payload) }]);
+        this.config?.logger.debug(() => `Rate limited: ${error.limiterName}, rescheduled in ${Math.round(delay)}s (attempt ${overrated}/${MAX_OVERRATED})`);
+    }
+    calculateBackoff(overrated, retryAfter) {
+        // Use limiter's retryAfter if available and reasonable
+        if (retryAfter !== undefined && retryAfter > 0 && retryAfter < 3600) {
+            return retryAfter + Math.random() * 30;
+        }
+        // Linear backoff: 5 min * attempt + jitter
+        return BASE_DELAY_SECONDS * overrated + Math.random() * BASE_DELAY_SECONDS;
+    }
+}
+/**
+ * Ensures the RateLimitMiddleware is registered.
+ * Call this in your configuration if using rate limiters in jobs.
+ */
+export const ensureRateLimitMiddleware = (config) => {
+    if (!config.serverMiddleware.exists(RateLimitMiddleware)) {
+        config.serverMiddleware.add(RateLimitMiddleware);
+    }
+};

package/dist/limiter/types.d.ts

@@ -0,0 +1,42 @@
+import type { RedisClient } from "../redis.js";
+/** Time intervals for bucket and window limiters */
+export type TimeInterval = "second" | "minute" | "hour" | "day";
+/** Result of an acquire attempt */
+export interface AcquireResult {
+    allowed: boolean;
+    /** Seconds until the limit resets */
+    retryAfter?: number;
+    /** Current usage count */
+    current?: number;
+    /** Maximum allowed */
+    limit?: number;
+}
+/** Common options for all limiters */
+export interface LimiterOptions {
+    /** Custom Redis key prefix. Default: 'limiter' */
+    keyPrefix?: string;
+}
+/** Options for ConcurrentLimiter */
+export interface ConcurrentLimiterOptions extends LimiterOptions {
+    /** How long a lock is held before auto-release (seconds). Default: 180 */
+    lockTimeout?: number;
+}
+/** Options for BucketLimiter */
+export interface BucketLimiterOptions extends LimiterOptions {
+}
+/** Options for WindowLimiter */
+export interface WindowLimiterOptions extends LimiterOptions {
+}
+/** The limiter interface - all limiters implement this */
+export interface ILimiter {
+    readonly name: string;
+    /** Execute callback within rate limit. Throws OverLimitError if limit exceeded. */
+    withinLimit<T>(fn: () => Promise<T> | T): Promise<T>;
+    /** Check current limit status without consuming */
+    check(): Promise<AcquireResult>;
+    /** Reset the limiter state */
+    reset(): Promise<void>;
+}
+/** Redis connection provider function */
+export type RedisProvider = () => Promise<RedisClient>;
+//# sourceMappingURL=types.d.ts.map

package/dist/limiter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/limiter/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,oDAAoD;AACpD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEhE,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,gCAAgC;AAChC,MAAM,WAAW,oBAAqB,SAAQ,cAAc;CAAG;AAE/D,gCAAgC;AAChC,MAAM,WAAW,oBAAqB,SAAQ,cAAc;CAAG;AAE/D,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mFAAmF;IACnF,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAErD,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAEhC,8BAA8B;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC"}

package/dist/limiter/types.js

@@ -0,0 +1 @@
+export {};

package/dist/limiter/window.d.ts

@@ -0,0 +1,15 @@
+import { BaseLimiter } from "./base.js";
+import type { AcquireResult, RedisProvider, TimeInterval, WindowLimiterOptions } from "./types.js";
+/**
+ * Limits operations within a rolling time window.
+ * Window starts from first operation and slides continuously.
+ */
+export declare class WindowLimiter extends BaseLimiter {
+    private readonly maxCount;
+    private readonly windowSeconds;
+    constructor(name: string, maxCount: number, interval: TimeInterval | number, options?: WindowLimiterOptions, redisProvider?: RedisProvider);
+    private generateRequestId;
+    protected tryAcquire(): Promise<AcquireResult>;
+    check(): Promise<AcquireResult>;
+}
+//# sourceMappingURL=window.d.ts.map

package/dist/limiter/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../src/limiter/window.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,oBAAoB,EACrB,MAAM,YAAY,CAAC;AASpB;;;GAGG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAGrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,OAAO,GAAE,oBAAyB,EAClC,aAAa,CAAC,EAAE,aAAa;IAQ/B,OAAO,CAAC,iBAAiB;cAIT,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IAyB9C,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;CAetC"}

package/dist/limiter/window.js

@@ -0,0 +1,59 @@
+import { BaseLimiter } from "./base.js";
+import { LUA_WINDOW_ACQUIRE } from "./lua-scripts.js";
+const INTERVAL_SECONDS = {
+    second: 1,
+    minute: 60,
+    hour: 3600,
+    day: 86_400,
+};
+/**
+ * Limits operations within a rolling time window.
+ * Window starts from first operation and slides continuously.
+ */
+export class WindowLimiter extends BaseLimiter {
+    maxCount;
+    windowSeconds;
+    constructor(name, maxCount, interval, options = {}, redisProvider) {
+        super(name, options, redisProvider);
+        this.maxCount = maxCount;
+        this.windowSeconds =
+            typeof interval === "number" ? interval : INTERVAL_SECONDS[interval];
+    }
+    generateRequestId() {
+        return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+    async tryAcquire() {
+        const redis = await this.getRedis();
+        const now = Date.now() / 1000;
+        const requestId = this.generateRequestId();
+        const result = (await redis.eval(LUA_WINDOW_ACQUIRE, {
+            keys: [this.redisKey],
+            arguments: [
+                String(this.maxCount),
+                String(this.windowSeconds),
+                String(now),
+                requestId,
+            ],
+        }));
+        const [allowed, current, retryAfter] = result;
+        return {
+            allowed: allowed === 1,
+            current,
+            limit: this.maxCount,
+            retryAfter: retryAfter > 0 ? retryAfter : undefined,
+        };
+    }
+    async check() {
+        const redis = await this.getRedis();
+        const now = Date.now() / 1000;
+        const windowStart = now - this.windowSeconds;
+        // Remove expired entries and count
+        await redis.zRemRangeByScore(this.redisKey, "-inf", String(windowStart));
+        const current = await redis.zCard(this.redisKey);
+        return {
+            allowed: current < this.maxCount,
+            current,
+            limit: this.maxCount,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekiq-ts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TypeScript client for Sidekiq job processing",
   "license": "MIT",
   "keywords": [