JetStream Guide
JetStream is NATS' built-in persistence engine, providing durable message storage, key-value stores, and object storage.
Streams
Streams are the core persistence mechanism in JetStream. They store messages published to specific subjects.
Creating a Stream
- Navigate to your NATS cluster
- Click the JetStream tab
- Click Create Stream
- Configure the stream settings
Stream Configuration
| Field | Description |
|---|---|
| Name | Unique identifier for the stream |
| Subjects | Subject patterns to capture (e.g., orders.*) |
| Retention | How messages are retained |
| Storage | File (persistent) or Memory (fast) |
| Replicas | Number of copies for durability |
| Max Messages | Maximum number of messages |
| Max Bytes | Maximum storage size |
| Max Age | Message TTL using Go duration syntax (e.g., 168h, 24h) |
Retention Policies
Choose based on your use case:
Limits (Default)
Messages retained until limits are reached:
// Stream keeps messages until maxMsgs or maxBytes
const stream = await jsm.streams.add({
name: 'EVENTS',
subjects: ['events.*'],
retention: RetentionPolicy.Limits,
max_msgs: 1000000,
max_bytes: 1024 * 1024 * 1024 // 1GB
});
Best for: Event sourcing, audit logs, replay scenarios
Interest
Messages retained only while consumers exist:
const stream = await jsm.streams.add({
name: 'NOTIFICATIONS',
subjects: ['notifications.*'],
retention: RetentionPolicy.Interest
});
Best for: Real-time notifications, live updates
Work Queue
Each message delivered exactly once, then deleted:
const stream = await jsm.streams.add({
name: 'TASKS',
subjects: ['tasks.*'],
retention: RetentionPolicy.Workqueue
});
Best for: Background jobs, task processing
Subject Wildcards
NATS supports powerful subject wildcards:
| Pattern | Description | Example Matches |
|---|---|---|
* | Single token | orders.* → orders.created, orders.updated |
> | Multiple tokens | events.> → events.user.signup, events.order.created |
// Capture all order events
const stream = await jsm.streams.add({
name: 'ORDERS',
subjects: ['orders.*', 'orders.*.status']
});
// Capture all events
const stream = await jsm.streams.add({
name: 'ALL_EVENTS',
subjects: ['events.>']
});
Stream Operations
Publish Messages
const js = nc.jetstream();
// Publish with acknowledgment
const ack = await js.publish('orders.created', JSON.stringify({
orderId: 'order-123',
total: 99.99
}));
console.log(`Published to stream: ${ack.stream}, seq: ${ack.seq}`);
Get Stream Info
const stream = await js.streams.get('ORDERS');
const info = await stream.info();
console.log(`Messages: ${info.state.messages}`);
console.log(`Bytes: ${info.state.bytes}`);
console.log(`Consumers: ${info.state.consumer_count}`);
Purge Stream
// Delete all messages
await jsm.streams.purge('ORDERS');
// Delete messages older than 1 hour
await jsm.streams.purge('ORDERS', {
keep: 0,
seq: 0,
filter: 'orders.old'
});
Consumers
Consumers define how messages are delivered from streams.
Consumer Types
Push Consumer
Messages automatically delivered to subscribers:
const consumer = await js.consumers.get('ORDERS', 'order-processor');
// Messages pushed automatically
const messages = await consumer.consume();
for await (const msg of messages) {
await processOrder(JSON.parse(msg.data));
msg.ack();
}
Pull Consumer
Client explicitly fetches messages:
const consumer = await js.consumers.get('ORDERS', 'batch-processor');
// Pull a batch of messages
const messages = await consumer.fetch({ max_messages: 100 });
for await (const msg of messages) {
await processOrder(JSON.parse(msg.data));
msg.ack();
}
Durable vs Ephemeral
Durable Consumers
State persists across restarts:
const consumer = await jsm.consumers.add('ORDERS', {
durable_name: 'order-processor',
ack_policy: AckPolicy.Explicit
});
Use when: Processing must resume after restarts
Ephemeral Consumers
Temporary, deleted when inactive:
const consumer = await jsm.consumers.add('ORDERS', {
inactive_threshold: 300000000000 // 5 minutes in nanoseconds
});
Use when: Real-time monitoring, one-time processing
Consumer Configuration
| Field | Description |
|---|---|
| Durable Name | Persistent consumer name |
| Deliver Policy | Where to start (all, new, last, byStartSequence, byStartTime, lastPerSubject) |
| Ack Policy | How to acknowledge (none, all, explicit) |
| Max Deliver | Maximum delivery attempts |
| Filter Subject | Only receive matching messages |
Message Acknowledgment
Always acknowledge messages to prevent redelivery:
for await (const msg of messages) {
try {
await processMessage(msg);
msg.ack(); // Success
} catch (error) {
msg.nak(); // Request redelivery
// Or: msg.term() // Don't redeliver
}
}
Key-Value Stores
JetStream provides distributed key-value storage.
Creating a KV Store
- Go to your NATS cluster
- Navigate to Key-Value in JetStream tab
- Click Create KV Store
KV Configuration
| Field | Description |
|---|---|
| Name | Store name |
| History | Number of revisions to keep per key |
| TTL | Time-to-live for entries |
| Max Value Size | Maximum value size in bytes |
| Max Bytes | Total storage limit |
| Replicas | Number of copies |
KV Operations
Set Values
const kv = await js.views.kv('CONFIG');
// Set a value
await kv.put('app.theme', 'dark');
await kv.put('app.language', 'en');
// Set with JSON
await kv.put('user.preferences', JSON.stringify({
notifications: true,
timezone: 'UTC'
}));
Get Values
// Get current value
const entry = await kv.get('app.theme');
console.log(entry.string()); // 'dark'
// Get all keys
const keys = await kv.keys();
for await (const key of keys) {
console.log(key);
}
Watch for Changes
// Watch a specific key
const watch = await kv.watch({ key: 'app.theme' });
for await (const entry of watch) {
console.log(`Theme changed to: ${entry.string()}`);
updateTheme(entry.string());
}
// Watch all keys
const watchAll = await kv.watch();
for await (const entry of watchAll) {
console.log(`${entry.key} = ${entry.string()}`);
}
Delete Values
// Delete a key
await kv.delete('app.theme');
// Purge all revisions
await kv.purge('app.theme');
Use Cases
- Configuration Management: Store application settings
- Feature Flags: Toggle features dynamically
- Session Storage: Store user sessions
- Distributed Locks: Implement leader election
Object Stores
Store large binary objects in JetStream.
Creating an Object Store
- Go to your NATS cluster
- Navigate to Object Store in JetStream tab
- Click Create Object Store
Object Store Configuration
| Field | Description |
|---|---|
| Name | Store name |
| Max Bytes | Total storage limit |
| Storage | File or Memory |
| Replicas | Number of copies |
Object Operations
Store Objects
const os = await js.views.os('FILES');
// Store from buffer
const data = Buffer.from('Hello, World!');
await os.put({ name: 'hello.txt' }, data);
// Store with metadata
await os.put({
name: 'report.pdf',
description: 'Monthly report',
headers: {
'Content-Type': 'application/pdf'
}
}, pdfBuffer);
Retrieve Objects
// Get object info
const info = await os.info('hello.txt');
console.log(`Size: ${info.size} bytes`);
console.log(`Modified: ${info.mtime}`);
// Download object
const result = await os.get('hello.txt');
const data = await result.data;
console.log(data.toString());
List Objects
const objects = await os.list();
for await (const obj of objects) {
console.log(`${obj.name}: ${obj.size} bytes`);
}
Delete Objects
await os.delete('hello.txt');
Use Cases
- File Storage: Store user uploads
- Asset Distribution: Distribute media files
- Backup Storage: Store application backups
- Document Storage: Store PDFs, images
Best Practices
1. Design Subject Hierarchy
# Good - hierarchical and specific
orders.created
orders.updated
orders.{orderId}.status
users.{userId}.profile.updated
# Bad - flat and ambiguous
order_created
user_update
2. Set Appropriate Limits
const stream = await jsm.streams.add({
name: 'EVENTS',
subjects: ['events.>'],
max_msgs: 10000000, // 10M messages
max_bytes: 10737418240, // 10GB
max_age: 604800000000000 // 7 days in nanoseconds
});
3. Use Explicit Acknowledgments
// Always acknowledge to prevent message loss
for await (const msg of messages) {
try {
await process(msg);
msg.ack();
} catch (error) {
msg.nak({ delay: 5000 }); // Retry after 5 seconds
}
}
4. Monitor Consumer Lag
Set up alerts when consumers fall behind:
const info = await consumer.info();
if (info.num_pending > 10000) {
alert('Consumer lag is high!');
}
5. Use Replicas for Durability
Always use 3+ replicas for production streams:
const stream = await jsm.streams.add({
name: 'CRITICAL_EVENTS',
subjects: ['critical.>'],
num_replicas: 3
});