0
# NATS
1
2
NATS is a high-performance, lightweight cloud-native messaging system for distributed applications and microservices. The Node.js client provides full TypeScript support with async/await patterns, automatic reconnection handling, and comprehensive features including core pub/sub messaging, JetStream for persistence and streaming, Key-Value stores, Object stores, and Service discovery APIs.
3
4
## Package Information
5
6
- **Package Name**: nats
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install nats`
10
11
## Core Imports
12
13
```typescript
14
import { connect, StringCodec, JSONCodec } from "nats";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { connect, StringCodec, JSONCodec } = require("nats");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { connect, StringCodec } from "nats";
27
28
// Connect to NATS server
29
const nc = await connect({ servers: ["nats://localhost:4222"] });
30
const sc = StringCodec();
31
32
// Simple publish/subscribe
33
const sub = nc.subscribe("news.updates");
34
(async () => {
35
for await (const m of sub) {
36
console.log(`Received: ${sc.decode(m.data)}`);
37
}
38
})();
39
40
// Publish a message
41
nc.publish("news.updates", sc.encode("Hello NATS!"));
42
43
// Request/reply pattern
44
const response = await nc.request("time", sc.encode(""));
45
console.log(`Time: ${sc.decode(response.data)}`);
46
47
// Clean shutdown
48
await nc.drain();
49
```
50
51
## Architecture
52
53
NATS is built around several key components:
54
55
- **Core Connection**: Primary `NatsConnection` interface providing pub/sub messaging with wildcards, queues, and request/reply patterns
56
- **JetStream**: Persistent messaging system with streams, consumers, and acknowledgments for reliable delivery
57
- **Key-Value Store**: High-level abstraction built on JetStream for key-value operations with history and watching
58
- **Object Store**: File-like storage system for larger payloads with metadata and linking
59
- **Services API**: Service discovery and monitoring framework for building NATS-based microservices
60
- **Transport Layer**: Node.js-optimized transport with automatic reconnection, TLS support, and connection draining
61
62
## Capabilities
63
64
### Connection Management
65
66
Core NATS connection functionality including authentication, TLS, reconnection handling, and connection lifecycle management.
67
68
```typescript { .api }
69
function connect(opts?: ConnectionOptions): Promise<NatsConnection>;
70
71
interface ConnectionOptions {
72
servers?: string[] | string;
73
port?: number;
74
user?: string;
75
pass?: string;
76
token?: string;
77
authenticator?: Authenticator | Authenticator[];
78
reconnect?: boolean;
79
maxReconnectAttempts?: number;
80
reconnectTimeWait?: number;
81
timeout?: number;
82
pingInterval?: number;
83
maxPingOut?: number;
84
name?: string;
85
verbose?: boolean;
86
pedantic?: boolean;
87
tls?: TlsOptions | null;
88
ignoreClusterUpdates?: boolean;
89
inboxPrefix?: string;
90
noEcho?: boolean;
91
debug?: boolean;
92
noRandomize?: boolean;
93
waitOnFirstConnect?: boolean;
94
}
95
```
96
97
[Connection Management](./connection.md)
98
99
### Core Messaging
100
101
Essential pub/sub messaging operations including publishing, subscribing, request/reply patterns, and message handling with full wildcard support.
102
103
```typescript { .api }
104
interface NatsConnection {
105
publish(subject: string, payload?: Payload, options?: PublishOptions): void;
106
subscribe(subject: string, opts?: SubscriptionOptions): Subscription;
107
request(subject: string, payload?: Payload, opts?: RequestOptions): Promise<Msg>;
108
requestMany(subject: string, payload?: Payload, opts?: Partial<RequestManyOptions>): Promise<AsyncIterable<Msg>>;
109
}
110
111
interface Msg {
112
subject: string;
113
data: Uint8Array;
114
reply?: string;
115
headers?: MsgHdrs;
116
respond(data?: Payload, opts?: PublishOptions): boolean;
117
}
118
```
119
120
[Core Messaging](./messaging.md)
121
122
### JetStream
123
124
Persistent messaging system providing streams for message storage, consumers for reliable delivery, and advanced features like deduplication and retention policies.
125
126
```typescript { .api }
127
interface JetStreamClient {
128
publish(subj: string, payload?: Payload, options?: Partial<JetStreamPublishOptions>): Promise<PubAck>;
129
subscribe(subject: string, opts?: Partial<ConsumerOptsBuilder>): Promise<JetStreamSubscription>;
130
pullSubscribe(subject: string, opts?: Partial<ConsumerOptsBuilder>): Promise<JetStreamPullSubscription>;
131
}
132
133
interface JetStreamManager {
134
streams: StreamAPI;
135
consumers: ConsumerAPI;
136
getAccountInfo(): Promise<JetStreamAccountStats>;
137
}
138
```
139
140
[JetStream](./jetstream.md)
141
142
### Key-Value Store
143
144
High-level key-value abstraction with history tracking, watch capabilities, and automatic conflict resolution built on JetStream streams.
145
146
```typescript { .api }
147
interface KV {
148
get(key: string): Promise<KvEntry | null>;
149
put(key: string, value: Uint8Array, opts?: Partial<KvPutOptions>): Promise<number>;
150
delete(key: string, opts?: Partial<KvDeleteOptions>): Promise<void>;
151
watch(opts?: Partial<KvWatchOptions>): Promise<QueuedIterator<KvEntry>>;
152
history(key: string): Promise<QueuedIterator<KvEntry>>;
153
}
154
```
155
156
[Key-Value Store](./kv-store.md)
157
158
### Object Store
159
160
File-like storage system for larger payloads with metadata, chunking, and linking capabilities for complex data structures.
161
162
```typescript { .api }
163
interface ObjectStore {
164
put(meta: ObjectStoreMeta, payload: AsyncIterable<Uint8Array>): Promise<ObjectInfo>;
165
get(name: string): Promise<ObjectResult | null>;
166
info(name: string): Promise<ObjectInfo | null>;
167
list(): Promise<QueuedIterator<ObjectInfo>>;
168
delete(name: string): Promise<boolean>;
169
}
170
```
171
172
[Object Store](./object-store.md)
173
174
### Services API
175
176
Service discovery and monitoring framework enabling service registration, health checks, and observability for NATS-based microservices.
177
178
```typescript { .api }
179
interface ServicesAPI {
180
add(config: ServiceConfig): Promise<Service>;
181
client(opts?: RequestManyOptions, prefix?: string): ServiceClient;
182
}
183
184
interface ServiceClient {
185
ping(name?: string, id?: string): Promise<QueuedIterator<ServiceIdentity>>;
186
stats(name?: string, id?: string): Promise<QueuedIterator<ServiceStats>>;
187
info(name?: string, id?: string): Promise<QueuedIterator<ServiceInfo>>;
188
}
189
```
190
191
[Services API](./services.md)
192
193
## Core Types
194
195
```typescript { .api }
196
type Payload = Uint8Array | string;
197
198
interface Msg {
199
subject: string;
200
data: Uint8Array;
201
reply?: string;
202
headers?: MsgHdrs;
203
respond(data?: Payload, opts?: PublishOptions): boolean;
204
}
205
206
interface Subscription {
207
unsubscribe(max?: number): void;
208
drain(): Promise<void>;
209
isClosed(): boolean;
210
getSubject(): string;
211
getReceived(): number;
212
getProcessed(): number;
213
getPending(): number;
214
getID(): number;
215
getMax(): number | undefined;
216
}
217
218
interface NatsError extends Error {
219
name: string;
220
message: string;
221
code: string;
222
chainedError?: Error;
223
api_error?: ApiError;
224
}
225
226
interface Stats {
227
inBytes: number;
228
outBytes: number;
229
inMsgs: number;
230
outMsgs: number;
231
}
232
233
interface ServerInfo {
234
server_id: string;
235
server_name: string;
236
version: string;
237
proto: number;
238
host: string;
239
port: number;
240
headers?: boolean;
241
max_payload: number;
242
jetstream?: boolean;
243
auth_required?: boolean;
244
tls_required?: boolean;
245
tls_available?: boolean;
246
}
247
```