Skip to main content

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​

  1. Navigate to your NATS cluster
  2. Click the JetStream tab
  3. Click Create Stream
  4. Configure the stream settings

Stream Configuration​

FieldDescription
NameUnique identifier for the stream
SubjectsSubject patterns to capture (e.g., orders.*)
RetentionHow messages are retained
StorageFile (persistent) or Memory (fast)
ReplicasNumber of copies for durability
Max MessagesMaximum number of messages
Max BytesMaximum storage size
Max AgeMessage 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:

PatternDescriptionExample Matches
*Single tokenorders.* → orders.created, orders.updated
>Multiple tokensevents.> → 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​

FieldDescription
Durable NamePersistent consumer name
Deliver PolicyWhere to start (all, new, last, byStartSequence, byStartTime, lastPerSubject)
Ack PolicyHow to acknowledge (none, all, explicit)
Max DeliverMaximum delivery attempts
Filter SubjectOnly 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​

  1. Go to your NATS cluster
  2. Navigate to Key-Value in JetStream tab
  3. Click Create KV Store

KV Configuration​

FieldDescription
NameStore name
HistoryNumber of revisions to keep per key
TTLTime-to-live for entries
Max Value SizeMaximum value size in bytes
Max BytesTotal storage limit
ReplicasNumber 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​

  1. Go to your NATS cluster
  2. Navigate to Object Store in JetStream tab
  3. Click Create Object Store

Object Store Configuration​

FieldDescription
NameStore name
Max BytesTotal storage limit
StorageFile or Memory
ReplicasNumber 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
});

Next Steps​