@ciklum/ng-xmess

NG-XMESS

Table of contents

1. Description
2. Installation and usage
   2.1 Application development
   2.2 Module development
3. API
   3.1 Multi-level wildcard
   3.2 Single level wildcard
   3.3 Without wildcard
   3.4 Decorators
   3.4.1 Property decorator
   3.4.2 Method decorator
   3.5 Destroy
4. Publish with wildcard
5. Interfaces
6. Links
7. CHANGELOG

Description

Extended basic pub/sub pattern implementation for communication between microfrontends apllications. Developed for Angular applications.

Installation and usage

Application development

Set private registry by following the instruction.

Then install ng-xmess library:

npm i -S @ciklum/ng-xmess

In your application:

import { NgModule } from '@angular/core'
import { NgXmessModule } from '@ciklum/ng-xmess'

@NgModule({
  imports: [NgXmessModule.forRoot()]
})
export class MyModule {}

In case of using with @ciklum/xmess-repeater

import { NgModule } from '@angular/core'
import { NgXmessModule } from '@ciklum/ng-xmess'

@NgModule({
  // Pass the xmessId to use ng-xmess in conjunction with xmess-repeater
  imports: [NgXmessModule.forRoot({ xmessId: 'xmess-repeater-integration-id' })]
})
export class MyModule {}

Module development

• Clone the project.
• Create .env file by following the instruction.
• Install module's dependencies by running:

npm run module:install

API

Module provides with service that implements basic pub/sub and partial MQTT protocol patterns. Service has two methods to work with:

• channel(path: string): Channel<ChannelResponse> - method to register subscriber to a specific channel. Returns Channel type that extends ReplaySubject, so that it immediately fires subscription with the last message if there were some publishes before.

• publish(arg?: any): void - method to publish some data to all subscribers in current channel.

Without wildcard

You are able to subscribe to a particular channel without any wildcard as well.

import { NgXmessService } from '@ciklum/ng-xmess';

class TestClass {
  playerInfo: any;
  
  constructor(private ngXmess: NgXmessService) {
    this.ngXmess.channel('sport').subscribe(payload => this.playerInfo = payload.data);
  }
  
  publish() {
    this.ngXmess.channel('sport').publish('some info'); //fires
    this.ngXmess.channel('sport/tennis').publish('some info'); //doesn't fire
    this.ngXmess.channel('sport/tennis/player1').publish('some info'); //doesn't fire
  }
}

Single level wildcard

The plus sign (‘+’) is a wildcard character that matches only one topic level.

The single-level wildcard can be used at any level in the Topic Filter, including first and last levels. Where it is used it MUST occupy an entire level of the filter

It can be used at more than one level in the Topic Filter and can be used in conjunction with the multilevel wildcard.

import { NgXmessService } from '@ciklum/ng-xmess';

class TestClass {
  playerInfo: any;
  
  constructor(private ngXmess: NgXmessService) {
    this.ngXmess.channel('sport/tennis/+').subscribe(payload => this.playerInfo = payload.data);
  }
  
  publish() {
    this.ngXmess.channel('sport/tennis/player1').publish('some info'); //fires
    this.ngXmess.channel('sport/tennis/player2').publish('some info'); //fires
    this.ngXmess.channel('sport/tennis/player1/ranking').publish('some info'); //doesn't fire
  }
}

In the example above we subscribed to “sport/tennis/+” and would receive following messages:

• “sport/tennis/player1”
• “sport/tennis/player2”
• and not receive from “sport/tennis/player1/ranking”, because the single-level wildcard matches only a single level

Extra information

• “+” is valid
• “sport/+/player1” is valid
• “/finance” matches “+/+” and “/+”, but not “+”

Multi-level wildcard

The number sign (‘#’) is a wildcard character that matches any number of levels within a topic. The multi-level wildcard represents the parent and any number of child levels.

The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic Filter.

import { NgXmessService } from '@ciklum/ng-xmess';

class TestClass {
  playerInfo: any;
  
  constructor(private ngXmess: NgXmessService) {
    this.ngXmess.channel('sport/tennis/player1/#').subscribe(payload => this.playerInfo = payload.data);
  }
  
  publish() {
    this.ngXmess.channel('sport/tennis/player1/ranking').publish('some info'); //fires
    this.ngXmess.channel('sport/tennis/player1/score/wimbledon').publish('some info'); //fires
  }
}

In the example above we subscribed to "sport/tennis/player1/#" and it would receive following messages:

• “sport/tennis/player1/ranking”
• “sport/tennis/player1/score/wimbledon”

Extra information

• “#” is valid and will receive every Application Message
• “sport/tennis/#” is valid
• “sport/tennis#” is not valid
• “sport/tennis/#/ranking” is not valid

Mixed

User is also able to use the single level ('+') and the multi-level ('#') wildcards in conjunction.

import { NgXmessService } from '@ciklum/ng-xmess';

class TestClass {
  playerInfo: any;
  
  constructor(private ngXmess: NgXmessService) {
    this.ngXmess.channel('+/tennis/#').subscribe(payload => this.playerInfo = payload.data);
  }
  
  publish() {
    this.ngXmess.channel('sport/tennis/player1').publish('some info'); //fires
    this.ngXmess.channel('player/tennis/rank/winners').publish('some info'); //fires
  }
}

In the example above we subscribed to “+/tennis/#” and would receive following messages:

• “sport/tennis/player1”
• “player/tennis/rank/winners”

Decorators

Also module provides with two decorators (property and method).

Property decorator

• @Xmess(path: string, options?: XmessPropOptions) - property decorator that subscribes to channel and set Observable payload to registered property.

import { Component } from '@angular/core';
import { Observable } from 'rxjs';
import { Xmess, ChannelResponse } from '@ciklum/ng-xmess';

@Component({
  template: `<h1>{{title|async}}</h1>`
})
class TestComponent {
  
  @Xmess('user/name') title: Observable<string>;
  
  @Xmess('user/lastname', {includePath: true}) payload: Observable<ChannelResponse>;
  
}

Method decorator

• @XmessListener(path: string) - method decorator that subscribes to channel and invoke registered method once subscription on registered channel is fired.

import { Component } from '@angular/core';
import { Observable } from 'rxjs';
import { XmessListener, ChannelResponse } from '@ciklum/ng-xmess';

@Component({
})
class TestComponent {
  
  @XmessListener('user/#')
  handler(payload: ChannelResponse) {
    console.log(payload);
  }
  
}

Destroy

xmessService.destroy() - method for removing global subscriptions

Publish with wildcard

Publish wildcard is not allowed

ngXmess.channel('a/#').publish('publish wildcard')
ngXmess.channel('b/+').publish('publish wildcard')
// this is not allowed and doesn’t work

Interfaces

interface ChannelResponse {
  path: string; // path of published channel
  data?: any; // data that send to channel
}

interface XmessPropOptions {
  includePath: boolean; // whether include published channel path to payload or not.
}

Links

• pub/sub pattern
• MQTT

Changelog

All notable changes to this project will be documented in this file

0.3.0 (2018-10-03)

Features

• add XmessPropOptions interface for the second param @Xmess decorator

0.2.0 (2018-09-28)

Features

• channel additionally to data obtains path

0.1.7 (2018-09-27)

Initial release