@stacksjs/bun-queue 0.0.1

package/dist/jobs/middleware.d.ts

@@ -0,0 +1,37 @@
+import type { JobMiddleware } from '../job-base';
+// Job middleware factory
+export declare const Middleware: {
+  rateLimited: (key: string, maxAttempts: number, decaySeconds?: number) => any;
+  withoutOverlapping: (key?: string, releaseAfterSeconds?: number, expireAfterSeconds?: number) => any;
+  skipIfBatchCancelled: () => any;
+  throttlesExceptions: (maxAttempts?: number, decaySeconds?: number, by?: (job: Job) => string) => any
+};
+export declare class RateLimited implements JobMiddleware {
+  private key: string;
+  private maxAttempts: number;
+  private decaySeconds?: number;
+  constructor(key: string, maxAttempts: number, decaySeconds?: number);
+  handle(job: Job, next: () => Promise<void>): Promise<void>;
+  static by(key: string, maxAttempts: number, decaySeconds?: number): RateLimited;
+}
+export declare class WithoutOverlapping implements JobMiddleware {
+  private key?: string;
+  private releaseAfterSeconds?: number;
+  private expireAfterSeconds?: number;
+  constructor(key?: string, releaseAfterSeconds?: number, expireAfterSeconds?: number);
+  handle(job: Job, next: () => Promise<void>): Promise<void>;
+  static by(key: string): WithoutOverlapping;
+  releaseAfter(seconds: number): this;
+  expireAfter(seconds: number): this;
+}
+export declare class SkipIfBatchCancelled implements JobMiddleware {
+  handle(job: Job, next: () => Promise<void>): Promise<void>;
+}
+export declare class ThrottlesExceptions implements JobMiddleware {
+  private maxAttempts?: number;
+  private decaySeconds?: number;
+  private by?: (job: Job) => string;
+  constructor(maxAttempts?: number, decaySeconds?: number, by?: (job: Job) => string);
+  handle(job: Job, next: () => Promise<void>): Promise<void>;
+  static by(callback: (job: Job) => string, maxAttempts?: number, decaySeconds?: number): ThrottlesExceptions;
+}

package/dist/leader-election.d.ts

@@ -0,0 +1,39 @@
+import type { RedisClient } from 'bun';
+export declare interface LeaderElectionOptions {
+  keyPrefix?: string
+  heartbeatInterval?: number
+  leaderTimeout?: number
+  onBecomeLeader?: () => void
+  onLeadershipLost?: () => void
+  onLeaderChanged?: (leaderId: string) => void
+  instanceId?: string
+}
+/**
+ * Implements leader election for distributed queue instances
+ * using Redis for coordination
+ */
+export declare class LeaderElection {
+  readonly private redisClient: RedisClient;
+  readonly private keyPrefix: string;
+  readonly private instanceId: string;
+  readonly private logger: any;
+  readonly private heartbeatInterval: number;
+  readonly private leaderTimeout: number;
+  readonly private options: LeaderElectionOptions;
+  private heartbeatTimer: NodeJS.Timeout | null;
+  private watchdogTimer: NodeJS.Timeout | null;
+  private isLeader: any;
+  private currentLeaderId: string | null;
+  constructor(redisClient: RedisClient, options?: LeaderElectionOptions);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isCurrentLeader(): boolean;
+  getCurrentLeader(): Promise<string | null>;
+  private electLeader(): Promise<void>;
+  private becomeLeader(): void;
+  private startHeartbeat(): void;
+  private startWatchdog(): void;
+  private checkLeadership(): Promise<void>;
+  private loseLeadership(): void;
+  private stepDown(): Promise<void>;
+}

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+import type { LogLevel } from './types';
+export declare function createLogger(queueName?: string): Logger;
+export declare const logger: Logger;
+declare class Logger {
+  private level: LogLevel;
+  private queueName?: string;
+  constructor(queueName?: string);
+  setLevel(level: LogLevel): void;
+  private formatMessage(message: string): string;
+  debug(message: string, args: any[]): void;
+  info(message: string, args: any[]): void;
+  warn(message: string, args: any[]): void;
+  error(message: string, args: any[]): void;
+}

package/dist/metrics.d.ts

@@ -0,0 +1,22 @@
+import type { Queue } from './queue';
+export declare interface QueueMetrics {
+  completed: number[]
+  failed: number[]
+  delayed: number[]
+  active: number[]
+  waiting: number[]
+  added: number
+  processedRate: number
+}
+export declare class Metrics {
+  private queue: Queue;
+  private collectInterval: number;
+  private intervalId: number | null;
+  private metrics: QueueMetrics;
+  constructor(queue: Queue);
+  private startCollecting(): void;
+  stop(): void;
+  private collectMetrics(): Promise<void>;
+  trackJobAdded(): void;
+  getMetrics(): Promise<QueueMetrics>;
+}

