Wildcard Subscription

Overview

A wildcard subscription lets one subscriber match a whole family of channels with a single call, instead of wiring up a separate subscribeToEvents for every sub-channel and touching code each time a new one appears. It's the natural fit for monitoring, logging, or fan-in aggregation across a channel hierarchy — for example, watching every regional order channel from one place.

KubeMQ matches wildcard tokens against the channel hierarchy server-side at delivery time. * matches exactly one dot-separated segment, and > matches one or more trailing segments, so client.subscribeToEvents({ channel: 'js-events.wildcard-subscription.*' }) catches any single-segment suffix. Every delivered event still carries its exact channel, so the onEvent callback can tell which concrete sub-channel it came from even though the subscription itself only named a pattern.

Gotchas: * matches exactly one segment — it won't reach two levels deep, so orders.* misses orders.us.east; use > for that. Wildcards are only valid on Events subscriptions, not on sendEvent/publishes or on events-store, queues, or commands/queries. And an overly broad pattern like > at the root will quietly pull in every channel under that prefix, including ones you didn't intend to monitor.

Prerequisites

• KubeMQ server running on localhost:50000
• Node.js SDK installed (npm install kubemq-js)

Code

/**
 * Example: Wildcard Channel Subscription
 *
 * Demonstrates subscribing to multiple channels using wildcard patterns.
 * A wildcard subscription receives events from all channels matching the pattern.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/events/wildcard-subscription.ts
 */
import { KubeMQClient, createEventMessage } from 'kubemq-js';

async function main(): Promise<void> {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-events-wildcard-subscription-client',
  });

  try {
    // Subscribe to all channels under "js-events.wildcard-subscription.*"
    const subscription = client.subscribeToEvents({
      channel: 'js-events.wildcard-subscription.*',
      onEvent: (event) => {
        console.log(`[${event.channel}] ${new TextDecoder().decode(event.body)}`);
      },
      onError: (err) => {
        console.error('Subscription error:', err.message);
      },
    });

    // Publish to different sub-channels — all match the wildcard.
    await client.sendEvent(
      createEventMessage({
        channel: 'js-events.wildcard-subscription.created',
        body: 'Order #1001 created',
      }),
    );
    await client.sendEvent(
      createEventMessage({
        channel: 'js-events.wildcard-subscription.shipped',
        body: 'Order #1001 shipped',
      }),
    );
    await client.sendEvent(
      createEventMessage({
        channel: 'js-events.wildcard-subscription.delivered',
        body: 'Order #1001 delivered',
      }),
    );

    await new Promise((resolve) => setTimeout(resolve, 1000));
    subscription.cancel();
  } finally {
    await client.close();
  }
}

main().catch(console.error);

How It Works

• The channel field in subscribeToEvents() accepts KubeMQ wildcard patterns: * matches exactly one dot-separated segment, > matches one or more trailing segments.
• One subscription on js-events.wildcard-subscription.* receives events from *.created, *.shipped, and *.delivered without needing three separate subscriptions.
• Each received EventReceived carries the original channel field, so the onEvent callback can distinguish which sub-channel the event came from.
• Published events use the specific sub-channel names (*.created, *.shipped, *.delivered), not the wildcard pattern itself.

Related

• Pattern overview
• Node.js SDK Reference
• Basic Pub/Sub
• Cancel Subscription