@stacksjs/queue 0.70.88 → 0.70.90

package/dist/job.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Create a job builder for dispatching file-based jobs
+ *
+ * @example
+ * ```typescript
+ * // Basic dispatch
+ * await job('SendWelcomeEmail', { userId: 1 }).dispatch()
+ *
+ * // With options
+ * await job('ProcessOrder', { orderId: 123 })
+ *   .onQueue('orders')
+ *   .tries(3)
+ *   .backoff([10, 30, 60])
+ *   .dispatch()
+ *
+ * // Immediate execution
+ * await job('SendNotification', { message: 'Hello' }).dispatchNow()
+ * ```
+ */
+export declare function job(name: string, payload?: any): JobBuilder;
+/**
+ * Create a job batch for dispatching multiple jobs together
+ *
+ * @example
+ * ```typescript
+ * import SendWelcomeEmail from '~/app/Jobs/SendWelcomeEmail'
+ * import ProcessOrder from '~/app/Jobs/ProcessOrder'
+ *
+ * const batch = await jobBatch([
+ *   { job: SendWelcomeEmail, payload: { email: 'user@example.com' } },
+ *   { job: ProcessOrder, payload: { orderId: 123 } },
+ * ])
+ *   .name('Onboard User')
+ *   .allowFailures()
+ *   .then(async (_b) => console.log('All done!'))
+ *   .dispatch()
+ * ```
+ */
+export declare function jobBatch(jobs: Array<import('./action').Job | import('./batch').BatchableJob>): import('./batch').PendingBatch;
+/**
+ * Run a job immediately by name
+ *
+ * This loads the job from app/Jobs/{name}.ts and executes it
+ *
+ * Wraps execution in `withTraceId(...)` so log lines, db queries, and
+ * downstream HTTP calls emitted from inside the job carry the same
+ * trace id as the request (or a fresh one for cron-triggered runs).
+ * `options.traceId` lets dispatchers attach a parent id explicitly;
+ * absent that, we mint one of the form `job:<name>:<random>` so
+ * background work is at least correlatable to itself.
+ */
+export declare function runJob(name: string, options?: { payload?: any; context?: any; traceId?: string }): Promise<void>;
+/*.ts`; this `Jobs` facade is the *call-site* form for
+ * dispatching by name from anywhere in the app. It lets one-liner
+ * dispatches skip the builder while still allowing the chainable form
+ * via `Jobs.make(...)` for option-heavy cases.
+ *
+ * @example
+ * ```typescript
+ * // One-shot dispatch (no options)
+ * await Jobs.dispatch('SendWelcomeEmail', { userId: 1 })
+ *
+ * // Conditional dispatch
+ * await Jobs.dispatchIf(user.isNew, 'SendWelcomeEmail', { userId: user.id })
+ *
+ * // With options — fall back to the builder
+ * await Jobs.make('ProcessOrder', { orderId: 123 })
+ *   .onQueue('orders')
+ *   .tries(3)
+ *   .dispatch()
+ *
+ * // Immediate (synchronous) execution, ignoring the queue
+ * await Jobs.dispatchNow('SendNotification', { message: 'Hello' })
+ * ```
+ * @defaultValue
+ * ```ts
+ * {
+ *   dispatch: () => unknown,
+ *   dispatchIf: () => unknown,
+ *   dispatchUnless: () => unknown,
+ *   dispatchNow: () => unknown,
+ *   dispatchOnce: () => unknown
+ * }
+ * ```
+ */
+export declare const Jobs: {
+  /** Construct a builder without dispatching — for chained option calls. */
+  make: (name: string, payload?: any) => JobBuilder;
+  /** Dispatch a job in one call. Equivalent to `job(name, payload).dispatch()`. */
+  dispatch: (name: string, payload?: any) => Promise<void>;
+  /** Dispatch only if `condition` is truthy. */
+  dispatchIf: (condition: boolean, name: string, payload?: any) => Promise<void>;
+  /** Dispatch unless `condition` is truthy. */
+  dispatchUnless: (condition: boolean, name: string, payload?: any) => Promise<void>;
+  /** Run the job synchronously, bypassing the queue. */
+  dispatchNow: (name: string, payload?: any) => Promise<void>;
+  /** Schedule the job to run after `seconds` of delay. */
+  dispatchAfter: (seconds: number, name: string, payload?: any) => JobBuilder;
+  /**
+   * Dispatch with an idempotency key in one call
+   * (stacksjs/stacks#1872 Q-8). Equivalent to
+   * `Jobs.make(name, payload).withIdempotencyKey(key).dispatch()`.
+   */
+  dispatchOnce: (key: string, name: string, payload?: any) => Promise<void>
+};
+/**
+ * Options for job dispatch
+ */
+export declare interface JobDispatchOptions {
+  queue?: string
+  delay?: number
+  tries?: number
+  timeout?: number
+  backoff?: number[]
+  context?: any
+  idempotencyKey?: string
+}
+/**
+ * Per-builder override of the transaction-context default.
+ * `'auto'` (the default) respects the current transaction scope:
+ * buffers when inside `db.transaction(...)`, dispatches immediately
+ * otherwise. `'after'` forces buffering even outside a transaction
+ * (warn-and-dispatch since there's nothing to buffer against).
+ * `'immediate'` forces immediate dispatch even inside a transaction
+ * — used for fire-and-forget side-effects that legitimately want
+ * to run before the surrounding transaction commits (analytics,
+ * lock probes, etc.).
+ *
+ * See stacksjs/stacks#1882.
+ */
+declare type TransactionMode = 'auto' | 'after' | 'immediate';
+/**
+ * Fluent job builder for file-based jobs
+ */
+declare class JobBuilder {
+  constructor(name: string, payload?: any);
+  onQueue(queue: string): this;
+  delay(seconds: number): this;
+  tries(count: number): this;
+  timeout(seconds: number): this;
+  backoff(delays: number[]): this;
+  withContext(context: any): this;
+  withIdempotencyKey(key: string): this;
+  afterCommit(): this;
+  withoutCommit(): this;
+  dispatch(): Promise<void>;
+  dispatchIf(condition: boolean): Promise<void>;
+  dispatchUnless(condition: boolean): Promise<void>;
+  dispatchNow(): Promise<void>;
+}