package/dist/middleware.d.ts

@@ -0,0 +1,61 @@
+import type { JobContract, JobMiddleware } from './job-base';
+export declare const middleware: {
+  rateLimit: (maxAttempts: number, decayMinutes?: number, prefix?: string) => any;
+  unique: (ttl?: number) => any;
+  throttle: (allows: number, every: number, prefix?: string) => any;
+  withoutOverlapping: (ttl?: number, releaseAfter?: number) => any;
+  skipIf: (condition: () => boolean | Promise<boolean>) => any;
+  onFailure: (callback: (error: Error, job: JobContract) => Promise<void> | void) => any
+};
+export declare interface MiddlewareStack {
+  through: (middleware: JobMiddleware[]) => Promise<void>
+  then: (destination: () => Promise<void>) => Promise<void>
+}
+export declare class JobMiddlewareStack implements MiddlewareStack {
+  private job: JobContract;
+  private middlewares: JobMiddleware[];
+  private index: any;
+  constructor(job: JobContract, middlewares: JobMiddleware[]);
+  through(middleware: JobMiddleware[]): Promise<void>;
+  then(destination: () => Promise<void>): Promise<void>;
+  private executeMiddleware(destination: () => Promise<void>): Promise<void>;
+}
+export declare class RateLimitMiddleware implements JobMiddleware {
+  private maxAttempts: number;
+  private decayMinutes: number;
+  private prefix: string;
+  constructor(maxAttempts: number, decayMinutes?: number, prefix?: any);
+  handle(job: JobContract, next: () => Promise<void>): Promise<void>;
+  private getRateLimitKey(job: JobContract): string;
+}
+export declare class UniqueJobMiddleware implements JobMiddleware {
+  private ttl: number;
+  constructor(ttl?: number);
+  handle(job: JobContract, next: () => Promise<void>): Promise<void>;
+  private getUniqueKey(job: JobContract, uniqueId: string): string;
+}
+export declare class ThrottleMiddleware implements JobMiddleware {
+  private allows: number;
+  private every: number;
+  private prefix: string;
+  constructor(allows: number, every: number, prefix?: any);
+  handle(job: JobContract, next: () => Promise<void>): Promise<void>;
+  private getThrottleKey(job: JobContract): string;
+}
+export declare class WithoutOverlappingMiddleware implements JobMiddleware {
+  private ttl: number;
+  private releaseAfter: number;
+  constructor(ttl?: number, releaseAfter?: number);
+  handle(job: JobContract, next: () => Promise<void>): Promise<void>;
+  private getOverlapKey(job: JobContract): string;
+}
+export declare class SkipIfMiddleware implements JobMiddleware {
+  private condition: () => boolean | Promise<boolean>;
+  constructor(condition: () => boolean | Promise<boolean>);
+  handle(_job: JobContract, next: () => Promise<void>): Promise<void>;
+}
+export declare class FailureMiddleware implements JobMiddleware {
+  private callback: (error: Error, job: JobContract) => Promise<void> | void;
+  constructor(callback: (error: Error, job: JobContract) => Promise<void> | void);
+  handle(job: JobContract, next: () => Promise<void>): Promise<void>;
+}

package/dist/observable.d.ts

@@ -0,0 +1,23 @@
+import type { RedisClient } from 'bun';
+import type { Observable, ObservableOptions } from './types';
+import type { Queue } from './queue';
+export declare class QueueObservable {
+  readonly private redisClient: RedisClient;
+  readonly private queues: Map<string, Queue<any>>;
+  readonly private observables: Map<string, Observable>;
+  readonly private timers: Map<string, NodeJS.Timeout>;
+  readonly private prefix: string;
+  readonly private logger: any;
+  constructor(prefix: string, redisClient: RedisClient);
+  createObservable(queues: Queue<any>[], options?: ObservableOptions): Promise<Observable>;
+  startObservable(observableId: string): Promise<void>;
+  stopObservable(observableId: string): Promise<void>;
+  removeObservable(observableId: string): Promise<void>;
+  getAllObservables(): Promise<Observable[]>;
+  getObservable(observableId: string): Promise<Observable | null>;
+  private startMonitoring(observableId: string): void;
+  getObservableStats(observableId: string): Promise<Record<string, any> | null>;
+  closeAll(): Promise<void>;
+  private getObservableKey(observableId: string): string;
+  private getObservableStatsKey(observableId: string): string;
+}

