@stacksjs/queue 0.70.23 → 0.70.25

package/dist/src/action.d.ts

@@ -0,0 +1,46 @@
+import type { JobOptions } from '@stacksjs/types';
+/*.ts) and dispatch.
+ * Inspired by Laravel's dispatchable jobs.
+ *
+ * @example
+ * ```typescript
+ * // app/Jobs/SendWelcomeEmail.ts
+ * export default new Job({
+ *   name: 'SendWelcomeEmail',
+ *   queue: 'emails',
+ *   tries: 3,
+ *   backoff: [10, 30, 60],
+ *
+ *   async handle(payload: { email: string }) {
+ *     await sendEmail(payload.email)
+ *   },
+ * })
+ *
+ * // Dispatching:
+ * import SendWelcomeEmail from '~/app/Jobs/SendWelcomeEmail'
+ *
+ * await SendWelcomeEmail.dispatch({ email: 'user@example.com' })
+ * await SendWelcomeEmail.dispatchIf(user.isNew, { email: user.email })
+ * await SendWelcomeEmail.dispatchAfter(60, { email: user.email })
+ * await SendWelcomeEmail.dispatchNow({ email: user.email })
+ * ```
+ */
+export declare class Job {
+  name: JobOptions['name'];
+  description: JobOptions['description'];
+  action?: JobOptions['action'];
+  handle?: JobOptions['handle'];
+  queue?: string;
+  rate: JobOptions['rate'];
+  tries: JobOptions['tries'];
+  timeout?: number;
+  backoff: JobOptions['backoff'];
+  backoffConfig: JobOptions['backoffConfig'];
+  enabled: JobOptions['enabled'];
+  constructor(options: JobOptions & { queue?: string; timeout?: number });
+  dispatch(payload?: any): Promise<void>;
+  dispatchIf(condition: boolean, payload?: any): Promise<void>;
+  dispatchUnless(condition: boolean, payload?: any): Promise<void>;
+  dispatchAfter(delaySeconds: number, payload?: any): Promise<void>;
+  dispatchNow(payload?: any): Promise<void>;
+}

package/dist/src/batch.d.ts

