@stacksjs/queue 0.70.87 → 0.70.88

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/queue",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.87",
+  "version": "0.70.88",
   "description": "The Stacks Queue system powered by bun-queue.",
   "author": "Chris Breuer",
   "contributors": [

package/dist/action.d.ts

@@ -1,46 +0,0 @@
-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<T = unknown>(payload?: T): Promise<void>;
-  dispatchIf<T = unknown>(condition: boolean, payload?: T): Promise<void>;
-  dispatchUnless<T = unknown>(condition: boolean, payload?: T): Promise<void>;
-  dispatchAfter<T = unknown>(delaySeconds: number, payload?: T): Promise<void>;
-  dispatchNow<T = unknown>(payload?: T): Promise<void>;
-}

package/dist/batch.d.ts

@@ -1,150 +0,0 @@
-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
-  then_handler?: string | null
-  catch_handler?: string | null
-  finally_handler?: 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>
-  thenHandler?: PersistentBatchHandler
-  catchHandler?: PersistentBatchHandler
-  finallyHandler?: PersistentBatchHandler
-}
-/**
- * Batch status
- */
-export type BatchStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
-/**
- * Persistent batch handler shape (stacksjs/stacks#1883).
- *
- * Survives worker restart by being JSON-serialized into the
- * `job_batches.then_handler` / `catch_handler` / `finally_handler`
- * columns. The winning worker (the one that flips
- * `pending_jobs = 0 → finished_at`) reads + dispatches these on
- * completion, so a batch that finishes after the dispatching
- * process died still fires its terminal callbacks.
- *
- * Two shapes:
- *   - `job`    — dispatch a queued job by name; the worker fires
- *                the job through `Jobs.dispatch(name, payload)`
- *   - `module` — load a module and invoke a named export; payload
- *                is passed through. Useful for in-process side-
- *                effects that don't warrant their own job (e.g.
- *                cleanup helpers, simple notifications).
- *
- * Inline function callbacks (the existing `.then(fn)` API) stay
- * supported as a process-local convenience — they continue to live
- * in the in-memory registry alongside any persistent handler. The
- * winning worker fires both: any in-memory callbacks AND the
- * persistent handler if one was registered.
- */
-export type PersistentBatchHandler = | { kind: 'job', name: string, payload?: unknown }
-  | { kind: 'module', module: string, export: string, payload?: unknown }
-/**
- * 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;
-  thenHandler(handler: PersistentBatchHandler): this;
-  catchHandler(handler: PersistentBatchHandler): this;
-  finallyHandler(handler: PersistentBatchHandler): 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/circuit-breaker.d.ts

@@ -1,52 +0,0 @@
-/**
- * Is the queue currently paused? Returns `true` when `paused_at`
- * is set and `resume_at` hasn't passed yet. Also auto-clears the
- * paused state when the cooldown elapses so the next call sees
- * the queue as available again.
- */
-export declare function isCircuitOpen(queue: string): Promise<boolean>;
-/**
- * Record a successful job. Maintained alongside failure_count so
- * the failure-rate calculation is meaningful. Window resets after
- * `windowSeconds` so an old failure burst doesn't permanently
- * skew the rate.
- */
-export declare function recordCircuitSuccess(queue: string, config?: CircuitBreakerConfig): Promise<void>;
-/**
- * Record a failed job. After incrementing, evaluates whether the
- * failure rate has crossed the threshold and trips the breaker if
- * so. Returns `true` when this call triggered the trip.
- */
-export declare function recordCircuitFailure(queue: string, config?: CircuitBreakerConfig): Promise<boolean>;
-/**
- * Manually pause a queue for the given cooldown (default matches
- * the configured `pauseSeconds`). Useful when an operator knows
- * downstream is broken and wants to skip jobs immediately rather
- * than wait for the auto-trip.
- */
-export declare function pauseQueue(queue: string, pauseSeconds?: number): Promise<void>;
-/**
- * Lift the pause on a queue (manual resume). Workers resume
- * processing on the next poll cycle.
- */
-export declare function resumeQueue(queue: string): Promise<void>;
-/**
- * Snapshot the current circuit state for every tracked queue.
- * Used by `queue:status` to show paused queues alongside
- * pending/failed counts.
- */
-export declare function listCircuitState(): Promise<CircuitRow[]>;
-export declare interface CircuitBreakerConfig {
-  failureRateThreshold?: number
-  windowSeconds?: number
-  pauseSeconds?: number
-  minObservations?: number
-}
-declare interface CircuitRow {
-  queue_name: string
-  success_count: number
-  failure_count: number
-  window_start: string
-  paused_at: string | null
-  resume_at: string | null
-}

package/dist/dead-letter.d.ts

