# @purista/natsbridge API

Package for using a [NATS](https://nats.io/) broker as event bridge.  
The event bridge supports brokers with and without JetStream enabled.

---
Canonical: /handbook/api/modules/_purista_natsbridge/
Format: Markdown for agents
---

Package for using a [NATS](https://nats.io/) broker as event bridge.  
The event bridge supports brokers with and without JetStream enabled.

Package: `@purista/natsbridge`

## Signature

```typescript
@purista/natsbridge
```

## Examples

```typescript
import { NatsBridge } from '@purista/natsbridge'

// create and init our eventbridge
  const eventBridge = new NatsBridge()
  await eventBridge.start()
```

## Members

### Classes

- `class NatsBridge` — EventBridge implementation for NATS core messaging with optional JetStream.

### Type Aliases

- `type GetCommandTopicFn = (this: INatsBridge, address: EBMessageAddress) => string` — Function signature for building a NATS command subscription subject.
- `type GetSubscriptionTopicFn = (this: INatsBridge, subscription: Subscription) => string` — Function signature for building a NATS subscription subject filter.
- `type GetTopicNameFn = (this: INatsBridge, message: EBMessage) => string` — Function signature for building a NATS publish subject from a PURISTA message.
- `type INatsBridge = { connection: NatsConnection | undefined; sc: Codec<unknown> } & EventBridgeBaseClass<NatsBridgeConfig>` — Internal receiver shape used by exported NATS helper functions.
- `type IncomingMessageFunction = (this: INatsBridge, error: NatsError | null, msg: Msg | JsMsg) => Promise<void>` — NATS message handler bound to an INatsBridge instance.
- `type NatsBridgeConfig = Prettify<{ commandResponsePublishTwice: "always" | "eventOnly" | "eventAndError" | "never"; defaultConsumerFailureHandling: NatsConsumerFailureHandlingDefaults; defaultMessageExpiryInterval: number; durableSubscriptionMode: "strict" | "best-effort"; emptyTopicPartString: string; jetStreamAckWaitMs: number; ... } & ConnectionOptions>` — Configuration for NatsBridge.
- `type NatsConsumerFailureHandlingDefaults = void` — Default JetStream-backed subscription failure handling.
- `type PausedSubscriptionState = void` — Runtime pause metadata for a subscription consumer managed by the NATS bridge.
- `type RegisteredSubscription = void` — NATS or JetStream subscription tracked by the bridge for cleanup.

### Variables

- `const getCommandSubscriptionTopic: GetCommandTopicFn` — Builds the NATS subject used by command handlers for one service address.
- `const getSubscriptionTopic: GetSubscriptionTopicFn` — Builds the NATS subject filter for a PURISTA subscription definition.
- `const getTopicName: GetTopicNameFn` — Calculates the NATS topic name for a message which should be sent.
- `const puristaVersion: "3.0.1"` — The PURISTA package version embedded in the published runtime build.

### Functions

- `getDefaultNatsBridgeConfig(): { commandResponsePublishTwice: "always" | "eventOnly" | "eventAndError" | "never"; defaultConsumerFailureHandling: NatsConsumerFailureHandlingDefaults; defaultMessageExpiryInterval: number; durableSubscriptionMode: "strict" | "best-effort"; emptyTopicPartString: string; jetStreamAckWaitMs: number; ... }`
- `getQueueGroupName(prefix: string, address: EBMessageAddress): string`