@@ -0,0 +1,115 @@
+import type { Job } from './action';
+export declare function getBatchCallbacks(batchId: string): BatchOptions | undefined;
+/**
+ * Record that a job in a batch completed successfully.
+ * Called by the worker after a batch job finishes.
+ *
+ * Uses an atomic decrement on the database so two concurrent workers
+ * finishing batch jobs at the same instant don't both read pending=N
+ * and both write pending=N-1 — that race used to leave the counter
+ * stuck above zero and the batch's `then`/`finally` callbacks never
+ * fired. Falls back to read-modify-write (with a debug log) when the
+ * driver doesn't expose atomic SQL.
+ */
+export declare function recordBatchJobCompletion(batchId: string): Promise<void>;
+/**
+ * Record that a job in a batch failed.
+ * Called by the worker when a batch job fails its final attempt.
+ */
+export declare function recordBatchJobFailure(batchId: string, jobId: string, error: Error): Promise<void>;
+/**
+ * Check if a batch has been cancelled (used by worker to skip jobs)
+ */
+export declare function isBatchCancelled(batchId: string): Promise<boolean>;
+/**
+ * A pending job within a batch (job + optional payload)
+ */
+export declare interface BatchableJob {
+  job: Job
+  payload?: any
+}
+/**
+ * Batch record stored in the database
+ */
+export declare interface BatchRecord {
+  id: string
+  name: string
+  total_jobs: number
+  pending_jobs: number
+  failed_jobs: number
+  failed_job_ids: string
+  options: string
+  cancelled_at: string | null
+  created_at: string
+  finished_at: string | null
+}
+/**
+ * Batch options for callbacks and behavior
+ */
+export declare interface BatchOptions {
+  name?: string
+  queue?: string
+  allowFailures?: boolean
+  thenCallbacks: Array<(batch: PendingBatch | DispatchedBatch) => Promise<void> | void>
+  catchCallbacks: Array<(batch: PendingBatch | DispatchedBatch, error: Error) => Promise<void> | void>
+  finallyCallbacks: Array<(batch: PendingBatch | DispatchedBatch) => Promise<void> | void>
+  progressCallbacks: Array<(batch: PendingBatch | DispatchedBatch) => Promise<void> | void>
+}
+/**
+ * Batch status
+ */
+export type BatchStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+/**
+ * PendingBatch - a batch that has been configured but not yet dispatched
+ */
+export declare class PendingBatch {
+  constructor(jobs: Array<Job | BatchableJob>);
+  name(name: string): this;
+  onQueue(queue: string): this;
+  allowFailures(): this;
+  then(callback: (batch: PendingBatch | DispatchedBatch) => Promise<void> | void): this;
+  catch(callback: (batch: PendingBatch | DispatchedBatch, error: Error) => Promise<void> | void): this;
+  finally(callback: (batch: PendingBatch | DispatchedBatch) => Promise<void> | void): this;
+  progress(callback: (batch: PendingBatch | DispatchedBatch) => Promise<void> | void): this;
+  dispatch(): Promise<DispatchedBatch>;
+  getJobs(): BatchableJob[];
+  getOptions(): BatchOptions;
+}
+/**
+ * DispatchedBatch - a batch that has been dispatched and can be inspected
+ */
+export declare class DispatchedBatch {
+  readonly id: string;
+  constructor(id: string);
+  fresh(): Promise<BatchRecord | null>;
+  getName(): Promise<string>;
+  totalJobs(): Promise<number>;
+  pendingJobs(): Promise<number>;
+  failedJobs(): Promise<number>;
+  completedJobs(): Promise<number>;
+  progress(): Promise<number>;
+  finished(): Promise<boolean>;
+  cancelled(): Promise<boolean>;
+  hasFailures(): Promise<boolean>;
+  failedJobIds(): Promise<string[]>;
+  cancel(): Promise<void>;
+  add(jobs: Array<Job | BatchableJob>): Promise<void>;
+  delete(): Promise<void>;
+}
+/**
+ * Create a new pending batch
+ *
+ * @example
+ * ```typescript
+ * const batch = Batch.create([job1, job2, job3])
+ *   .name('My Batch')
+ *   .then(async (_batch) => console.log('Done!'))
+ *   .dispatch()
+ * ```
+ */
+export declare class Batch {
+  static create(jobs: Array<Job | BatchableJob>): PendingBatch;
+  static find(id: string): Promise<DispatchedBatch | null>;
+  static all(): Promise<DispatchedBatch[]>;
+  static prune(olderThanHours?: number): Promise<number>;
+}

package/dist/src/discovery.d.ts

@@ -0,0 +1,79 @@
+import type { JobOptions } from '@stacksjs/types';
+/**
+ * Discover jobs from the app/Jobs directory
+ */
+export declare function discoverJobs(jobsPath?: string): Promise<DiscoveredJob[]>;
+/**
+ * Get a job by name from the registry
+ */
+export declare function getJob(name: string): DiscoveredJob | undefined;
+/**
+ * Get all discovered jobs
+ */
+export declare function getAllJobs(): DiscoveredJob[];
+/**
+ * Get scheduled jobs
+ */
+export declare function getScheduledJobs(): DiscoveredJob[];
+/**
+ * Execute a job by name
+ */
+export declare function executeJob<T = any>(name: string, payload?: any): Promise<T>;
+/**
+ * Convert discovered job config to bun-queue JobOptions
+ */
+export declare function toJobOptions(job: DiscoveredJob): JobOptions;
+// Global job registry
+export declare const jobRegistry: JobRegistry;
+/**
+ * Discovered job metadata
+ */
+export declare interface DiscoveredJob {
+  name: string
+  path: string
+  config: JobConfig
+  type: 'class' | 'function'
+  module: any
+}
+/**
+ * Job configuration from discovery
+ */
+export declare interface JobConfig {
+  name?: string
+  description?: string
+  queue?: string
+  tries?: number
+  backoff?: number | number[]
+  rate?: string
+  timeout?: number
+  withoutOverlapping?: boolean
+  retries?: number
+  retryAfter?: number[]
+  schedule?: string
+  backoffConfig?: {
+    strategy?: 'fixed' | 'exponential' | 'linear'
+    initialDelay?: number
+    factor?: number
+    maxDelay?: number
+    jitter?: {
+      enabled?: boolean
+      factor?: number
+      minDelay?: number
+      maxDelay?: number
+    }
+  }
+}
+/**
+ * Job registry for managing discovered jobs
+ */
+declare class JobRegistry {
+  register(job: DiscoveredJob): void;
+  get(name: string): DiscoveredJob | undefined;
+  all(): DiscoveredJob[];
+  byQueue(queue: string): DiscoveredJob[];
+  scheduled(): DiscoveredJob[];
+  has(name: string): boolean;
+  clear(): void;
+  setInitialized(value: boolean): void;
+  isInitialized(): boolean;
+}

