Messaging::StreamName

MessageStore::StreamName is a module that offers utilities for composing and parsing stream names.

It builds on the utilities in the lower-level MessageStore::StreamName module, and adds conveniences and affordances that are useful in messaging contexts, like message handlers.

Messaging::StreamName Facts

  • The Messaging::StreamName module can be mixed into a class or can be used as a function library, with its methods invoked directly from the Messaging::StreamName
  • Methods in the Messaging::StreamName module leverage the utilities in the MessageStore::StreamName module.

Messaging::StreamName Module

The StreamName module is a mixin and function library from the Messaging library and namespace.

The StreamName module provides:

  • The category macro for declaring the default category name to be used for uses of stream name composition utilities within the class where the category is declared
  • The stream_name method for composing entity stream names from the (optionally) declared category macro and an ID
  • The category_stream_name method for composing category stream names
  • The command_stream_name method for composing command stream names
  • The command_category_stream_name for composing command category stream names
  • The get_id class method for parsing a stream's ID from a stream name
  • The get_category class method for parsing a stream's category from a stream name

Category Declaration

The most common usage scenario for the stream name utility method use is in conjunction with the category macro.

The category macro declares the category name that will be used when the optional category parameter is not passed to the stream name utility.

# In the class context
category :some_entity

# In the instance context (eg: a handler block or instance method)
stream_name('123')
# => "someEntity-123"

Note that when the category is declared via the category macro, the category name is converted to camel case.

If the category is not declared via the category macro, the category can be passed explicitly to the stream name utility.

When a stream name utility method is used to explicitly control the category name, care must be taken to use the correct, natural casing. The utility methods don't convert the category name value to camel case, or normalize it in any way.

Note that the category macro is provided by the Messaging::Category module, which is included into the receiver class when the Messaging::StreamName module is included.

Entity Event Stream Name

Compose a stream name for a stream that is suitable for entity event storage.

stream_name(id, category=nil, type: nil, types: nil)

Returns

String

Parameters

Name Description Type
id ID of the entity represented by the stream String
category The stream's category name String
type The stream's category type, if only one type String
types The stream's list category types, if many types Array of Strings

In Conjunction with the Category Class Macro

# In the class context
category :some_entity

# In the instance context (eg: a handler block or instance method)
stream_name('123')
# => "someEntity-123"

Using the Category Parameter

stream_name('123', 'someEntity')
# => "someEntity-123"

With a Type

stream_name('123', 'someEntity', type: 'someType')
# => "someEntity:someType-123"

With More than One Type

stream_name('123', 'someEntity', types: ['someType', 'someOtherType'])
# => "someEntity:someType+someOtherType-123"

Category Stream Name

Compose a stream name for a category of streams.

A stream that contains the messages for every individual, identified stream in the category. For example, given the streams account-123, and account-456, the category stream, account, contains messages from both individual streams in the account category.

category_stream_name(category=nil, type: nil, types: nil)

Returns

String

Parameters

Name Description Type
category The stream's category name String
type The stream's category type, if only one type String
types The stream's list category types, if many types Array of Strings

In Conjunction with the Category Class Macro

# In the class context
category :some_entity

# In the instance context (eg: a handler block or instance method)
category_stream_name()
# => "someEntity"

Using the Category Parameter

category_stream_name('someEntity')
# => "someEntity"

With a Type

category_stream_name('someEntity', type: 'someType')
# => "someEntity:someType"

With More than One Type

category_stream_name('someEntity', types: ['someType', 'someOtherType'])
# => "someEntity:someType+someOtherType"

Command Stream Name

Compose a stream name for a stream that is suitable for transporting commands for an entity.

command_stream_name(id, category=nil, type: nil, types: nil)

Returns

String

Parameters

Name Description Type
id ID of the entity for which commands are transported by the command stream String
category The stream's category name String
type The stream's category type, if only one type String
types The stream's list category types, if many types Array of Strings

In Conjunction with the Category Class Macro

# In the class context
category :some_entity

# In the instance context (eg: a handler block or instance method)
command_stream_name('123')
# => "someEntity:command-123"

Using the Category Parameter

command_stream_name('123', 'someEntity')
# => "someEntity:command-123"

With a Type

command_stream_name('123', 'someEntity', type: 'someType')
# => "someEntity:command+someType-123"

With More than One Type

command_stream_name('123', 'someEntity', types: ['someType', 'someOtherType'])
# => "someEntity:command+someType+someOtherType-123"

Command Category Stream Name

Compose a stream name for a category of command streams.

A stream that contains the messages for every individual, identified command stream in the category.

command_category_stream_name(category=nil, type: nil, types: nil)

Returns

String

Parameters

Name Description Type
category The stream's category name String
type The stream's category type, if only one type String
types The stream's list category types, if many types Array of Strings

In Conjunction with the Category Class Macro

# In the class context
category :some_entity

# In the instance context (eg: a handler block or instance method)
command_category_stream_name()
# => "someEntity:command"

Using the Category Parameter

command_category_stream_name('someEntity')
# => "someEntity:command"

With a Type

command_category_stream_name('someEntity', type: 'someType')
# => "someEntity:command+someType"

With More than One Type

command_category_stream_name('someEntity', types: ['someType', 'someOtherType'])
# => "someEntity:command+someType+someOtherType"

Get ID from Stream Name

self.get_id(stream_name)

Returns

String

Parameters

Name Description Type
stream_name The stream name from which to get the ID String

Note that the get_id method is not mixed in when the Messaging::StreamName module is mixed into a class. It can only be invoked from the Messaging::StreamName constant.

Messaging::StreamName.get_id('someEntity-123')
# => '123'

Get Category from Stream Name

self.get_category(stream_name)

Returns

String

Parameters

Name Description Type
stream_name The stream name from which to get the category String

Note that the get_category method is not mixed in when the Messaging::StreamName module is mixed into a class. It can only be invoked from the Messaging::StreamName constant.

Messaging::StreamName.get_category('someEntity-123')
# => 'someEntity'

Category Types are Purely Mechanical

WARNING

Category types are not intended for any use except internal infrastructure or mechanical uses. They should not be used to build hierarchical category names for applicative code.

See the Stream Names topic in the Core Concepts section for examples of mechanical and infrastructural category types.

Using as a Mixin

Subordinate Mixin

Including Messaging::StreamName into a class includes the Messaging::Category module into the class.

Methods Mixed into the Receiver

  • stream_name
  • category_stream_name
  • command_stream_name
  • command_category_stream_name

Using as a Function Library

In addition to using the Messaging::StreamName module as a mixin, its methods can be invoked from the Messaging::StreamName constant.

Messaging::StreamName.stream_name('123')
  • stream_name
  • category_stream_name
  • command_stream_name
  • command_category_stream_name
  • get_id
  • get_category