@stacksjs/queue 0.70.23 → 0.70.25

package/dist/src/job.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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' })
+ * ```
+ */
+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()`. */
+  async dispatch: (name: string, payload?: any) => Promise<void>;
+  /** Dispatch only if `condition` is truthy. */
+  async dispatchIf: (condition: boolean, name: string, payload?: any) => Promise<void>;
+  /** Dispatch unless `condition` is truthy. */
+  async dispatchUnless: (condition: boolean, name: string, payload?: any) => Promise<void>;
+  /** Run the job synchronously, bypassing the queue. */
+  async dispatchNow: (name: string, payload?: any) => Promise<void>;
+  /** Schedule the job to run after `seconds` of delay. */
+  dispatchAfter: (seconds: number, name: string, payload?: any) => JobBuilder
+};
+/**
+ * Options for job dispatch
+ */
+export declare interface JobDispatchOptions {
+  queue?: string
+  delay?: number
+  tries?: number
+  timeout?: number
+  backoff?: number[]
+  context?: any
+}
+/**
+ * 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;
+  dispatch(): Promise<void>;
+  dispatchIf(condition: boolean): Promise<void>;
+  dispatchUnless(condition: boolean): Promise<void>;
+  dispatchNow(): Promise<void>;
+}

package/dist/src/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/src/scheduler.d.ts

@@ -0,0 +1,52 @@
+import { type DiscoveredJob } from './discovery';
+/**
+ * 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
+}

package/dist/src/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/src/worker.d.ts

@@ -0,0 +1,26 @@
+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
+ */
+export declare function stopProcessor(): 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

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/queue",
   "type": "module",
-  "version": "0.70.23",
-  "description": "The Stacks Queue system.",
+  "version": "0.70.25",
+  "description": "The Stacks Queue system powered by bun-queue.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/queue#readme",
@@ -18,9 +20,10 @@
   },
   "keywords": [
     "queue",
-    "bee-queue",
+    "bun-queue",
     "redis",
-    "upstash",
+    "job",
+    "worker",
     "stacks",
     "framework",
     "typescript",
@@ -28,21 +31,30 @@
   ],
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "@stacksjs/bun-queue": "^0.1.0"
+  },
   "devDependencies": {
-    "@stacksjs/development": "0.70.22"
+    "better-dx": "^0.2.12"
   }
 }

package/dist/action.d.ts

@@ -1,25 +0,0 @@
-import type { JobOptions } from '@stacksjs/types';
-
-export declare class Job {
-  name: JobOptions['name']
-  description: JobOptions['description']
-  action?: JobOptions['action']
-  handle?: JobOptions['handle']
-  rate: JobOptions['rate']
-  tries: JobOptions['tries']
-  backoff: JobOptions['backoff']
-  backoffConfig: JobOptions['backoffConfig']
-  enabled: JobOptions['enabled']
-
-  constructor({ name, description, handle, rate, tries, backoff, backoffConfig, action, enabled }: JobOptions) {
-    this.name = name
-    this.description = description
-    this.handle = handle
-    this.rate = rate
-    this.action = action
-    this.tries = tries
-    this.backoff = backoff
-    this.backoffConfig = backoffConfig
-    this.enabled = enabled
-  }
-}

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from './action'
-export * from './job'
-export * from './process'

package/dist/job.d.ts

