nats.js

JetStream is a persistence engine that provides streaming, message, and worker queues with At-Least-Once semantics.

Streams

JetStream stores messages in streams. A stream defines how messages are stored and sets limits (e.g., duration of persistence or maximum number of messages). To store a message, you publish it to a subject associated with a stream.

Consumers

Messages are replayed from a stream by consumers. A consumer configuration determines which messages are presented to a client, such as:

• Filtering by specific sequence numbers or time ranges.
• Filtering by specific subjects.
• Defining acknowledgement policies (e.g., whether the server requires an ACK).
• Controlling the rate at which messages are delivered.

When using NATS in frameworks like React, Vue, or Svelte, follow these patterns:

1. Avoid local state for connections: Do not wrap the NATS connection in component-local useState or useEffect. This causes the connection to re-run on every render.
2. Use Singleton Promises: Create a module-scope singleton promise for the connection.
3. Leverage Async Primitives: Consume the connection promise using the framework's built-in async handling, such as React <Suspense>, Vue <Suspense>, or Svelte {#await} blocks.

The framework automatically assigns a unique ID to every service instance. While multiple instances may share the same name, they will have unique IDs.

You can discover running services by creating a monitoring client via svc.client(). This client allows you to perform operations like ping(), stats(), and info(). All these operations return iterators describing the services found. You can filter these operations by service name or a specific instance id.

const m = svc.client();

// Ping all services
for await (const s of await m.ping()) {
  console.log(s.id);
}

// Get stats for all services
await m.stats();

// Get info for all services
await m.info();

// Filter stats by service name
await m.stats("max");

// Filter stats by a specific instance ID
await m.stats("max", id);

NATS client functionality is organized into two distinct layers:

Core client (nats.js)

• Purpose: Direct, lightweight, and performance-oriented API mapping to nats-server capabilities.
• Characteristics: High cross-client parity (matches Rust, Go, etc.), stable versioning, and conservative breaking changes.
• Use when: You need protocol-level coverage (auth, TLS, reconnection) or standard NATS features (publish, subscribe, JetStream, Service API).

Orbit (orbit.js)

• Purpose: High-level, opinionated abstractions built on top of the core client.
• Characteristics: JavaScript-idiomatic APIs, faster iteration/API churn, and per-module versioning.
• Use when: You want helpers, sugar over core APIs, KV codecs, distributed counters, or experimental patterns.

The core module provides the fundamental NATS functionality for JavaScript clients, including:

• Connection management, authentication, and lifecycle handling.
• NATS protocol implementation for messaging (publish, subscribe, and request/reply).

It is designed to be runtime-agnostic. While native transport modules (like node or deno) provide a connect function that returns a NatsConnection, the core module itself can be used as a dependency for building other NATS-compatible libraries (e.g., @nats-io/jetstream) without binding to a specific runtime.

All JetStream messages are JsMsg instances, which wrap a standard NATS Msg. They provide metadata like seq (sequence) and redelivered status. You must manage the message lifecycle using one of the following methods:

• ack(): Successfully processed the message.
• nak(millis?): Failed to process; tells the server to resend. If millis is provided, the server waits that long before resending (requires server v2.7.1+).
• working(): Informs the server you are still processing to prevent premature redelivery.
• term(): Failed to process and instructs the server never to send this message to any consumer again.

When using NATS in frameworks like React, Next.js, or Vue, follow these best practices:

1. Avoid local state for connections: Do not wrap the NATS connection in component-local useState or useEffect. This causes the connection to re-run on every render.
2. Use a singleton promise: Create a module-scope singleton promise for the connection.
3. Use async primitives: Consume the connection promise using the framework's built-in async resource handling, such as React <Suspense>, Vue <Suspense>, or Svelte {#await}.

For Next.js, it is recommended to load the NATS client via next/dynamic with ssr: false because WebSockets only run in the browser.

When using NATS in modern web frameworks, do not wrap the connection in component-local useState or useEffect. This can cause the connection to re-run on every render.

Recommended Pattern: Create a module-scope singleton promise for the connection and consume it using the framework's built-in async-resource primitives, such as:

• React <Suspense> or the use hook
• Vue <Suspense>
• Svelte {#await}
• Next.js streaming and loading.tsx

NATS.js supports two ways to handle messages:

Async Iterators (Recommended)

Using for await (const m of sub) is the modern approach. It simplifies complex coordination and makes code easier to maintain.

• Implication: Async subscriptions buffer inbound messages. Processing is queued in a microtask queue, which may increase latency but provides better liveliness.

Callbacks

By providing a callback in SubscriptionOptions, you use a traditional callback-based approach.

• Implication: This allows processing a subscription in the same event loop that dispatched the message, reducing latency.
• Note: When a callback is used, the subscription iterator will never yield messages; the callback intercepts everything.