JobOptions

The JobOptions interface defines the options for creating a new job in the queue.

Fields

• jobType: string — The type of the job.

• payload: any — The payload for the job, type-safe per job type.

• maxAttempts?: number — Maximum number of attempts for this job (default: 3).

• priority?: number — Priority of the job (higher runs first, default: 0).

• runAt?: Date | null — When to run the job (default: now).

• timeoutMs?: number — Timeout for this job in milliseconds. If not set, uses the processor default or unlimited.

• forceKillOnTimeout?: boolean — If true, the job will be forcefully terminated (using Worker Threads) when timeout is reached. If false (default), the job will only receive an AbortSignal and must handle the abort gracefully.

  ⚠️ Runtime Requirements: This option requires Node.js and will not work in Bun or other runtimes without worker thread support. See Force Kill on Timeout for details.

• tags?: string[] — Tags for this job. Used for grouping, searching, or batch operations.

• idempotencyKey?: string — Optional idempotency key. When provided, ensures that only one job exists for a given key. If a job with the same key already exists, addJob returns the existing job's ID instead of creating a duplicate. See Idempotency for details.

• deadLetterJobType?: string — Optional dead-letter destination job type. When the job exhausts retries, DataQueue creates a new pending job in this job type with an envelope payload containing source metadata, original payload, and failure context.

Example

const job = {
  jobType: 'email',
  payload: { to: 'user@example.com', subject: 'Hello' },
  maxAttempts: 5,
  priority: 10,
  runAt: new Date(Date.now() + 60000), // run in 1 minute
  timeoutMs: 30000, // 30 seconds
  forceKillOnTimeout: false, // Use graceful shutdown (default)
  tags: ['welcome', 'user'], // tags for grouping/searching
  idempotencyKey: 'welcome-email-user-123', // prevent duplicate jobs
  deadLetterJobType: 'email_dead_letter', // route exhausted failures
};