docs(messaging): improve messaging service documentation

energywebfoundation · May 11, 2022 · 509e201 · 509e201
1 parent 787e848
commit 509e201
Show file tree

Hide file tree

Showing 5 changed files with 142 additions and 22 deletions.
diff --git a/docs/api/classes/modules_messaging.MessagingService.md b/docs/api/classes/modules_messaging.MessagingService.md
@@ -2,6 +2,13 @@
 
 [modules/messaging](../modules/modules_messaging.md).MessagingService
 
+Service responsible for handling the messaging via NATS.
+
+```typescript
+const { messagingService } = await initWithPrivateKeySigner(privateKey, rpcUrl);
+messagingService.subscribeTo(...);
+```
+
 ## Table of contents
 
 ### Constructors
@@ -42,48 +49,69 @@ ___
 
 ### publish
 
-▸ **publish**(`subject`, `data`): `Promise`<`void`\>
+▸ **publish**(`subject`, `data`): `void`
+
+Publish a message with data to the given subject.
+
+```typescript
+messagingService.publish('*.*.did:ethr:volta:0x00..0.ewf-volta', Uint8Array.from('Hello World'));
+```
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `subject` | `string` |
-| `data` | `Uint8Array` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `subject` | `string` | message subject |
+| `data` | `Uint8Array` | message data |
 
 #### Returns
 
-`Promise`<`void`\>
+`void`
 
 ___
 
 ### subscribeTo
 
-▸ **subscribeTo**(`__namedParameters`): `Promise`<`undefined` \| `number`\>
+▸ **subscribeTo**(`options`): `Promise`<`undefined` \| `number`\>
+
+Subscribe to messages on the given subject.
+
+```typescript
+messagingService.subscribeTo({
+    subject: '*.*.did:ethr:volta:0x00..0.ewf-volta',
+    messageHandler: (data) => console.log(data),
+});
+```
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `__namedParameters` | `Object` |
-| `__namedParameters.subject?` | `string` |
-| `__namedParameters.messageHandler` | (`data`: [`IMessage`](../interfaces/modules_messaging.IMessage.md)) => `void` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `options` | [`SubscribeToOptions`](../interfaces/modules_messaging.SubscribeToOptions.md) | object with options |
 
 #### Returns
 
 `Promise`<`undefined` \| `number`\>
 
+subscription id
+
 ___
 
 ### unsubscribeFrom
 
 ▸ **unsubscribeFrom**(`subscriptionId`): `Promise`<`void`\>
 
+Unsubscribe from the given subscription id.
+
+```typescript
+messagingService.unsubscribeFrom(55);
+```
+
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `subscriptionId` | `number` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `subscriptionId` | `number` | subscription id |
 
 #### Returns
 

diff --git a/docs/api/interfaces/modules_messaging.SubscribeToOptions.md b/docs/api/interfaces/modules_messaging.SubscribeToOptions.md
@@ -0,0 +1,22 @@
+# Interface: SubscribeToOptions
+
+[modules/messaging](../modules/modules_messaging.md).SubscribeToOptions
+
+## Table of contents
+
+### Properties
+
+- [messageHandler](modules_messaging.SubscribeToOptions.md#messagehandler)
+- [subject](modules_messaging.SubscribeToOptions.md#subject)
+
+## Properties
+
+### messageHandler
+
+• **messageHandler**: [`MessageHandler`](../modules/modules_messaging.md#messagehandler)
+
+___
+
+### subject
+
+• `Optional` **subject**: `string`
diff --git a/docs/api/modules/modules_messaging.md b/docs/api/modules/modules_messaging.md
@@ -13,3 +13,28 @@
 ### Interfaces
 
 - [IMessage](../interfaces/modules_messaging.IMessage.md)
+- [SubscribeToOptions](../interfaces/modules_messaging.SubscribeToOptions.md)
+
+### Type aliases
+
+- [MessageHandler](modules_messaging.md#messagehandler)
+
+## Type aliases
+
+### MessageHandler
+
+Ƭ **MessageHandler**: (`message`: [`IMessage`](../interfaces/modules_messaging.IMessage.md)) => `void`
+
+#### Type declaration
+
+▸ (`message`): `void`
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `message` | [`IMessage`](../interfaces/modules_messaging.IMessage.md) |
+
+##### Returns
+
+`void`
diff --git a/src/modules/messaging/messaging.service.ts b/src/modules/messaging/messaging.service.ts
@@ -6,14 +6,26 @@ import {
   Subscription,
 } from 'nats.ws';
 import { getMessagingConfig } from '../../config/messaging.config';
-import { IMessage, MessagingMethod } from './messaging.types';
+import {
+  IMessage,
+  MessagingMethod,
+  SubscribeToOptions,
+} from './messaging.types';
 import { SignerService } from '../signer/signer.service';
 import {
   executionEnvironment,
   ExecutionEnvironment,
 } from '../../utils/detect-environment';
 import { getLogger } from '../../config/logger.config';
 
+/**
+ * Service responsible for handling the messaging via NATS.
+ *
+ * ```typescript
+ * const { messagingService } = await initWithPrivateKeySigner(privateKey, rpcUrl);
+ * messagingService.subscribeTo(...);
+ * ```
+ */
 export class MessagingService {
   private _jsonCodec: Codec<unknown>;
   private _natsConnection: NatsConnection;
@@ -63,13 +75,22 @@ export class MessagingService {
     }
   }
 
+  /**
+   * Subscribe to messages on the given subject.
+   *
+   * ```typescript
+   * messagingService.subscribeTo({
+   *     subject: '*.*.did:ethr:volta:0x00..0.ewf-volta',
+   *     messageHandler: (data) => console.log(data),
+   * });
+   * ```
+   * @param {SubscribeToOptions} options object with options
+   * @return subscription id
+   */
   async subscribeTo({
     subject = `*.*.${this._signerService.did}.${this._natsEnvironmentName}`,
     messageHandler,
-  }: {
-    subject?: string;
-    messageHandler: (data: IMessage) => void;
-  }) {
+  }: SubscribeToOptions): Promise<number | undefined> {
     if (!this._natsConnection) {
       return;
     }
@@ -87,7 +108,15 @@ export class MessagingService {
     return subscription.getID();
   }
 
-  async unsubscribeFrom(subscriptionId: number) {
+  /**
+   * Unsubscribe from the given subscription id.
+   *
+   * ```typescript
+   * messagingService.unsubscribeFrom(55);
+   * ```
+   * @param {Number} subscriptionId subscription id
+   */
+  async unsubscribeFrom(subscriptionId: number): Promise<void> {
     const i = this._subscriptions.findIndex(
       (s) => s.getID() === subscriptionId
     );
@@ -96,7 +125,16 @@ export class MessagingService {
     }
   }
 
-  async publish(subject: string, data: Uint8Array) {
+  /**
+   * Publish a message with data to the given subject.
+   *
+   * ```typescript
+   * messagingService.publish('*.*.did:ethr:volta:0x00..0.ewf-volta', Uint8Array.from('Hello World'));
+   * ```
+   * @param {String} subject message subject
+   * @param {Uint8Array} data message data
+   */
+  publish(subject: string, data: Uint8Array): void {
     this._natsConnection?.publish(subject, data);
   }
 }
diff --git a/src/modules/messaging/messaging.types.ts b/src/modules/messaging/messaging.types.ts
@@ -10,3 +10,10 @@ export interface IMessage {
   requester: string;
   claimIssuer?: string[];
 }
+
+export type MessageHandler = (message: IMessage) => void;
+
+export interface SubscribeToOptions {
+  subject?: string;
+  messageHandler: MessageHandler;
+}