# NatsQueueBridge API

Strict QueueBridge implementation backed by NATS JetStream streams and KV.

---
Canonical: /handbook/api/classes/_purista_nats-queue-bridge.NatsQueueBridge/
Source: NatsQueueBridge.impl.ts
Format: Markdown for agents
---

Strict QueueBridge implementation backed by NATS JetStream streams and KV.

Package: `@purista/nats-queue-bridge`

## Signature

```typescript
class NatsQueueBridge
```

## Examples

```typescript
import { NatsQueueBridge } from '@purista/nats-queue-bridge'

const queueBridge = new NatsQueueBridge({
  connectionOptions: { servers: 'nats://localhost:4222' },
  defaultMaxAttempts: 5,
})

await queueBridge.start()
```

```typescript
const first = await queueBridge.enqueue({
  queueName: 'billing.invoice-email',
  payload: { invoiceId: 'inv_123' },
  idempotencyKey: 'invoice-email:inv_123',
})

const duplicate = await queueBridge.enqueue({
  queueName: 'billing.invoice-email',
  payload: { invoiceId: 'inv_123' },
  idempotencyKey: 'invoice-email:inv_123',
})

first.jobId === duplicate.jobId
```

## Members

### Constructors

- `new constructor(options: NatsQueueBridgeOptions)` — Creates a NATS JetStream queue bridge with the provided options.

### Properties

- `capabilities: QueueBridgeCapabilities` — Queue capabilities supported by this JetStream bridge.
- `instanceId: `template`` — Unique bridge instance identifier for diagnostics and lease ownership.
- `name: "NatsQueueBridge"` — Stable bridge name reported to PURISTA runtime diagnostics.

### Methods

- `ack(queueName: string, leaseId: string): Promise<void>` — Acknowledges successful processing and removes the local lease tracking.
- `destroy(): Promise<void>` — Drains and closes the NATS connection and clears local lease/consumer caches.
- `enqueue(options: QueueEnqueueOptions<unknown, unknown>): Promise<QueueEnqueueResult>` — Enqueues a job, optionally scheduled for later delivery.
- `extendLease(queueName: string, leaseId: string, extensionMs: number): Promise<void>` — Extends a currently tracked lease.
- `inspectLeases(queueName: string, options?: QueueDeadLetterListOptions): Promise<QueueLeaseInspectionRecord[]>` — Returns leases currently tracked by this bridge instance.
- `isHealthy(): Promise<boolean>` — Performs a lightweight connection flush to verify broker health.
- `isReady(): Promise<boolean>` — Indicates whether the bridge has an open NATS connection.
- `leaseNext(queueName: string, options?: QueueLeaseOptions): Promise<QueueLease | undefined>` — Leases the next available job from a queue.
- `metrics(queueName: string): Promise<QueueMetrics>` — Returns broker-derived queue metrics for pending, in-flight, and
dead-lettered jobs.
- `moveToDeadLetter(queueName: string, message: QueueMessage, reason?: string): Promise<void>` — Moves a message directly to the queue dead-letter stream.
- `nack(queueName: string, leaseId: string, request: QueueRetryRequest): Promise<void>` — Retries or dead-letters a leased job.
- `peekDeadLetter(queueName: string, options?: QueueDeadLetterListOptions): Promise<QueueMessage[]>` — Reads dead-lettered jobs without redriving or deleting them.
- `purgeDeadLetter(queueName: string): Promise<number>` — Deletes all jobs in the queue dead-letter stream and returns the deleted count.
- `redriveDeadLetter(queueName: string, options?: QueueDeadLetterRedriveOptions): Promise<number>` — Redrives dead-lettered jobs back to the pending queue and removes them
from the dead-letter stream.
- `start(): Promise<void>` — Connects to NATS and initializes JetStream clients.