domain-service-events v1.0.0

Domain Service Events

Emit and subscribe to internal events based on domain, service, and event type. Also provides an additional layer of memory spacing if needed. This is for events within a single JavaScript or NodeJS process. See the usage exampes to get a better idea of what this does.

Page Contents

• Installation
• Import / Require
• Usage Examples
• Subscription Priority
• Memory Spaces
• API

Installation

npm install domain-service-events

Import / Require

TypeScript and ES6 Modules

// get default memory space
import DomainServiceEvents from 'domain-service-events'

// have the ability to create multiple memory spaces
import { DomainServiceEventsFactory } from 'domain-service-events'

Node JS

// get default memory space
const DomainServiceEvents = require('domain-service-events')

// have the ability to create multiple memory spaces
const { DomainServiceEventsFactory } = require('domain-service-events')

Usage Examples

import DomainServiceEvents from 'domain-service-events'

// subscribe specifically to the myDomain myService myEventType event
DomainServiceEvents.subscribe('myDomain.myService.myEventType', function (event, payload) {
    // do something
})

// subscribe to all events in myDoamin
DomainServiceEvents.subscribe('myDomain.*.*', function (event, payload) {
    // do something
})

// subscribe to all events of type myEventType
DomainServiceEvents.subscribe('*.*.myEventType', function (event, payload) {
    // do something
})

// subscribe to have the handler called only once
DomainServiceEvents.once('myDomain.myService.myEventType', function (event, payload) {
    // do something
})

// create a registered emitter
const emit = DomainServiceEvents.register('myDomain', 'myService')

// send payload to every handler that has subscribed to myDomain, myService, or myEventType
emit('myEventType', { a: true, b: 5, message: 'yes' })
    .then(() => {
        console.log('All handlers completed')
    })

// subscribe and unsubscribe
const unsubscribe = DomainServiceEvents.subscribe('*.*.*', function (event, payload) {})
unsubscribe()

Subscription Priority

There are two ways that subscription handlers are prioritized. The first is based on the specificity of the event id. When you subscribe you can optionally specify the domain, service, and event type. The more you specify the sooner your handler will be executed. Less specificity means your handler will run later.

The second way to prioritize a handler is by specifying a weight when subscribing.

The following table shows the priority order based on event id specificity. A cell with an ✓ indicates that specifier has been used. The numbers along the top show priority, with 1 being first and 8 being last.

As a brief example, an event id of "foo.bar.baz" would run first and "foo.bar.*" would run second.

Memory Spaces

If you want to create a new set of subscriptions and emitted events that are independent of other DomainServiceEvents subscriptions and emitters then you can create a new memory space using the factory function.

import { DomainServiceEventsFactory } from 'domain-service-events' // ES6 imports
// const { DomainServiceEventsFactory } = require('domain-service-events') // NodeJS

const Events1 = DomainServiceEventsFactory()
const Events2 = DomainServiceEventsFactory()

Events1.subscribe('foo.bar.baz', (event, payload) => {
    // do something
})

Events2.subscribe('foo.bar.baz', (event, payload) => {
    // do something
})

// These two namespaces are identical but not in conflict.
const emit1 = Events1.register('foo', 'bar')
const emit2 = Events2.register('foo', 'bar')

// Trigger an event in the first memory space.
// The Events2.subscribe handler will not trigger.
emit1('baz', 'some payload')

API

The following API is the same whether you are using custom memory spaces or the default memory space.

emit

emit (eventType: string, payload: any): Promise<void>

This function is generated when you register a domain service event. Calling this function will trigger all subscriptions, made using the subscribe function, that subscribed to this domain service event type.

Parameters

• eventType - The name of the event being emitted.
• payload - An optional value to send along with the emitted event. Can be any value.

Returns a promise that will resolve once all subscribed handlers have completed.

once

once (eventId: string | EventId, handler: Function): void

Subscribe to an event once and then auto unsubscribe. The parameters for this function are identical to the subscribe function so refer to that for the parameters descriptions.

Returns nothing.

register

register (domain: string, service: string): Function

Registers a new domain service namespace that can then be used to emit events.

Parameters

• domain - The name of the domain being registered.
• service - The name of the service being registered.

Returns an emit function that can be used to emit events from the registered namespace.

subscribe

subscribe (eventId: string | EventId, handler: Function): Function

Subscribe to one or more events.

Parameters

• eventId - This can be a string that indicates the domain service event type to subscribe to. This is done by separating the domain, service, and event type with a dot (.). The eventId may also include wildcards in any of the domain, service, and event type. Examples:

  subscribe('myDomain.myService.myEventType', () => {}) // subscribe to one specific event type
  subscribe('foo.bar.*', () => {}) // subscribe to all event types within foo.bar
  subscribe('*.*.*', () => {}) // subscribe all all events within the memory space

  Alternatively this value can also be an object that can specify the event id and other properties:

  • eventId - The event ID string, including optional wildcards.
  • weight - The subscription weight. A higher weight will cause the subscription handler to run later. Positive and negative numbers can be used. Defaults to 0.

• handler - The function that will be called when an event meets the eventId criteria. If the handler is asynchronous then it should return a promise. The handler will receive two parameters as input:

  • event - The event signature. Contains a unique ID for the event (id) as well as the domain, service, and type of event.

  • payload - The payload sent when the event was emit function was called. Some emit functions may not send a payload.

Returns an unsubscribe function to remove this subscription.

Unsubscribe

unsubscribe (): void

Unsubscribes an existing subscription. See the subscribe function for details.

Returns nothing.