npm package: @nuskin/ns-solace-utils
Description: This is a library to allow you to produce and consume in the Solace environment.
Latest version: 4.1.0

# ns-solace-utils

Utility library for Nu Skin to publish to and consume from the Solace Event Message Router.


**CONTENTS**

- [ns-solace-utils](#ns-solace-utils)
  - [NPM and Github Repo](#npm-and-github-repo)
  - [Installation](#installation)
  - [Usage](#usage)
    - [Solace Sessions](#solace-sessions)
    - [Queue Message Consumer](#queue-message-consumer)
    - [Topic Message Publisher](#topic-message-publisher)

## NPM and Github Repo

https://www.npmjs.com/package/@nuskin/ns-solace-utils
<br />
https://code.tls.nuskin.io/nextgen-development/utility/ns-solace-utils

## Installation

Using npm:

```bash
$ npm install @nuskin/ns-solace-utils
```

## Usage

### Solace Sessions
The `session` module creates and returns a solace session based on the properties you provide. It can also disconnect and exit from a session.

When you get a session you are required to pass in a callback that it will trigger when the session receives the `SessionEventCode.UP_NOTICE` event from Solace.
You also have the option to override the other events that it is currently listening for if you would like.
Subscribed Solace Events: `SessionEventCode.ACKNOWLEDGED_MESSAGE`, `SessionEventCode.REJECTED_MESSAGE_ERROR`, `SessionEventCode.CONNECT_FAILED_ERROR`, `SessionEventCode.DISCONNECTED`
You are also given the session object itself if you want to just override it inside your own code by calling `session.on()`

To disconnect or exit your session you can just call those methods, pass it your session, and it will gracefully disconnect and dispose of your session for you.
**Example 1:**

```javascript
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

getSolaceSession(properties, (session) => {
    // What you want to do once the session is up and connected goes here.
}).connect();

    
```

**Example 2:**

```javascript
const { getSolaceSession, exitSolaceSession, disconnectSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

const solaceSession = getSolaceSession(properties, onUpCallback);
solaceSession.connect();

disconnectSolaceSession(solaceSession);
exitSolaceSession(solaceSession);

const onUpCallback = (session) => {
    // You could also split them up this way if you'd prefer
}
    
```


**Example 3:**

```javascript
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

const solaceSession = getSolaceSession(properties, onUpCallback, onAcknowledgedCallback);
solaceSession.connect();

const onUpCallback = (session) => {
    // You could also split them up this way if you'd prefer
}

const onAcknowledgedCallback = (session) => {
    // I'm overriding SessionEventCode.ACKNOWLEDGED_MESSAGE here.
}
```

### Queue Message Consumer

The `queueConsumer` module the ability to begin consuming messages from a Solace Queue. The Solace MessageConsumer does require an active session so you'll need to pass that in once you have it.
Like with the `session` module you will be required to pass in a callback. In this case the callback will listen for the `MessageConsumerEventName.MESSAGE` event. This is what is fired when your consumer receives a message from the queue. Also, just like the `session` module we allow you to override the other default callbacks.
Subscribed Solace Events: `MessageConsumerEventName.UP`, `MessageConsumerEventName.CONNECT_FAILED_ERROR`, `MessageConsumerEventName.DOWN`, `MessageConsumerEventName.DOWN_ERROR`

The Solace Message Router doesn't allow us to easily nack messages so the default behavior of these other events is to disconnect from the queue without acknowledging the message which will place the message back on the queue. Then we try and reconnect after a brief wait at which point your consumer will receive the same message again.

You can also pass in a `MessageConsumerAcknowledgeMode`. It will default to `CLIENT` which means that it is up to you to `acknowledge()` your own messages when you're done with them. The other option is `MessageConsumerAcknowledgeMode.AUTO` which will acknowledge your messages the moment you pull them from the queue.

> Important Note: There are a variety of ways the message could come down from Solace depending on how the client sent the message body to the router. You can use the `getMessageBody()` function in the `util.js` file.

**Example 1:**

```javascript
const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, (message) => {
        // This is the callback that will be triggered when you receive a message
    })
    queueConsumer.connect();
}).connect();

```

**Example 2:**

```javascript
const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, onMessageEventCallback)
    queueConsumer.connect();
}).connect();

const onMessageEventCallback = (session) => {
    // You could also split them up this way if you'd prefer
}
```

**Example 3:**

```javascript
const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, onMessageCallback, onUpCallback)
    queueConsumer.connect();
}).connect();

const onMessageCallback = (session) => {
    // You could also split them up this way if you'd prefer
}


const onUpCallback = (session) => {
    // I'm overriding the MessageConsumerEventName.UP event
}
```
### Topic Message Publisher

The `publisher` module allows you to either send a message in a "fire and forget" fashion or it allows you to subscribe to the events and listen for the consumer of your message to send you a `SessionEventCode.ACKNOWLEDGED_MESSAGE` or a `SessionEventCode.REJECTED_MESSAGE_ERROR`. Once again you can override these functions with whatever you want and you'll also need to pass in your session again. Your messages need to be passed in as a string or you will experience an error or potential issues with your consumers.

The default event listeners will log out whether or not your message was successful and then gracefully disconnect and dispose of your session. So, if you want to do anything based on the consumer's event you'll want to pass in some callbacks. 

**Example 1:**

```javascript
const { sendMessage } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessage(session, topicName, JSON.stringify(message), metadata);
).connect();

```

**Example 2:**

```javascript
const { sendMessageAndSubscribe } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessageAndSubscribe(session, topicName, JSON.stringify(message), metadata, (evt) => {
        return 'acknowledged';
    }, (err) => {
        return 'rejected';
    });
).connect();

```

**Example 3:**

```javascript
const { sendMessageAndSubscribe } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessageAndSubscribe(session, topicName, JSON.stringify(message), metadata, onAcknowledgedCallback, onRejectedCallback);
).connect();

const onAcknowledgedCallback = (session) => {
    // I'm overriding the SessionEventCode.ACKNOWLEDGED_MESSAGE event
}

const onRejectedCallback = (session) => {
    // I'm overriding the SessionEventCode.REJECTED_MESSAGE_ERROR event
}
```