@@ -1,199 +0,0 @@
-import type { QueueOption } from '@stacksjs/types';
-
-declare const queueDriver: 'database';
-declare interface JobConfig {
-  handle?: (payload?: any) => Promise<void>
-  action?: string | (() => Promise<void>)
-}
-declare interface Dispatchable {
-  dispatch: () => Promise<void>
-  dispatchNow: () => Promise<void>
-  delay: (seconds: number) => this
-  afterResponse: () => this
-  chain: (jobs: Dispatchable[]) => this
-  onQueue: (queue: string) => this
-}
-export declare function runJob(name: string, options: QueueOption): Promise<void>;
-export declare class Queue implements Dispatchable {
-  protected options: QueueOption = {}
-
-  constructor(
-    protected name: string,
-    protected payload?: any,
-  ) { }
-
-  async dispatch(): Promise<void> {
-    const queueName = this.options.queue || 'default'
-
-    const jobPayload = this.createJobPayload(queueName)
-
-    if (this.isQueuedDriver()) {
-      await this.storeQueuedJob(jobPayload)
-      return
-    }
-
-    if (this.options.afterResponse) {
-      this.deferAfterResponse()
-      return
-    }
-
-    if (this.options.delay) {
-      this.deferWithDelay()
-      return
-    }
-
-    await this.runJobImmediately(jobPayload)
-  }
-
-  private isQueuedDriver(): boolean {
-    return ['database', 'redis'].includes(queueDriver)
-  }
-
-  private createJobPayload(queueName: string): QueueOption {
-    return {
-      queue: queueName,
-      payload: this.payload,
-      context: this.options.context,
-      maxTries: this.options.maxTries,
-      timeout: this.options.timeout,
-      backoff: this.options.backoff,
-      delay: this.options.delay,
-    }
-  }
-
-  private async storeQueuedJob(jobPayload: any): Promise<void> {
-    await storeJob(this.name, jobPayload)
-  }
-
-  private deferAfterResponse(): void {
-    process.on('beforeExit', async () => {
-      await this.dispatchNow()
-    })
-  }
-
-  private deferWithDelay(): void {
-    setTimeout(async () => {
-      await this.dispatchNow()
-    }, this.options.delay || 0)
-  }
-
-  private async runJobImmediately(jobPayload: any): Promise<void> {
-    try {
-      await runJob(this.name, jobPayload)
-      await this.runChainedJobs()
-    }
-    catch (error) {
-      log.error(`Failed to dispatch job ${this.name}:`, error)
-      throw error
-    }
-  }
-
-  private async runChainedJobs(): Promise<void> {
-    if (!this.options.chainedJobs?.length)
-      return
-
-    for (const job of this.options.chainedJobs) {
-      await job.dispatch()
-    }
-  }
-
-  async dispatchNow(): Promise<void> {
-    try {
-      await runJob(this.name, {
-        payload: this.payload,
-        context: this.options.context,
-        immediate: true,
-      })
-
-      if (this.options.chainedJobs?.length) {
-        for (const job of this.options.chainedJobs) {
-          await job.dispatchNow()
-        }
-      }
-    }
-    catch (error) {
-      log.error(`Failed to execute job ${this.name}:`, error)
-      throw error
-    }
-  }
-
-  delay(seconds: number): this {
-    this.options.delay = seconds
-    return this
-  }
-
-  onQueue(queue: string): this {
-    this.options.queue = queue
-    return this
-  }
-
-  chain(jobs: Dispatchable[]): this {
-    this.options.chainedJobs = jobs
-    return this
-  }
-
-  afterResponse(): this {
-    this.options.afterResponse = true
-    return this
-  }
-
-  tries(count: number): this {
-    this.options.maxTries = count
-    return this
-  }
-
-  timeout(seconds: number): this {
-    this.options.timeout = seconds
-    return this
-  }
-
-  backoff(attempts: number[]): this {
-    this.options.backoff = attempts
-    return this
-  }
-
-  withContext(context: any): this {
-    this.options.context = context
-    return this
-  }
-}
-export declare class JobFactory {
-  static make(name: string, payload?: any): Queue {
-    return new Queue(name, payload)
-  }
-
-  static dispatch(name: string, payload?: any): Queue {
-    const job = new Queue(name, payload)
-    job.dispatch()
-    return job
-  }
-
-  static async dispatchNow(name: string, payload?: any): Promise<void> {
-    await new Queue(name, payload).dispatchNow()
-  }
-
-  static later(delay: number, name: string, payload?: any): Queue {
-    return new Queue(name, payload).delay(delay)
-  }
-
-  static chain(jobs: Queue[]): Queue {
-    const firstJob = jobs[0]
-    return firstJob.chain(jobs.slice(1))
-  }
-}
-export declare function job(name: string, payload?: any): Queue;
-export declare function processOrder(payload, context): void;
-
-export default {
-  async handle() {
-  }
-};
-export default {
-  action: 'SendWelcomeEmail'
-};
-export default {
-  action: async () => {
-  }
-};
-export default async function(payload, context) {
-};

package/dist/process.d.ts

@@ -1,24 +0,0 @@
-import type { JitterConfig, JobOptions } from '@stacksjs/types';
-import type { JobModel } from '../../../orm/src/models/Job';
-
-declare interface QueuePayload {
-  path: string
-  name: string
-  maxTries: number
-  timeOut: number | null
-  timeOutAt: Date | null
-  params: any
-  classPayload: string
-}
-export declare function processJobs(queue: string | undefined): Promise<Ok<string, never>>;
-export declare function executeFailedJobs(): Promise<void>;
-export declare function retryFailedJob(id: number): Promise<void>;
-declare function executeJobs(queue: string | undefined): Promise<void>;
-declare function enforceMaxDelay(maxDelay: number | undefined, delay: number): number;
-declare function addDelay(timestamp: number | undefined, currentAttempts: number, classPayload: JobOptions): number;
-declare function meilisecondsToSeconds(meiliseconds: number): number;
-declare function applyJitter(delay: number, jitterConfig: JitterConfig): number;
-declare function storeFailedJob(job: JobModel, exception: string): void;
-declare function now(): string;
-declare function updateJobAttempts(job: JobModel, currentAttempts: number, delay: number | null): Promise<void>;
-declare function timestampNow(): number;

package/dist/utils.d.ts

@@ -1,4 +0,0 @@
-import type { QueueOption } from '@stacksjs/types';
-
-export declare function storeJob(name: string, options: QueueOption): Promise<void>;
-declare function generateUnixTimestamp(secondsToAdd: number): number;