@stacksjs/queue 0.70.87 → 0.70.88

package/dist/job.d.ts

@@ -1,150 +0,0 @@
-/**
- * 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

@@ -1,70 +0,0 @@
-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

@@ -1,53 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,69 +0,0 @@
-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

@@ -1,74 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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;