package/dist/priority-queue.d.ts

@@ -0,0 +1,40 @@
+import type { RedisClient } from 'bun';
+import { Job } from './job';
+import { Queue } from './queue';
+import type { JobEvents } from './events';
+import type { JobOptions, JobStatus, PriorityLevel, PriorityQueueOptions, QueueConfig } from './types';
+/**
+ * PriorityQueue implements a queue with priority support
+ * It maintains separate priority queues and processes higher priority jobs first
+ */
+export declare class PriorityQueue<T = any> {
+  name: string;
+  prefix: string;
+  redisClient: RedisClient;
+  keyPrefix: string;
+  events: JobEvents;
+  readonly private baseQueue: Queue<T>;
+  readonly private priorityLevels: number;
+  readonly private defaultPriorityLevel: number;
+  readonly private dynamicReordering: boolean;
+  readonly private reorderInterval: number;
+  private reorderTimer: NodeJS.Timeout | null;
+  readonly private logger: any;
+  private jobMoverTimer: NodeJS.Timeout | null;
+  constructor(name: string, priorityOptions?: PriorityQueueOptions, queueOptions?: QueueConfig);
+  add(data: T, options?: JobOptions): Promise<Job<T>>;
+  process(concurrency: number, handler: (job: Job<T>) => Promise<any>): void;
+  close(): Promise<void>;
+  getJob(jobId: string): Promise<Job<T> | null>;
+  removeJob(jobId: string): Promise<void>;
+  getJobs(status: JobStatus, start?: any, end?: any): Promise<Job<T>[]>;
+  getJobCounts(): Promise<Record<JobStatus, number>>;
+  empty(): Promise<void>;
+  private moveJobsToWaiting(): Promise<void>;
+  private startJobMover(): void;
+  private reorderJobs(): Promise<void>;
+  private startDynamicReordering(): void;
+  getKey(name: string): string;
+  getJobKey(jobId: string): string;
+  private getPriorityKey(priority: PriorityLevel): string;
+}

package/dist/queue-manager.d.ts

@@ -0,0 +1,24 @@
+import { config } from './config';
+import type { QueueConnectionConfig, QueueManagerConfig } from './types';
+export declare function getQueueManager(config?: Partial<QueueManagerConfig>): QueueManager;
+export declare function setQueueManager(manager: QueueManager): void;
+export declare function closeQueueManager(): Promise<void>;
+export declare interface QueueConnection {
+  name: string
+  config: QueueConnectionConfig
+  queues: Map<string, QueueInstance<any>>
+  queue: <T = any>(name?: string) => QueueInstance<T>
+}
+export declare class QueueManager {
+  private connections: Map<string, QueueConnection>;
+  private config: QueueManagerConfig;
+  constructor(managerConfig?: Partial<QueueManagerConfig>);
+  connection(name?: string): QueueConnection;
+  queue<T = any>(name?: string): QueueInstance<T>;
+  closeAll(): Promise<void>;
+  getConnections(): string[];
+  addConnection(name: string, config: QueueConnectionConfig): void;
+  removeConnection(name: string): void;
+  setDefaultConnection(name: string): void;
+  getDefaultConnection(): string;
+}

package/dist/queue.d.ts

