Skip to main content

Events reference

Events are emitted on the PortQueue client and observed with pq.on / once / off. Every listener receives one typed payload object (named fields, no positional args). Fan-out is non-blocking — the bus never waits for listeners. There is no WorkerEvent; all events are global on the client.

import { PortQueueEvent } from '@portqueue/core';

const off = pq.on(PortQueueEvent.JOB_FAILED, ({ queue, jobId, error, retryAttempt }) => {
  metrics.failures.inc({ queue });
}, { queue: 'orders' }); // optional queue filter (typed to TQueues)

off(); // unsubscribe
pq.once(PortQueueEvent.CLIENT_STARTED, () => {});

PortQueueEvent​

Client / lifecycle

  • CLIENT_STARTED, CLIENT_STOPPING, CLIENT_STOPPED
  • MIGRATION_APPLIED — { from, to }
  • ERROR — { error, source } — any swallowed internal error surfaces here, so nothing is truly silent. Subscribe to this in production.

Job lifecycle

  • JOB_ADDED — { jobId, queue, deduplicated }
  • JOB_ACTIVE — { jobId, queue, retryAttempt, instanceKey }
  • JOB_COMPLETED — { jobId, queue, returnValue, durationSeconds }
  • JOB_FAILED — failure after attempts exhausted
  • JOB_RETRYING — scheduled for another attempt
  • JOB_STALLED — lock lapsed, reclaimable
  • JOB_EXPIRED, JOB_CANCELLED, JOB_REMOVED

Schedules

  • SCHEDULE_CREATED, SCHEDULE_UPDATED, SCHEDULE_REMOVED, SCHEDULE_FIRED

Queue & processing

  • QUEUE_PAUSED, QUEUE_RESUMED
  • QUEUE_REMOVED — { queue } — fired by pq.removeQueue
  • WORKER_STARTED, WORKER_STOPPED — { queue } — this process started or stopped claiming that queue: a createQueue with a handler began its claim loop, or shutdown ended it.

Instances

Emitted as instances are paused, resumed, or removed from the fleet — see Scale horizontally, which relies on these to track fleet membership.

  • INSTANCE_PAUSED — { instanceKey } — fired by pq.pauseInstance
  • INSTANCE_RESUMED — { instanceKey } — fired by pq.resumeInstance
  • INSTANCE_REMOVED — { instanceKey } — fired by pq.removeInstance

System pressure

  • SYSTEM_PRESSURE_HIGH, SYSTEM_PRESSURE_NORMAL
Events can't change anything

Events are for observation only. To mutate or block an operation, use a hook.