package/dist/notifications.d.ts

@@ -0,0 +1,70 @@
+import { log } from '@stacksjs/logging';
+/**
+ * Configure failed job notifications
+ */
+export declare function configureFailedJobNotifications(config: FailedJobNotificationConfig): FailedJobNotifier;
+/**
+ * Get the global notifier
+ */
+export declare function getFailedJobNotifier(): FailedJobNotifier | null;
+/**
+ * Notify about a failed job using the global notifier
+ */
+export declare function notifyJobFailed(job: FailedJobInfo): Promise<void>;
+/**
+ * Failed job info
+ */
+export declare interface FailedJobInfo {
+  id: string | number
+  name: string
+  queue: string
+  payload: any
+  exception: string
+  failedAt: Date
+  attempts: number
+  maxAttempts: number
+}
+/**
+ * Notification configuration
+ */
+export declare interface FailedJobNotificationConfig {
+  channels: NotificationChannel[]
+  email?: {
+    to: string | string[]
+    from?: string
+    subject?: string
+  }
+  slack?: {
+    webhookUrl: string
+    channel?: string
+    username?: string
+    iconEmoji?: string
+  }
+  discord?: {
+    webhookUrl: string
+    username?: string
+    avatarUrl?: string
+  }
+  webhook?: {
+    url: string
+    headers?: Record<string, string>
+    secret?: string
+  }
+  rateLimit?: number
+  batch?: boolean
+  batchInterval?: number
+  filter?: (job: FailedJobInfo) => boolean
+}
+/**
+ * Notification channel types
+ */
+export type NotificationChannel = 'email' | 'slack' | 'discord' | 'webhook' | 'log';
+/**
+ * Failed job notification manager
+ */
+export declare class FailedJobNotifier {
+  constructor(config: FailedJobNotificationConfig);
+  notify(job: FailedJobInfo): Promise<void>;
+  shutdown(): Promise<void>;
+  cleanup(): Promise<void>;
+}

package/dist/poison.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Compute the dedup key for a job+payload combination. Stable
+ * sha256 truncated to 32 hex chars — short enough to fit in
+ * indexed columns, wide enough to avoid collisions in practice.
+ */
+export declare function hashPayload(payload: unknown): string;
+/**
+ * Record a failure against `(jobName, payload-hash)`. If this push
+ * makes the count exceed the threshold within the window, the row
+ * is marked `quarantined_at` and the function returns `true`.
+ *
+ * Called from the worker's failure path AFTER the job lands in
+ * `failed_jobs`. Failures outside the window reset the count.
+ */
+export declare function recordFailureForPoison(jobName: string, payload: unknown, config?: PoisonConfig): Promise<boolean>;
+/**
+ * Is `(jobName, payload)` currently quarantined? Called from the
+ * dispatch path — true means "skip the queue, route directly to
+ * the DLQ".
+ */
+export declare function isQuarantined(jobName: string, payload: unknown): Promise<boolean>;
+/**
+ * Manually quarantine a job class. Useful when an operator knows
+ * a particular flow is broken (e.g. third-party API outage) and
+ * wants to stop the queue from churning on it before the failure
+ * threshold trips.
+ *
+ * If `payload` is omitted, every payload-hash for the job name is
+ * matched (uses wildcard `payload_hash = '*'`). For class-wide
+ * quarantine without per-payload granularity.
+ */
+export declare function quarantineJob(jobName: string, payload?: unknown): Promise<void>;
+/**
+ * Lift the quarantine for a job class. Deletes every
+ * `job_quarantine` row matching `jobName` (across all payload
+ * hashes) so future dispatches go to the queue normally.
+ */
+export declare function unquarantineJob(jobName: string): Promise<void>;
+/**
+ * Read the set of currently-quarantined job names + payload hashes
+ * for the `queue:quarantine` CLI list view.
+ */
+export declare function listQuarantined(): Promise<Array<{
+  id: number
+  job_name: string
+  payload_hash: string
+  failure_count: number
+  quarantined_at: string | null
+}>>;
+export declare interface PoisonConfig {
+  maxFailures?: number
+  windowMinutes?: number
+}

