# Wildcard Subscription (/sdks/nodejs/how-to/events/wildcard-subscription)



## Overview [#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 [#prerequisites]

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

## Code [#code]

```typescript title="wildcard-subscription.ts"
/**
 * 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 [#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 [#related]

* [Pattern overview](/learn/events/getting-started)
* [Node.js SDK Reference](/sdks/nodejs/reference)
* [Basic Pub/Sub](/sdks/nodejs/tutorials/basic-pubsub)
* [Cancel Subscription](/sdks/nodejs/how-to/events/cancel-subscription)