Event & Error Handling

Each Background queue, extends from the EventTarget class. That means you can add event listeners and listen for the events that are happening in your jobs.

QueueEvent Class

Queues fire an event called QueueEvent. Here is the actual implementation from the source code.

export interface QueueEventData {
  job?: Job;
  status?: JobStatus;
  message?: string;
}

// Extend standard Event with our custom data
export class QueueEvent extends Event {
  public readonly data: QueueEventData;
  constructor(type: string, data: QueueEventData) {
    super(type);
    this.data = data;
  }
}

// Add type declaration for event listeners to fix TypeScript errors
declare global {
  interface EventListenerObject {
    handleEvent(evt: Event | QueueEvent): void;
  }

  interface EventTarget {
    addEventListener(
      type: string,
      callback: EventListener | ((evt: QueueEvent) => void),
      options?:
        | boolean
        | { capture?: boolean; once?: boolean; passive?: boolean },
    ): void;
  }
}

Events

Currently queues fire multiple types of events. Here is the list of the fired events.

• completed - Gets fired when a job is completed.
• failed - Gets fired when a job fails.
• scheduled - Gets fired when a new job scheduled.
• polling-interval-updated - Gets fired when the polling interval is updated.
• polling-interval-error - Gets fired when an error occurs during polling interval update.
• scheduled-repeat-error - Gets fired when an error occurs during repeatable job next schedule.
• calculate-next-execution-time-error - Gets fired when an error occurs during the next execution time calculation.

Listening For Events

Here is the implementation for the event listening.

const storage = new InMemoryJobStorage();
const queue = new JobQueue(storage, {
  concurrency: 2,
  maxRetries: 3,
  name: "test-queue",
  processingInterval: 1000,
});

const jobHandler = async (data: { message: string }) => {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  return data;
};

const eventHandler = (event: QueueEvent) => {
  console.log(event.type);
  console.log(event.data);
};

queue.register("test-job", jobHandler);

queue.add("test-job",{message:"example job"});

// In a real implementation you may want to create seperate event handlers.
queue.addEventListener("completed", eventHandler);
queue.addEventListener("failed",eventHandler);