skills/docs/foundation/flow/queue/src/errors/queue-error.md

queue-error

(no submodules)

Purpose

Defines the error hierarchy for @suaveplan/queue. All errors extend SuaveplanError via a shared QueueError base class, giving them stable numeric codes, cause-chain traversal, and OTel span-event integration from @suaveplan/error.

Error codes are registered once via defineCodes("queue", {...}) so each error can be identified numerically in distributed tracing, log pipelines, and wire protocols without relying on class names that may be minified.

Features

• QueueError — base class for the entire queue error family
• QueueFullError — capacity exceeded on enqueue
• QueueJobNotFoundError — job ID lookup failure (includes optional jobId in message)
• QueueWorkerAbortedError — worker stopped via AbortSignal
• QueueHandlerFailedError — job handler threw an unhandled error
• QueueInvalidStateError — illegal job state transition (includes from/to in message)
• QueueDeadLetterFailedError — dead-letter enqueue failure
• All codes under the "queue" domain namespace via defineCodes

Usage: Basic Example

import { QueueFullError, QueueHandlerFailedError } from "@suaveplan/queue/errors/queue-error";

try {
  throw new QueueFullError({ message: "Memory queue at capacity" });
} catch (err) {
  if (err instanceof QueueFullError) {
    console.error("Queue full, code:", err.code); // stable numeric code
  }
}

Usage: Advanced Example

import {
  QueueInvalidStateError,
  QueueJobNotFoundError,
  QUEUE_CODES,
} from "@suaveplan/queue/errors/queue-error";

// State transition with context
throw new QueueInvalidStateError({
  from: "completed",
  to: "processing",
});

// Job lookup failure with ID
const err = new QueueJobNotFoundError({ jobId: "job_abc123" });
console.log(err.message); // "Job not found: job_abc123"
console.log(err.code === QUEUE_CODES.QUEUE_JOB_NOT_FOUND); // true

API Reference

QUEUE_CODES

Stable code map: QUEUE_FULL=1, QUEUE_JOB_NOT_FOUND=2, QUEUE_WORKER_ABORTED=3, QUEUE_HANDLER_FAILED=4, QUEUE_INVALID_STATE=5, QUEUE_DEAD_LETTER_FAILED=6.

QueueError

Base class. Extends SuaveplanError, domain "queue".

QueueFullError(options?)

• options.message? — override default message
• options.cause? — wrapped cause

QueueJobNotFoundError(options?)

• options.jobId? — included in default message

QueueWorkerAbortedError(options?)

Thrown when AbortSignal fires during worker processing.

QueueHandlerFailedError(options?)

Wraps the original handler error as cause.

QueueInvalidStateError(options?)

• options.from? / options.to? — state labels included in default message

QueueDeadLetterFailedError(options?)

Thrown when the dead-letter enqueue itself fails.

Implementation Notes

defineCodes from @suaveplan/error allocates a namespace-prefixed numeric code map. This approach prevents code collisions across packages and survives minification. Each error class declares its code as both a static and instance property to support instanceof checks and code-based switching.