@@ -1,61 +0,0 @@
-/**
- * Move a job from `failed_jobs` into `dead_letter_jobs`. Called
- * by the retry path when a job re-fails, and by the poison/
- * circuit-breaker paths when they intercept a job pre-dispatch.
- *
- * Returns `true` on success, `false` when the DLQ table is missing
- * (caller falls back to today's behavior — leave the row in
- * `failed_jobs`).
- */
-export declare function moveToDeadLetter(failedJob: {
-    uuid?: string
-    connection?: string
-    queue?: string
-    payload?: string
-    exception?: string
-    failed_at?: string | null
-  }, reason: DeadLetterReason, totalFailures?: number): Promise<boolean>;
-export declare function listDeadLetterJobs(filter?: ListDeadLetterFilter): Promise<DeadLetterRecord[]>;
-/**
- * Pull a DLQ row back into the active `jobs` queue. Resets
- * `attempts` to 0 and `reserved_at` to null so the worker picks
- * it up on the next poll cycle. The original DLQ row is deleted
- * after the re-enqueue.
- *
- * Returns `true` when the job was found + re-enqueued, `false`
- * when the id didn't exist OR the DLQ table is missing.
- */
-export declare function retryDeadLetterJob(id: number): Promise<boolean>;
-/**
- * Delete DLQ rows older than `olderThanDays`. Useful for retention
- * cleanup — apps with high failure volume can prune rows after the
- * configured window. Default 30 days.
- *
- * Returns the number of rows deleted; 0 when the table is missing.
- */
-export declare function purgeDeadLetterJobs(olderThanDays?: number): Promise<number>;
-export declare interface DeadLetterRecord {
-  id: number
-  uuid: string
-  connection: string
-  queue: string
-  payload: string
-  exception: string
-  reason: DeadLetterReason
-  total_failures: number
-  first_failed_at: string | null
-  last_failed_at: string | null
-  dead_lettered_at: string
-}
-/**
- * List dead-letter rows. Filters compose: `queue` narrows by
- * queue name, `since` filters by `dead_lettered_at` cutoff. Limit
- * defaults to 100 to keep CLI output manageable.
- */
-export declare interface ListDeadLetterFilter {
-  queue?: string
-  reason?: DeadLetterReason
-  sinceCutoffMs?: number
-  limit?: number
-}
-export type DeadLetterReason = 'repeat-failure' | 'poison-detected' | 'circuit-broken' | 'manual';

package/dist/discovery.d.ts

@@ -1,79 +0,0 @@
-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/envelope.d.ts

@@ -1,89 +0,0 @@
-/**
- * Construct a fresh envelope for an outgoing dispatch. Both drivers
- * call this — single source of truth for the on-the-wire shape.
- */
-export declare function createEnvelope(jobName: string, payload: unknown, options?: JobEnvelopeOptions): JobEnvelope;
-/**
- * Test-only: clear the warn-once state. Production callers never
- * need this.
- */
-export declare function clearEnvelopeWarnings(): void;
-/**
- * Parse an opaque value into a `JobEnvelope`. Accepts strings (which
- * are JSON-parsed) or objects (which are inspected directly) —
- * the database driver passes a JSON string; the redis driver passes
- * the already-deserialized object that bun-queue gave back.
- *
- * Returns a discriminated result so caller code doesn't have to
- * pattern-match on the version field. Forward-compatible: an
- * unknown-but-newer version returns `{ ok: false, reason:
- * 'unknown-version' }` so the worker can leave the row for a
- * newer-build worker.
- */
-export declare function parseEnvelope(raw: unknown): ParsedEnvelope;
-/**
- * Unified job envelope (stacksjs/stacks#1884, Q-6 from #1872).
- *
- * Background: the database and redis queue drivers serialized jobs
- * differently:
- *
- *   - database: `{ jobName, payload, options }` JSON-stringified into
- *     the `jobs.payload` column
- *   - redis: `{ jobName, payload }` passed as bun-queue's `data` arg
- *     with options split into bun-queue's second arg
- *
- * Switching `QUEUE_DRIVER` mid-flight orphaned in-flight jobs because
- * the new worker couldn't deserialize the other shape. Fix: one
- * `JobEnvelope` shape, used by every driver's write AND read, with a
- * `envelopeVersion` field so a future shape change can be rolled out
- * without breaking in-flight jobs queued under the previous version.
- *
- * Backward-compat: `parseEnvelope` handles three shapes:
- *
- *   1. **v1 (this version)** — full envelope with `envelopeVersion: 1`
- *   2. **v0 implicit** — pre-fix shape (`{ jobName, payload, options? }`
- *      with no `envelopeVersion`). One-shot warn-and-process so the
- *      operator knows the migration window is closing.
- *   3. **Laravel legacy** — `{ job: 'App\\Jobs\\Foo', data }` carried
- *      over from the database-Laravel-port era. Same warn-and-process.
- *
- * Forward-compat: a `envelopeVersion` newer than `JOB_ENVELOPE_VERSION`
- * is logged and skipped (so a rolling deploy with a newer-shape envelope
- * doesn't crash old workers; they leave the row for the new workers to
- * pick up).
- */
-/**
- * Current envelope version. Bump when you change the shape of
- * `JobEnvelope` in a way that older workers couldn't deserialize.
- *
- * - v1: jobName + payload + optional options + envelopeVersion +
- *       dispatchedAt
- */
-export declare const JOB_ENVELOPE_VERSION: 1;
-/**
- * Per-job runtime options that travel with the envelope so a worker
- * processing the job knows how to apply them (timeout, retries,
- * backoff). The database driver previously embedded these in the
- * envelope; the redis driver lost them across the wire because they
- * went to bun-queue's separate options arg only.
- */
-export declare interface JobEnvelopeOptions {
-  queue?: string
-  timeout?: number
-  tries?: number
-  backoff?: number | number[]
-}
-export declare interface JobEnvelope {
-  jobName: string
-  payload: unknown
-  options?: JobEnvelopeOptions
-  envelopeVersion: number
-  dispatchedAt: string
-}
-/**
- * Result of attempting to parse an arbitrary input into a
- * `JobEnvelope`. Discriminated so callers don't have to inspect
- * the version field directly.
- */
-export type ParsedEnvelope = | { ok: true, envelope: JobEnvelope, source: 'v1' | 'v0-implicit' | 'laravel-legacy' }
-  | { ok: false, reason: 'malformed' | 'unknown-version' | 'missing-job-name', detail?: string }

package/dist/events.d.ts

@@ -1,138 +0,0 @@
-/**
- * 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;
-}