package/dist/scheduler-persistence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Load a job's persisted `lastRun`, or null when there's none / persistence is
+ * unavailable. Used at startup so a restart doesn't re-fire a job that already
+ * ran this minute.
+ */
+export declare function loadPersistedLastRun(jobName: string): Promise<Date | null>;
+/**
+ * Persist a job's `lastRun` (bounded to one row per job). Delete-then-insert is
+ * a portable upsert that avoids the per-dialect UPDATE-affected-rows ambiguity
+ * (MySQL reports 0 rows on an unchanged value); a single scheduler process owns
+ * this table, so there is no concurrent-writer race. Best-effort.
+ */
+export declare function persistLastRun(jobName: string, when: Date): Promise<void>;
+/** Test hook: reset the one-time table-ensured flag. */
+export declare function __resetSchedulerPersistenceForTests(): void;

package/dist/scheduler.d.ts

@@ -0,0 +1,69 @@
+import { type DiscoveredJob } from './discovery';
+/**
+ * Extract the wall-clock fields a cron expression matches against, in the
+ * configured timezone (stacksjs/stacks#1984). `SchedulerConfig.timezone` was
+ * documented ("Timezone for cron expressions") but never applied — cron ran in
+ * the server's local time regardless, so `0 9 * * *` fired at 9am server-local
+ * rather than 9am in the configured zone. With no timezone set we keep
+ * local-time semantics; an invalid zone warns once and falls back to local.
+ */
+export declare function getCronParts(date: Date, timeZone?: string): CronParts;
+/**
+ * Calculate next run time for a cron expression
+ */
+export declare function calculateNextRun(cronExpression: string, timeZone?: string): Date | null;
+/**
+ * Start the scheduler
+ */
+export declare function startScheduler(config?: Partial<SchedulerConfig>): Promise<void>;
+/**
+ * Stop the scheduler
+ */
+export declare function stopScheduler(): Promise<void>;
+/**
+ * Get scheduler status
+ */
+export declare function getSchedulerStatus(): {
+  isRunning: boolean
+  jobCount: number
+  jobs: Array<{
+    name: string
+    schedule: string | undefined
+    lastRun: Date | null
+    nextRun: Date | null
+    isRunning: boolean
+  }>
+};
+/**
+ * Check if scheduler is running
+ */
+export declare function isSchedulerRunning(): boolean;
+/**
+ * Get registered scheduled jobs
+ */
+export declare function getRegisteredJobs(): Map<string, ScheduledJobState>;
+/**
+ * Manually trigger a scheduled job
+ */
+export declare function triggerJob(name: string): Promise<void>;
+/**
+ * Scheduler configuration
+ */
+declare interface SchedulerConfig {
+  checkInterval: number
+  timezone?: string
+  preventOverlapping: boolean
+}
+/**
+ * Scheduled job state
+ */
+declare interface ScheduledJobState {
+  job: DiscoveredJob
+  lastRun: Date | null
+  nextRun: Date | null
+  isRunning: boolean
+}
+/**
+ * Parse a cron expression and check if it should run now
+ */
+declare interface CronParts { minute: number, hour: number, day: number, month: number, dayOfWeek: number }

package/dist/testing.d.ts

