@synadiaorbit/muxsub

MuxSub

A NATS multiplexing subscription utility that allows multiple message handlers to share a single underlying subscription using inbox-based routing.

Overview

MuxSub creates a single wildcard subscription on a generated inbox prefix (e.g., _INBOX.abc123.>), then routes incoming messages to specific handlers based on the message subject tokens. This approach reduces the number of subscriptions while maintaining clean message handling separation.

Installation

# Deno
deno add @synadiaorbit/muxsub

# Import in your code
import { MuxSubscription } from "@synadiaorbit/muxsub";

Usage

Basic Example

import { wsconnect } from "@nats-io/nats-core";
import { MuxSubscription } from "@synadiaorbit/muxsub";

const nc = await wsconnect({ servers: ["nats://localhost:4222"] });
const mux = new MuxSubscription(nc);

// Callback-based handler
mux.newMuxInbox("foo.bar", (_, msg) => {
  console.log("Received:", msg.subject);
});

// Iterator-based handler
const iterator = mux.newMuxInbox("responses");
for await (const msg of iterator) {
  console.log("Response:", msg.subject);
  break; // Exit after first message
}

// Publish to handlers
nc.publish(mux.subjectFor("foo.bar"), "hello");
nc.publish(mux.subjectFor("responses"), "world");

await mux.drain();
await nc.close();

API Reference

MuxSubscription

Constructor

• new MuxSubscription(nc: NatsConnection) - Creates a new multiplexing subscription

Methods

Handler Management

• newMuxInbox(subject: string, callback: MsgCallback) - Register a callback handler
• newMuxInbox(subject: string) - Create an async iterator for messages
• cancelMuxInbox(subject: string) - Remove a handler

Subject Utilities

• subjectFor(partialSubject: string) - Get the full NATS subject for publishing
• tokenFor(subject: string) - Extract the token from a full subject

Subscription Control

• drain() - Gracefully close after processing pending messages
• unsubscribe(max?: number) - Stop the subscription
• closed - Promise that resolves when subscription closes
• isDraining() - Check if subscription is draining
• isClosed() - Check if subscription is closed

How It Works

• Creates a single subscription on {prefix}.> where {prefix} is a generated inbox
• When messages arrive, extracts the token after the prefix
• Routes messages to registered handlers based on the token
• Supports both callback and async iterator patterns

Use Cases

• Request-response patterns where you need to handle multiple concurrent requests
• Microservice communication with topic-based routing
• Reducing subscription overhead when handling many related message types
• Building higher-level messaging abstractions

License

Apache License 2.0