@@ -0,0 +1,114 @@
+import type { RedisClient } from 'bun';
+import { CleanupService } from './cleanup';
+import { createLogger } from './logger';
+import { CronScheduler } from './cron-scheduler';
+import { DeadLetterQueue } from './dead-letter-queue';
+import { DistributedLock } from './distributed-lock';
+import { Job } from './job';
+import { JobEvents } from './events';
+import { LeaderElection } from './leader-election';
+import { Metrics } from './metrics';
+import { RateLimiter } from './rate-limiter';
+import { StalledJobChecker } from './stalled-checker';
+import { WorkCoordinator } from './work-coordinator';
+import { Worker } from './worker';
+import type { CronJobOptions } from './cron-scheduler';
+import type { DeadLetterQueueOptions, JobOptions, JobStatus, QueueConfig, QueueConnectionConfig } from './types';
+import type { JobContract } from './job-base';
+import type { JobProcessor } from './job-processor';
+export declare class Queue<T = any> {
+  name: string;
+  prefix: string;
+  redisClient: RedisClient;
+  keyPrefix: string;
+  events: JobEvents;
+  private worker: Worker<T> | null;
+  private metrics: Metrics | null;
+  private cleanupService: CleanupService | null;
+  private stalledChecker: StalledJobChecker | null;
+  readonly protected logger: ReturnType<typeof createLogger>;
+  private limiter: RateLimiter | null;
+  private defaultJobOptions: JobOptions | undefined;
+  private lock: DistributedLock | null;
+  private cronScheduler: CronScheduler | null;
+  private deadLetterQueue: DeadLetterQueue<T> | null;
+  private defaultDeadLetterOptions: DeadLetterQueueOptions | undefined;
+  private leaderElection: LeaderElection | null;
+  private workCoordinator: WorkCoordinator | null;
+  private instanceId: string;
+  private horizontalScalingEnabled: boolean;
+  private jobProcessor: JobProcessor;
+  constructor(name: string, options?: QueueConnectionConfig);
+  private initializeHorizontalScaling(options: QueueConfig): void;
+  private handleBecomeLeader(): void;
+  private handleLeadershipLost(): void;
+  private handleLeaderChanged(leaderId: string): void;
+  private init(): Promise<void>;
+  add(data: T, options?: JobOptions): Promise<Job<T>>;
+  process(concurrency: number, handler: (job: Job<T>) => Promise<any>): void;
+  private startHorizontalScaling(concurrency: number, handler: (job: Job<T>) => Promise<any>): Promise<void>;
+  private startWorker(concurrency: number, handler: (job: Job<T>) => Promise<any>): void;
+  private _horizontalScalingInterval: NodeJS.Timeout | null;
+  close(): Promise<void>;
+  getInstanceId(): string;
+  getClusterInfo(): Promise<Record<string, any> | null>;
+  isLeader(): boolean;
+  getLeaderId(): Promise<string | null>;
+  getJob(jobId: string): Promise<Job<T> | null>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  removeJob(jobId: string): Promise<void>;
+  getMetrics(): Promise<any>;
+  getJobs(status: JobStatus, start?: any, end?: any): Promise<Job<T>[]>;
+  getJobCounts(): Promise<Record<JobStatus, number>>;
+  empty(): Promise<void>;
+  ping(): Promise<boolean>;
+  getKey(name: string): string;
+  getJobKey(jobId: string): string;
+  isRateLimited(key?: string, data?: T): Promise<{ limited: boolean, resetIn: number }>;
+  processJobWithLock(jobId: string, handler: (job: Job<T>) => Promise<any>): Promise<any>;
+  getLock(): DistributedLock | null;
+  scheduleCron(options: CronJobOptions): Promise<string>;
+  unscheduleCron(jobId: string): Promise<boolean>;
+  getDeadLetterQueue(): DeadLetterQueue<T>;
+  getDefaultDeadLetterOptions(): DeadLetterQueueOptions | undefined;
+  moveToDeadLetter(jobId: string, reason: string): Promise<boolean>;
+  getDeadLetterJobs(start?: any, end?: any): Promise<Job<T>[]>;
+  republishDeadLetterJob(jobId: string, options?: { resetRetries?: boolean }): Promise<Job<T> | null>;
+  removeDeadLetterJob(jobId: string): Promise<boolean>;
+  clearDeadLetterQueue(): Promise<void>;
+  bulkRemove(jobIds: string[]): Promise<number>;
+  bulkPause(jobIds: string[]): Promise<number>;
+  bulkResume(jobIds: string[]): Promise<number>;
+  dispatchJob(job: JobContract, args: any[]): Promise<Job<any>>;
+  processJobs(concurrency?: number): void;
+  addJobBatch(jobs: JobContract[], batchOptions?: {
+    batchId?: string
+    allowFailures?: boolean
+  }): Promise<Job<any>[]>;
+  retryJob(jobId: string, newArgs?: any[]): Promise<Job<any> | null>;
+  getFailedJobClasses(): Promise<Array<{
+    job: Job<any>
+    jobClass: string
+    error: string
+    failedAt: number
+  }>>;
+  getJobClassStats(): Promise<{
+    byClass: Record<string, {
+      total: number
+      completed: number
+      failed: number
+      pending: number
+    }>
+    overall: {
+      total: number
+      completed: number
+      failed: number
+      pending: number
+    }
+  }>;
+  private isJobClass(data: any): boolean;
+  clearJobClasses(): Promise<void>;
+  pauseJobClasses(): Promise<void>;
+  resumeJobClasses(): Promise<void>;
+}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,13 @@
+import type { Queue } from './queue';
+export declare interface RateLimitResult {
+  limited: boolean
+  remaining: number
+  resetIn: number
+}
+export declare class RateLimiter {
+  queue: Queue;
+  options: RateLimiterOptions;
+  constructor(queue: Queue, options: RateLimiterOptions);
+  check(data?: any): Promise<RateLimitResult>;
+  checkByKey(key: string): Promise<RateLimitResult>;
+}