@@ -0,0 +1,74 @@
+import type { JobOptions } from '@stacksjs/types';
+/**
+ * Enable fake queue for testing
+ */
+export declare function fake(): FakeQueue;
+/**
+ * Get the fake queue instance
+ */
+export declare function getFakeQueue(): FakeQueue | null;
+/**
+ * Check if queue is faked
+ */
+export declare function isFaked(): boolean;
+/**
+ * Restore real queue behavior
+ */
+export declare function restore(): void;
+/**
+ * Create a queue tester instance
+ */
+export declare function createQueueTester(): QueueTester;
+/**
+ * Test helper to run a job synchronously
+ */
+export declare function runJob<T, R>(jobModule: { handle: (data: T) => Promise<R> | R }, data: T): Promise<R>;
+/**
+ * Test helper to expect a job to fail
+ */
+export declare function expectJobToFail<T>(jobModule: { handle: (data: T) => Promise<any> }, data: T, expectedError?: string | RegExp): Promise<Error>;
+/**
+ * Dispatched job record for assertions
+ */
+export declare interface DispatchedJob<T = any> {
+  name: string
+  data: T
+  options: Partial<JobOptions>
+  dispatchedAt: Date
+  queue: string
+}
+/**
+ * Fake queue for testing
+ */
+declare class FakeQueue {
+  dispatch<T>(name: string, data: T, options?: Partial<JobOptions>): void;
+  push<T>(name: string, data: T, options?: Partial<JobOptions>): void;
+  dispatched(name?: string): DispatchedJob[];
+  pushed(name?: string): DispatchedJob[];
+  assertDispatched(name: string, callback?: (job: DispatchedJob) => boolean): void;
+  assertNotDispatched(name: string): void;
+  assertDispatchedTimes(name: string, times: number): void;
+  assertNothingDispatched(): void;
+  assertPushed(name: string, callback?: (job: DispatchedJob) => boolean): void;
+  assertPushedWithDelay(name: string, delay: number): void;
+  assertPushedOn(queue: string, name: string): void;
+  processJob<T>(name: string, handler: (data: T) => Promise<any>): Promise<void>;
+  processed(name?: string): DispatchedJob[];
+  failed(name?: string): Array<{ job: DispatchedJob, error: Error }>;
+  reset(): void;
+}
+/**
+ * Queue testing helper class
+ */
+export declare class QueueTester {
+  constructor();
+  dispatch<T>(name: string, data: T, options?: Partial<JobOptions>): this;
+  push<T>(name: string, data: T, options?: Partial<JobOptions>): this;
+  assertDispatched(name: string, callback?: (job: DispatchedJob) => boolean): this;
+  assertNotDispatched(name: string): this;
+  assertDispatchedTimes(name: string, times: number): this;
+  assertNothingDispatched(): this;
+  dispatched(name?: string): DispatchedJob[];
+  reset(): this;
+  cleanup(): void;
+}

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+import type { QueueOption } from '@stacksjs/types';
+/**
+ * Affected-row count from an UPDATE result, across every shape the query
+ * builders in the wild return: Kysely's `numUpdatedRows` bigint,
+ * bun-query-builder's `{ changes, lastInsertRowid }` object, or a plain
+ * number. `Number({...})` is NaN, and `NaN > 0` is false — which made the
+ * queue worker's CAS claim treat every SUCCESSFUL reservation as lost:
+ * jobs were reserved then discarded, one per poll, forever, with nothing
+ * processed and nothing logged (found on stacksjs/status production,
+ * 2026-07-04, 1,600+ jobs stuck reserved).
+ */
+export declare function updatedRowCount(result: unknown): number;
+export declare function storeJob(name: string, options: QueueOption): Promise<void>;

package/dist/worker.d.ts

@@ -0,0 +1,40 @@
+import type { Result } from '@stacksjs/error-handling';
+/**
+ * Start the queue processor (worker)
+ * This is the main function called by `buddy queue:work`
+ */
+export declare function startProcessor(queueName?: string, options?: { concurrency?: number }): Promise<Result<undefined, Error>>;
+/**
+ * Stop the queue processor, draining in-flight jobs within a grace
+ * window before returning. The `signalled to stop` flag stops the
+ * polling loop from claiming new jobs; any handler that's currently
+ * mid-execution gets up to `graceMs` to finish.
+ *
+ * `graceMs` defaults to 10s (matches the buddy CLI's existing
+ * SIGTERM → SIGKILL window). Pass 0 to skip the wait entirely
+ * (test runs, CI).
+ *
+ * When the grace window expires with jobs still active, the function
+ * resolves anyway — the reservation-sweep (Q-2) will requeue them on
+ * the next worker startup. The alternative (hanging the process
+ * forever) is worse than the requeue cost.
+ *
+ * See stacksjs/stacks#1872 Q-10.
+ */
+export declare function stopProcessor(options?: { graceMs?: number }): Promise<void>;
+/**
+ * Retry all failed jobs
+ */
+export declare function executeFailedJobs(): Promise<void>;
+/**
+ * Retry a specific failed job
+ */
+export declare function retryFailedJob(id: number): Promise<void>;
+/**
+ * Get the count of currently active (processing) jobs
+ */
+export declare function getActiveJobCount(): number;
+/**
+ * Check if the worker is currently running
+ */
+export declare function isWorkerRunning(): boolean;

package/package.json

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