Topic Patterns

Topic Format

Topics are dot-delimited hierarchical identifiers using alphanumeric characters, dots, underscores, and hyphens:

// Valid topic formats
'workflow.started'
'workflow.execution.node-completed'
'agent.chat.token'
'hil.approval.user-123'
'notifications.user.alice_bob'

// Valid pattern characters: [a-zA-Z0-9._-]
// Dots separate segments
// No spaces, no special characters except ._-

Exact Match

Subscribe to a single topic with no wildcards. Only messages with that exact topic string are delivered:

// Exact match — receives only 'workflow.started', not 'workflow.started.sub'
stream.subscribe('bas', 'workflow.started', handler);

// Useful for high-specificity subscriptions
stream.subscribe('bas', 'hil.approval.task-456', hilHandler);
stream.subscribe('bas', 'agent.chat.session-789.done', completionHandler);

Single-Level Wildcard (.*)

The .* suffix matches exactly one additional segment. Pattern must end with .*:

// Matches: workflow.started, workflow.completed, workflow.failed
// Does NOT match: workflow, workflow.node.started (multi-level)
stream.subscribe('bas', 'workflow.*', handler);

// Matches: agent.chat.token, agent.chat.done, agent.chat.error
stream.subscribe('bas', 'agent.chat.*', streamHandler);

// Nested prefix — still single level wildcard
// Matches: workflow.execution.started, workflow.execution.completed
// Does NOT match: workflow.execution.node.started (3 levels deep)
stream.subscribe('bas', 'workflow.execution.*', execHandler);

Pattern Validation Rules

TopicMatcher.validate(pattern) enforces these rules:

BizFirstGO Topic Namespace Conventions