# queue-error

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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.