package/dist/src/events.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Get the global queue events instance
+ */
+export declare function getQueueEvents(): QueueEvents;
+/**
+ * Subscribe to a queue event
+ *
+ * @example
+ * ```typescript
+ * // Listen for job completions
+ * onQueueEvent('job:completed', (payload) => {
+ *   console.log(`Job ${payload.jobId} completed!`)
+ * })
+ *
+ * // Listen for all events
+ * onQueueEvent('*', (event, payload) => {
+ *   console.log(`Event: ${event}`, payload)
+ * })
+ * ```
+ */
+export declare function onQueueEvent(event: QueueEventType | '*', handler: QueueEventHandler | ((_event: QueueEventType, _payload: QueueEventPayload) => void | Promise<void>)): () => void;
+/**
+ * Emit a queue event
+ */
+export declare function emitQueueEvent(event: QueueEventType, payload: Omit<QueueEventPayload, 'timestamp'>): Promise<void>;
+/**
+ * Event-aware job wrapper
+ *
+ * Wraps a job handler to automatically emit events
+ */
+export declare function withEvents<T extends (...args: any[]) => Promise<any>>(queueName: string, handler: T): T;
+/**
+ * Queue event listener decorator
+ *
+ * @example
+ * ```typescript
+ * class EmailNotifications {
+ *   @OnQueueEvent('job:completed')
+ *   async onJobCompleted(payload: QueueEventPayload) {
+ *     console.log('Job completed:', payload)
+ *   }
+ * }
+ * ```
+ */
+export declare function OnQueueEvent(event: QueueEventType): void;
+/**
+ * Get or create the global QueueMetrics instance
+ */
+export declare function getGlobalMetrics(): QueueMetrics;
+export declare function getWorkerTracker(): WorkerTracker;
+/**
+ * Queue event payload interface
+ */
+export declare interface QueueEventPayload {
+  jobId?: string
+  queueName?: string
+  jobName?: string
+  data?: any
+  result?: any
+  error?: Error
+  progress?: number
+  timestamp: number
+  attemptsMade?: number
+  duration?: number
+}
+/**
+ * Worker status tracker
+ *
+ * Tracks registered workers and their activity for health checks.
+ */
+export declare interface TrackedWorker {
+  id: string
+  status: 'active' | 'idle' | 'stopped'
+  queue: string
+  processedCount: number
+  failedCount: number
+  lastActivityAt: string
+  startedAt: string
+}
+/**
+ * Queue event types
+ */
+export type QueueEventType = | 'job:added'
+  | 'job:processing'
+  | 'job:completed'
+  | 'job:failed'
+  | 'job:retrying'
+  | 'job:stalled'
+  | 'job:progress'
+  | 'queue:paused'
+  | 'queue:resumed'
+  | 'queue:error'
+  | 'worker:started'
+  | 'worker:stopped'
+  | 'batch:added'
+  | 'batch:completed'
+  | 'batch:failed';
+/**
+ * Queue event handler type
+ */
+export type QueueEventHandler = (_payload: QueueEventPayload) => void | Promise<void>;
+/**
+ * Queue events emitter
+ */
+export declare class QueueEvents {
+  on(event: QueueEventType, handler: QueueEventHandler): () => void;
+  onAny(handler: (event: QueueEventType, payload: QueueEventPayload) => void | Promise<void>): () => void;
+  once(event: QueueEventType, handler: QueueEventHandler): () => void;
+  emit(event: QueueEventType, payload: Omit<QueueEventPayload, 'timestamp'>): Promise<void>;
+  off(event: QueueEventType): void;
+  removeAllListeners(): void;
+}
+/**
+ * Queue metrics based on events
+ */
+export declare class QueueMetrics {
+  constructor();
+  getThroughputPerMinute(): number;
+  getAverageProcessingTime(): number;
+  getMetrics(): {
+    counts: { added: number; completed: number; failed: number; processing: number }
+    averageDuration: number
+    recentErrors: Array<{ error: Error; timestamp: number }>
+    throughputPerMinute: number
+  };
+  reset(): void;
+  stop(): void;
+}
+declare class WorkerTracker {
+  register(id: string, queue: string): void;
+  markActive(id: string): void;
+  markIdle(id: string): void;
+  recordCompletion(id: string): void;
+  recordFailure(id: string): void;
+  unregister(id: string): void;
+  getAll(): TrackedWorker[];
+  clear(): void;
+}

