@stacksjs/bun-queue 0.0.1

package/dist/stalled-checker.d.ts

@@ -0,0 +1,14 @@
+import type { Queue } from './queue';
+declare class StalledJobChecker {
+  readonly private queue: Queue;
+  readonly private logger: any;
+  private timer: NodeJS.Timeout | null;
+  private running: any;
+  readonly private interval: number;
+  readonly private maxRetries: number;
+  constructor(queue: Queue, interval?: number, maxRetries?: number);
+  start(): void;
+  stop(): void;
+  private checkStalledJobs(): Promise<void>;
+}
+export { StalledJobChecker };

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+import type { RedisClient } from 'bun';
+export type { RedisClient };
+export declare const DEFAULT_PRIORITY_LEVEL: 0;
+export declare const MAX_PRIORITY_LEVELS: 10;
+export declare interface QueueConfig {
+  verbose?: boolean
+  logLevel?: LogLevel
+  redis?: {
+    url?: string
+    client?: RedisClient
+  }
+  prefix?: string
+  defaultJobOptions?: JobOptions
+  limiter?: RateLimiter
+  metrics?: {
+    enabled: boolean
+    collectInterval?: number
+  }
+  stalledJobCheckInterval?: number
+  maxStalledJobRetries?: number
+  distributedLock?: boolean
+  defaultDeadLetterOptions?: DeadLetterQueueOptions
+  horizontalScaling?: {
+    enabled?: boolean
+    instanceId?: string
+    maxWorkersPerInstance?: number
+    jobsPerWorker?: number
+    leaderElection?: {
+      heartbeatInterval?: number
+      leaderTimeout?: number
+    }
+    workCoordination?: {
+      pollInterval?: number
+      keyPrefix?: string
+    }
+  }
+}
+export declare interface QueueManagerConfig {
+  default?: string
+  connections?: Record<string, QueueConnectionConfig>
+  failed?: {
+    driver: 'redis' | 'database'
+    table?: string
+    prefix?: string
+  }
+  batching?: {
+    driver: 'redis' | 'database'
+    table?: string
+    prefix?: string
+  }
+}
+export declare interface QueueConnectionConfig extends QueueConfig {
+  driver: 'redis' | 'memory' | 'database'
+  table?: string
+}
+export declare interface JobOptions {
+  delay?: number
+  attempts?: number
+  backoff?: {
+    type: 'fixed' | 'exponential'
+    delay: number
+  }
+  removeOnComplete?: boolean | number
+  removeOnFail?: boolean | number
+  priority?: number
+  lifo?: boolean
+  timeout?: number
+  jobId?: string
+  repeat?: {
+    every: number
+    limit?: number
+    count?: number
+    cron?: string
+    tz?: string
+    startDate?: Date | number
+    endDate?: Date | number
+  }
+  dependsOn?: string | string[]
+  keepJobs?: boolean
+  deadLetter?: boolean | DeadLetterQueueOptions
+}
+export declare interface RateLimiter {
+  max: number
+  duration: number
+  keyPrefix?: string | ((data: any) => string)
+}
+export declare interface Job<T = any> {
+  id: string
+  name: string
+  data: T
+  opts: JobOptions
+  progress: number
+  delay: number
+  timestamp: number
+  attemptsMade: number
+  stacktrace: string[]
+  returnvalue: any
+  finishedOn?: number
+  processedOn?: number
+  failedReason?: string
+  dependencies?: string[]
+}
+export declare interface QueueEvents {
+  jobAdded: (jobId: string, name: string) => void
+  jobRemoved: (jobId: string) => void
+  jobCompleted: (jobId: string, result: any) => void
+  jobFailed: (jobId: string, error: Error) => void
+  jobProgress: (jobId: string, progress: number) => void
+  jobActive: (jobId: string) => void
+  jobStalled: (jobId: string) => void
+  jobDelayed: (jobId: string, delay: number) => void
+  ready: () => void
+  error: (error: Error) => void
+  batchAdded: (batchId: string, jobIds: string[]) => void
+  batchCompleted: (batchId: string, results: any[]) => void
+  batchFailed: (batchId: string, errors: Error[]) => void
+  batchProgress: (batchId: string, progress: number) => void
+  groupCreated: (groupName: string) => void
+  groupRemoved: (groupName: string) => void
+  observableStarted: (observableId: string) => void
+  observableStopped: (observableId: string) => void
+  jobMovedToDeadLetter: (jobId: string, deadLetterQueueName: string, reason: string) => void
+  jobRepublishedFromDeadLetter: (jobId: string, originalQueueName: string) => void
+}
+// Batch processing types
+export declare interface BatchOptions extends JobOptions {
+  batchSize?: number
+  processTimeout?: number
+}
+export declare interface Batch<T = any> {
+  id: string
+  jobs: Job<T>[]
+  opts: BatchOptions
+  timestamp: number
+  status: JobStatus
+  processingAt?: number
+  finishedAt?: number
+}
+// Group types
+export declare interface GroupOptions {
+  name: string
+  limit?: number
+  maxConcurrency?: number
+}
+export declare interface Group {
+  name: string
+  limit: number
+  maxConcurrency: number
+  queues: string[]
+}
+// Observable types
+export declare interface ObservableOptions {
+  interval?: number
+  autoStart?: boolean
+}
+export declare interface Observable {
+  id: string
+  queues: string[]
+  interval: number
+  running: boolean
+}
+// Support 0-9 priority levels by default
+export declare interface PriorityQueueOptions {
+  levels?: number
+  defaultLevel?: number
+  dynamicReordering?: boolean
+  reorderInterval?: number
+}
+// Dead Letter Queue options
+export declare interface DeadLetterQueueOptions {
+  queueSuffix?: string
+  maxRetries?: number
+  processFailed?: boolean
+  removeFromOriginalQueue?: boolean
+  enabled?: boolean
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
+export type JobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused'
+// Priority Queue types
+export type PriorityLevel = number

package/dist/utils.d.ts

@@ -0,0 +1,26 @@
+import { RedisClient } from 'bun';
+import type { JobOptions, QueueConfig } from './types';
+/**
+ * Gets a Redis client from the config or creates a new one
+ */
+export declare function getRedisClient(queueConfig?: QueueConfig): RedisClient;
+/**
+ * Generates a unique job ID
+ */
+export declare function generateId(): string;
+/**
+ * Merges job options with defaults
+ */
+export declare function mergeOptions(options?: JobOptions): JobOptions;
+/**
+ * Gets key with prefix
+ */
+export declare function getKey(key: string, prefix?: string): string;
+/**
+ * Parses Redis hash into a job
+ */
+export declare function parseJob(hash: Record<string, string>): any;
+/**
+ * Wait for the specified number of milliseconds
+ */
+export declare function wait(ms: number): Promise<void>;

package/dist/work-coordinator.d.ts

@@ -0,0 +1,35 @@
+import type { RedisClient } from 'bun';
+export declare interface WorkCoordinatorOptions {
+  keyPrefix?: string
+  pollInterval?: number
+  instanceId?: string
+  jobsPerWorker?: number
+  maxWorkersPerInstance?: number
+}
+/**
+ * Manages work distribution among multiple queue instances
+ * to ensure fair sharing of jobs and prevent overloading any one instance
+ */
+export declare class WorkCoordinator {
+  readonly private redisClient: RedisClient;
+  readonly private keyPrefix: string;
+  readonly private instanceId: string;
+  readonly private pollInterval: number;
+  readonly private jobsPerWorker: number;
+  readonly private maxWorkersPerInstance: number;
+  readonly private logger: any;
+  private pollTimer: NodeJS.Timeout | null;
+  private workers: number;
+  private running: boolean;
+  constructor(redisClient: RedisClient, options?: WorkCoordinatorOptions);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  private registerInstance(): Promise<void>;
+  private unregisterInstance(): Promise<void>;
+  private startPolling(): void;
+  private sendHeartbeat(): Promise<void>;
+  private coordinateWork(): Promise<void>;
+  private calculateWorkerDistribution(instanceInfo: Record<string, any>, activeInstances: string[], totalWorkers: number, totalMaxWorkers: number): Record<string, number>;
+  getWorkerCount(): number;
+  getInstanceStatistics(): Promise<Record<string, any>>;
+}

package/dist/worker.d.ts

@@ -0,0 +1,19 @@
+import type { Job } from './job';
+import type { Queue } from './queue';
+export declare class Worker<T = any> {
+  queue: Queue<T>;
+  concurrency: number;
+  handler: (job: Job<T>) => Promise<any>;
+  processing: Map<string, Promise<any>>;
+  running: boolean;
+  timer: NodeJS.Timeout | null;
+  constructor(queue: Queue<T>, concurrency: number, handler: (job: Job<T>) => Promise<any>);
+  start(): void;
+  stop(timeout?: any): Promise<void>;
+  private processTick(): void;
+  private processJobs(): Promise<void>;
+  private processJob(jobId: string): void;
+  private moveToActive(jobId: string): Promise<void>;
+  private moveDelayedJobsToWaiting(): Promise<void>;
+  adjustConcurrency(newConcurrency: number): void;
+}

package/dist/workers/index.d.ts

@@ -0,0 +1,6 @@
+export {
+  QueueWorker,
+  type WorkerEvents,
+  type WorkerOptions,
+} from './queue-worker';
+export { WorkerManager } from './worker-manager';

package/dist/workers/queue-worker.d.ts

@@ -0,0 +1,62 @@
+import { FailedJobManager } from '../failed';
+import type { QueueManagerConfig } from '../types';
+export declare interface WorkerOptions {
+  name?: string
+  connection?: string
+  queue?: string[]
+  delay?: number
+  memory?: number
+  timeout?: number
+  sleep?: number
+  maxTries?: number
+  force?: boolean
+  stopWhenEmpty?: boolean
+  maxJobs?: number
+  maxTime?: number
+  rest?: number
+}
+export declare interface WorkerEvents {
+  jobProcessing: (job: QueueJob<any>) => void
+  jobProcessed: (job: QueueJob<any>, result: any) => void
+  jobFailed: (job: QueueJob<any>, error: Error) => void
+  jobRetry: (job: QueueJob<any>) => void
+  jobTimeout: (job: QueueJob<any>) => void
+  workerStopping: (status: number) => void
+}
+export declare interface WorkerStats {
+  jobsProcessed: number
+  runtime: number
+  isRunning: boolean
+  lastRestart: number
+}
+export declare class QueueWorker {
+  private logger: any;
+  private failedJobManager: FailedJobManager;
+  private isRunning: any;
+  private shouldStop: any;
+  private jobsProcessed: any;
+  private startTime: any;
+  private lastRestart: any;
+  private events: Partial<WorkerEvents>;
+  private config: QueueManagerConfig;
+  private options?: WorkerOptions;
+  constructor(config: QueueManagerConfig, options?: WorkerOptions);
+  work(): Promise<void>;
+  stop(status?: number, options?: { wait?: boolean }): Promise<void>;
+  restart(): Promise<void>;
+  private runNextJob(): Promise<void>;
+  private getNextJob(queue: any): Promise<QueueJob<any> | null>;
+  private processJob(queueJob: QueueJob<any>, queueName: string): Promise<void>;
+  private executeJob(queueJob: QueueJob<any>): Promise<any>;
+  private executeJobClass(queueJob: QueueJob<any>, jobData: any): Promise<any>;
+  private handleJobException(queueJob: QueueJob<any>, error: Error, queueName: string): Promise<void>;
+  private retryJob(queueJob: QueueJob<any>, _error: Error): Promise<void>;
+  private failJob(queueJob: QueueJob<any>, error: Error, queueName: string): Promise<void>;
+  private isJobClass(data: any): boolean;
+  private getJobMaxTries(queueJob: QueueJob<any>): number;
+  private calculateRetryDelay(queueJob: QueueJob<any>): number;
+  private checkLimits(): Promise<void>;
+  private sleep(ms: number): Promise<void>;
+  on<K extends keyof WorkerEvents>(event: K, callback: WorkerEvents[K]): this;
+  getStats(): WorkerStats;
+}

package/dist/workers/worker-manager.d.ts

@@ -0,0 +1,22 @@
+import { QueueWorker } from './queue-worker';
+import type { QueueManagerConfig } from '../types';
+import type { WorkerOptions } from './queue-worker';
+export declare class WorkerManager {
+  private workers: Map<string, QueueWorker>;
+  private logger: any;
+  private config: QueueManagerConfig;
+  constructor(config: QueueManagerConfig);
+  startWorker(name: string, options?: WorkerOptions): Promise<QueueWorker>;
+  stopWorker(name: string, options?: { wait?: boolean }): Promise<boolean>;
+  restartWorker(name: string): Promise<boolean>;
+  stopAllWorkers(options?: { wait?: boolean }): Promise<void>;
+  getWorker(name: string): QueueWorker | undefined;
+  getWorkerNames(): string[];
+  getWorkerStats(): Record<string, any>;
+  isWorkerRunning(name: string): boolean;
+  getWorkerCount(): number;
+  work(options?: WorkerOptions & { name?: string }): Promise<QueueWorker>;
+  restart(name?: string): Promise<void>;
+  terminate(name?: string, options?: { wait?: boolean }): Promise<void>;
+  monitor(intervalMs?: number): NodeJS.Timeout;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@stacksjs/bun-queue",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "A Redis-backed job queue built for Bun.",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/bun-queue#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/bun-queue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/bun-queue/issues"
+  },
+  "keywords": [
+    "queue",
+    "job",
+    "redis",
+    "worker",
+    "task",
+    "scheduler",
+    "bun",
+    "typescript"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./*": {
+      "import": "./src/*"
+    }
+  },
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun --bun build.ts && bun run compile",
+    "compile": "bun build ./bin/cli.ts --compile --minify --outfile bin/queue",
+    "compile:all": "bun run compile:linux-x64 && bun run compile:linux-arm64 && bun run compile:windows-x64 && bun run compile:darwin-x64 && bun run compile:darwin-arm64",
+    "compile:linux-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-x64 --outfile bin/queue-linux-x64",
+    "compile:linux-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-arm64 --outfile bin/queue-linux-arm64",
+    "compile:windows-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-windows-x64 --outfile bin/queue-windows-x64.exe",
+    "compile:darwin-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-x64 --outfile bin/queue-darwin-x64",
+    "compile:darwin-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-arm64 --outfile bin/queue-darwin-arm64",
+    "zip": "bun run zip:all",
+    "zip:all": "bun run zip:linux-x64 && bun run zip:linux-arm64 && bun run zip:windows-x64 && bun run zip:darwin-x64 && bun run zip:darwin-arm64",
+    "zip:linux-x64": "zip -j bin/queue-linux-x64.zip bin/queue-linux-x64",
+    "zip:linux-arm64": "zip -j bin/queue-linux-arm64.zip bin/queue-linux-arm64",
+    "zip:windows-x64": "zip -j bin/queue-windows-x64.zip bin/queue-windows-x64.exe",
+    "zip:darwin-x64": "zip -j bin/queue-darwin-x64.zip bin/queue-darwin-x64",
+    "zip:darwin-arm64": "zip -j bin/queue-darwin-arm64.zip bin/queue-darwin-arm64",
+    "fresh": "bunx rimraf node_modules/ bun.lock && bun i",
+    "prepublishOnly": "bun --bun run build && bun run compile:all && bun run zip",
+    "test": "bun test",
+    "lint": "bunx --bun eslint .",
+    "lint:fix": "bunx --bun eslint . --fix",
+    "changelog": "bunx logsmith --verbose",
+    "changelog:generate": "bunx logsmith --output CHANGELOG.md",
+    "release": "bun --bun run changelog:generate && bunx --bun bumpx prompt --recursive",
+    "typecheck": "bun --bun tsc --noEmit",
+    "example:basic": "bun examples/basic.ts",
+    "example:advanced": "bun examples/advanced.ts",
+    "example:advanced-features": "bun examples/advanced-features.ts",
+    "example:priority-queue": "bun examples/priority-queue.ts",
+    "example:key-rate-limiting": "bun examples/key-rate-limiting.ts",
+    "example:distributed-locks": "bun examples/distributed-locks.ts",
+    "example:cron-jobs": "bun examples/cron-jobs.ts",
+    "example:dead-letter-queue": "bun examples/dead-letter-queue.ts"
+  }
+}