Skip to main content

NatsPubsub Documentation

Welcome to the comprehensive documentation for NatsPubsub - a production-ready, declarative pub/sub messaging library for NATS JetStream.

What is NatsPubsub?​

NatsPubsub is a modern, developer-friendly library that brings battle-tested reliability patterns to NATS JetStream. Available in both JavaScript/TypeScript and Ruby, it enables seamless event-driven architecture with guaranteed message delivery, exactly-once processing, and automatic failure handling.

Key Features​

  • 🎯 Declarative API - Intuitive, class-based subscribers inspired by Rails and NestJS
  • 🔒 Reliability Patterns - Built-in Inbox/Outbox patterns and Dead Letter Queue (DLQ)
  • 🌐 Cross-Language - Full interoperability between Ruby and JavaScript services
  • 🧪 Testing Support - Comprehensive testing utilities and matchers
  • 📊 Observability - Built-in metrics, health checks, and monitoring UI
  • ⚡ High Performance - Optimized for throughput with batching and connection pooling
  • 🛡️ Type Safety - Full TypeScript support with built-in schema validation
  • 🔧 Auto-Topology - Automatic JetStream stream and consumer management

Quick Navigation​

Getting Started​

Perfect for newcomers to NatsPubsub:

Guides​

Step-by-step guides for common tasks:

Patterns​

Implement reliability patterns:

Integrations​

Framework-specific integration guides:

Reference​

Complete API and configuration documentation:

Advanced​

Deep dives into internals and advanced topics:

Troubleshooting​

Solutions to common problems:

Language-Specific Resources​

JavaScript/TypeScript​

Ruby​

Example Projects​

Learn by example with complete working applications:

Quick Start​

JavaScript/TypeScript​

import { Publisher, Subscriber } from "nats-pubsub";

// Publish a message
const publisher = new Publisher({
  servers: "nats://localhost:4222",
  env: "production",
  appName: "my-app",
});

await publisher.publish("order.created", {
  orderId: "12345",
  amount: 99.99,
});

// Subscribe to messages
class OrderSubscriber extends Subscriber {
  constructor() {
    super("order.created");
  }

  async handle(message, metadata) {
    console.log("Order created:", message);
  }
}

// Start subscriber
const subscriber = new OrderSubscriber();
await subscriber.connect({
  servers: "nats://localhost:4222",
  env: "production",
  appName: "my-app",
});

Ruby​

require 'nats_pubsub'

# Configure NatsPubsub
NatsPubsub.configure do |config|
  config.servers = 'nats://localhost:4222'
  config.env = 'production'
  config.app_name = 'my-app'
end

# Publish a message
NatsPubsub.publish('order.created', {
  order_id: '12345',
  amount: 99.99
})

# Subscribe to messages
class OrderSubscriber < NatsPubsub::Subscriber
  subscribe_to 'order.created'

  def handle(message, context)
    puts "Order created: #{message}"
  end
end

# Start subscribers
NatsPubsub::Manager.start

Architecture Overview​

Core Concepts​

Topics and Subjects​

NatsPubsub uses hierarchical topics with automatic subject generation:

{env}.{appName}.{topic}

Example: production.order-service.order.created

Reliability Patterns​

  • Outbox Pattern: Ensures messages are published even if NATS is temporarily unavailable
  • Inbox Pattern: Prevents duplicate message processing with database-backed deduplication
  • Dead Letter Queue: Automatically handles failed messages with configurable retry

Middleware System​

Add cross-cutting concerns with a composable middleware pipeline:

// JavaScript
subscriber.use(loggingMiddleware);
subscriber.use(retryMiddleware);
subscriber.use(metricsMiddleware);
# Ruby
class OrderSubscriber < NatsPubsub::Subscriber
  use LoggingMiddleware
  use RetryMiddleware
  use MetricsMiddleware
end

Why NatsPubsub?​

vs. Raw NATS Client​

FeatureRaw NATSNatsPubsub
Declarative API❌✅
Inbox/Outbox Patterns❌ Manual✅ Built-in
Schema Validation❌✅
Testing Utilities⚠️ Limited✅ Comprehensive
Auto-Topology❌✅
Observability⚠️ Basic✅ Built-in
Framework Integration❌✅ Rails, Express, NestJS

vs. Kafka​

  • ✅ Simpler Operations: No ZooKeeper, easier deployment
  • ✅ Lower Latency: Sub-millisecond message delivery
  • ✅ Built-in Request/Reply: Native support for synchronous patterns
  • ✅ Smaller Footprint: Single binary, minimal resource usage
  • ⚠️ Ecosystem: Smaller ecosystem than Kafka

vs. RabbitMQ​

  • ✅ Performance: 2-10x higher throughput
  • ✅ Simplicity: Easier to configure and operate
  • ✅ Cloud Native: Better Kubernetes integration
  • ✅ At-Least-Once: Built into JetStream
  • ⚠️ Message Persistence: Different durability model

Community & Support​

Performance Benchmarks​

NatsPubsub delivers production-grade performance:

OperationThroughputLatency (p99)
Publishing (sync)50K msgs/sec2ms
Publishing (batch)200K msgs/sec5ms
Subscribing100K msgs/sec<1ms
Inbox Check150K ops/sec<1ms
Outbox Relay80K msgs/sec10ms

See Performance Guide for optimization tips.

Production Ready​

NatsPubsub is built for production with:

  • ✅ Battle-tested: Used in high-throughput production systems
  • ✅ Comprehensive Testing: 95%+ code coverage
  • ✅ Type Safety: Full TypeScript support
  • ✅ Monitoring: Built-in metrics and health checks
  • ✅ Documentation: Extensive guides and API docs
  • ✅ Active Maintenance: Regular updates and security patches

Next Steps​

  1. New to NatsPubsub? Start with Introduction
  2. Ready to code? Try the Quick Start (5 minutes)
  3. Building for production? Read the Deployment Guide
  4. Need help? Check Troubleshooting

License: MIT | Version: 1.0.0 | Last Updated: November 2025