package/dist/src/health.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Perform queue health check
+ */
+export declare function checkQueueHealth(config?: HealthCheckConfig): Promise<QueueHealthResult>;
+/**
+ * Create a health check HTTP handler
+ */
+export declare function createHealthCheckHandler(config?: HealthCheckConfig): (req: Request) => Promise<Response>;
+/**
+ * Quick health check - returns just the status
+ */
+export declare function isQueueHealthy(config?: HealthCheckConfig): Promise<boolean>;
+/**
+ * Queue health check result
+ */
+export declare interface QueueHealthResult {
+  status: HealthStatus
+  timestamp: string
+  queues: QueueStatus[]
+  workers: WorkerStatus[]
+  metrics: QueueMetrics
+  alerts: HealthAlert[]
+}
+/**
+ * Individual queue status
+ */
+export declare interface QueueStatus {
+  name: string
+  status: HealthStatus
+  pending: number
+  processing: number
+  delayed: number
+  failed: number
+  oldestJobAge?: number
+}
+/**
+ * Worker status
+ */
+export declare interface WorkerStatus {
+  id: string
+  status: 'active' | 'idle' | 'stopped'
+  queue: string
+  processedCount: number
+  failedCount: number
+  lastActivityAt?: string
+}
+/**
+ * Queue metrics summary
+ */
+export declare interface QueueMetrics {
+  totalPending: number
+  totalProcessing: number
+  totalDelayed: number
+  totalFailed: number
+  throughputPerMinute: number
+  averageProcessingTime: number
+  errorRate: number
+}
+/**
+ * Health alert
+ */
+export declare interface HealthAlert {
+  level: 'warning' | 'critical'
+  message: string
+  queue?: string
+  timestamp: string
+}
+/**
+ * Health check configuration
+ */
+export declare interface HealthCheckConfig {
+  maxPendingWarning?: number
+  maxPendingCritical?: number
+  maxFailedWarning?: number
+  maxFailedCritical?: number
+  maxJobAgeWarning?: number
+  maxJobAgeCritical?: number
+  maxErrorRateWarning?: number
+  maxErrorRateCritical?: number
+  queues?: string[]
+}
+/**
+ * Health status
+ */
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';

package/dist/src/index.d.ts

