Topic

Purpose

The Topic module provides a store for named topics used in message routing. A topic is a name paired with a generated identifier; channels subscribe to topics and receive the messages routed to them.

Key Interfaces

Topic

interface Topic {
  readonly name: string // Human-readable topic name
  readonly id: string // Unique identifier (UUID v4, generated by the store)
}

TopicStore

interface TopicStore {
  readonly create: (...name: string[]) => void // Creates topics by name with generated ids
  readonly add: (...topic: Topic[]) => void // Adds existing topic objects
  readonly existsByName: (name: string) => boolean
  readonly existsById: (id: string) => boolean
  readonly getByName: (name: string) => Topic | null
  readonly getById: (id: string) => Topic | null
  readonly list: readonly Topic[]
  readonly removeByName: (...name: string[]) => void
  readonly removeById: (...id: string[]) => void
  readonly clear: () => void
}

Factory Functions

createTopicStore

Location: @hyperfrontend/network-protocol/topic

function createTopicStore(): TopicStore

Usage Examples

Basic Topic Management

import { createTopicStore } from '@hyperfrontend/network-protocol/topic'

const topicStore = createTopicStore()

topicStore.create('user-events', 'system-events', 'notifications')

const userEvents = topicStore.getByName('user-events')
// => { name: 'user-events', id: '<generated uuid>' }

topicStore.existsByName('user-events') // true
topicStore.list.length // 3

Adding Existing Topics

topicStore.add({ name: 'chat.messages', id: chatTopicId })
topicStore.getById(chatTopicId)

The id is not validated by add, but every routed-packet creator requires a UUID v4 topic id (see routing/), so use one.

Topic Removal

topicStore.removeByName('user-events', 'system-events')
topicStore.removeById(chatTopicId)
topicStore.clear()
topicStore.list.length // 0

Error Handling

topicStore.create('user-events') // twice
// Error: "Cannot create a topic with name 'user-events' as a topic with that name already exists"

topicStore.create('')
// Error: "Invalid topic name ''"

topicStore.add({ name: 'user-events', id })
// Error: "Cannot add a topic with name 'user-events' as it already exists"

topicStore.removeByName('missing')
// Error: "No topic found with name 'missing' to remove"

topicStore.removeById('missing')
// Error: "No topic found with id 'missing' to remove"

Topic Naming Conventions

Integration with Routing

import { createTopicStore } from '@hyperfrontend/network-protocol/topic'
import { createChannelStore } from '@hyperfrontend/network-protocol/browser/channel'

const topicStore = createTopicStore()
const channelStore = createChannelStore()

topicStore.create('user-events', 'system-events')

const first = channelStore.create('client-1', {
  send,
  receive,
  protocolProvider,
  session: firstSession,
})

const router: Router = (channels, topics) => {
  const subscriptions = new WeakMap<Channel, Topic[]>()
  const userEvents = topics.find((t) => t.name === 'user-events')
  subscriptions.set(first, userEvents ? [userEvents] : [])
  return { isDynamic: false, subscriptions }
}

const routingOptions = router(
  channelStore.list.map((entry) => entry.channel),
  topicStore.list
)

Validation Helpers

validations/ holds isValidName (a non-empty string), isValidTopicId (a 36-character UUID v4 string), and isValidTopic (both). isValidTopicId is what the routing creators use to check a topic id.

Relationship to Other Modules

• Depends on: @hyperfrontend/random-generator-utils (identifiers)
• Used by: routing/

See Also

• Library Index - All modules
• Architecture Guide - Topic architecture
• Topic Entry - The @hyperfrontend/network-protocol/topic entry

Related Modules