@@ -0,0 +1,137 @@
+// =============================================================================
+// Redis queue driver
+// =============================================================================
+// Redis driver is lazily loaded to avoid requiring bun-queue when not using Redis.
+// Use: const { RedisQueue } = await import('@stacksjs/queue/drivers/redis')
+// Or access via the queue manager which dynamically imports the driver.
+export declare function getRedisQueue(): Promise<void>;
+/**
+ * @stacksjs/queue
+ *
+ * A thin wrapper around bun-queue that integrates with Stacks conventions.
+ * Core Stacks queue exports are always available. For advanced bun-queue
+ * features (Queue, Worker, dispatch, etc.), import from '@stacksjs/queue/bun-queue'.
+ */
+// =============================================================================
+// Stacks Job class for file-based jobs (app/Jobs/*.ts)
+// =============================================================================
+export { Job } from './action';
+// =============================================================================
+// Stacks job helper for dispatching file-based jobs
+// =============================================================================
+export { Jobs, job, jobBatch, runJob } from './job';
+// =============================================================================
+// Per-job progress + cancellation (cache-backed; safe across processes)
+// =============================================================================
+export { setJobProgress, getJobProgress, cancelJob, isJobCancelled, clearJobState } from './job-progress';
+// =============================================================================
+// Job discovery (for app/Jobs directory)
+// =============================================================================
+export {
+  discoverJobs,
+  executeJob,
+  getAllJobs,
+  getJob,
+  getScheduledJobs,
+  jobRegistry,
+  toJobOptions,
+  type DiscoveredJob,
+  type JobConfig,
+} from './discovery';
+// =============================================================================
+// Stacks scheduler (integrates with job discovery)
+// =============================================================================
+export {
+  getRegisteredJobs,
+  getSchedulerStatus,
+  isSchedulerRunning,
+  startScheduler,
+  stopScheduler,
+  triggerJob,
+} from './scheduler';
+// =============================================================================
+// Stacks queue events (integrates with Stacks logging)
+// =============================================================================
+export {
+  emitQueueEvent,
+  getGlobalMetrics,
+  getQueueEvents,
+  getWorkerTracker,
+  onQueueEvent,
+  OnQueueEvent,
+  QueueEvents,
+  QueueMetrics,
+  withEvents,
+  type QueueEventHandler,
+  type QueueEventPayload,
+  type QueueEventType,
+  type TrackedWorker,
+} from './events';
+// =============================================================================
+// Health checks
+// =============================================================================
+export {
+  checkQueueHealth,
+  createHealthCheckHandler,
+  isQueueHealthy,
+  type HealthAlert,
+  type HealthCheckConfig,
+  type HealthStatus,
+  type QueueHealthResult,
+  type QueueMetrics as HealthQueueMetrics,
+  type QueueStatus,
+  type WorkerStatus,
+} from './health';
+// =============================================================================
+// Failed job notifications
+// =============================================================================
+export {
+  configureFailedJobNotifications,
+  FailedJobNotifier,
+  getFailedJobNotifier,
+  notifyJobFailed,
+  type FailedJobInfo,
+  type FailedJobNotificationConfig,
+  type NotificationChannel,
+} from './notifications';
+// =============================================================================
+// Testing utilities
+// =============================================================================
+export {
+  createQueueTester,
+  expectJobToFail,
+  fake,
+  getFakeQueue,
+  isFaked,
+  QueueTester,
+  restore,
+  runJob as runTestJob,
+  type DispatchedJob,
+} from './testing';
+// =============================================================================
+// Job batches
+// =============================================================================
+export {
+  Batch,
+  DispatchedBatch,
+  PendingBatch,
+  getBatchCallbacks,
+  isBatchCancelled,
+  recordBatchJobCompletion,
+  recordBatchJobFailure,
+  type BatchableJob,
+  type BatchOptions,
+  type BatchRecord,
+  type BatchStatus,
+} from './batch';
+// =============================================================================
+// Worker functions (for queue:work command)
+// =============================================================================
+export {
+  executeFailedJobs,
+  getActiveJobCount,
+  isWorkerRunning,
+  retryFailedJob,
+  startProcessor,
+  stopProcessor,
+} from './worker';

package/dist/src/job-progress.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Update the progress of the running job. Workers call this from
+ * inside their handler; the UI polls `getJobProgress(id)` to render
+ * a progress bar.
+ *
+ * @example
+ * ```ts
+ * await job.progress(0.5, 'Halfway there')
+ * // … later
+ * await job.progress(1.0, 'Done')
+ * ```
+ */
+export declare function setJobProgress(jobId: string, percent: number, message?: string): Promise<void>;
+/**
+ * Read the current progress of a job, or `null` if no progress has
+ * been recorded yet (job hasn't started, or the entry expired).
+ */
+export declare function getJobProgress(jobId: string): Promise<JobProgress | null>;
+/**
+ * Mark a job as cancelled. The next time the worker calls
+ * `isJobCancelled(id)` it will see the flag and can stop cleanly. The
+ * worker is responsible for checking — the framework can't preempt a
+ * running handler safely.
+ *
+ * @example
+ * ```ts
+ * // From an admin endpoint:
+ * await cancelJob(req.params.id)
+ *
+ * // Inside the worker:
+ * if (await isJobCancelled(job.id)) return
+ * ```
+ */
+export declare function cancelJob(jobId: string): Promise<void>;
+/**
+ * Check whether the named job has been cancelled. Workers should call
+ * this between unit-of-work iterations so cancellations are honored
+ * promptly without preempting in-flight work.
+ */
+export declare function isJobCancelled(jobId: string): Promise<boolean>;
+/**
+ * Clear progress + cancellation state for a finished job. Workers
+ * should call this on completion (success or failure) so admin UIs
+ * showing "in-flight jobs" don't keep finished entries forever.
+ *
+ * No-op if no entries exist for the id — safe to call always.
+ */
+export declare function clearJobState(jobId: string): Promise<void>;
+declare interface JobProgress {
+  percent: number
+  message?: string
+  updatedAt: number
+}