Solace Messaging API for JavaScript

Common errors

• Error connecting: Solace error 500: Connection refused (client-connect-failed)

  cause Incorrect broker host/port, invalid VPN, username, or password, or broker is unreachable/down.
  fix Verify `sessionProperties.url`, `vpnName`, `userName`, `password` against your Solace Event Broker configuration. Ensure the broker is running and accessible from the client's network.

• Session Event: 18 - Subscription Error: Client does not have 'subscribe' permission for topic 'some/forbidden/topic'.

  cause The client attempted to subscribe to a topic for which it lacks permissions on the Solace Event Broker.
  fix Check topic permissions for the client username and ensure the topic syntax is correct and allowed by the broker's Access Control Lists (ACLs).

• TypeError: solace.SolclientFactory.createSession is not a function

  cause Incorrect import or access method for the `SolclientFactory`. The `solace` object might not be correctly resolving the `SolclientFactory` property.
  fix Ensure you are importing `solace` correctly as `import * as solace from 'solclientjs';` for ESM/TypeScript or `const solace = require('solclientjs');` for CommonJS. `SolclientFactory` should then be accessible as a property of the main `solace` object.

Warnings

• gotcha Proprietary Software License
  Fix: Review the Solace software license terms at https://solace.com/license-software before using this package, as it is proprietary and intended for use with Solace Event Brokers.
• gotcha External Documentation
  Fix: API documentation is no longer bundled with the package; refer to the online documentation for Node.js (https://docs.solace.com/API-Developer-Online-Ref-Documentation/nodejs/index.html) or Browser (https://docs.solace.com/API-Developer-Online-Ref-Documentation/js/index.html).
• gotcha API Variation Selection
  Fix: Choose the appropriate API variation (production, full, or debug) during `require` or `import` based on performance and logging needs. `production` is minified with limited logs, `full` has more logs, and `debug` has all logs with no minification.
• gotcha Mandatory Message Destruction
  Fix: After receiving and processing a message, call `message.destroy()` to release associated resources and prevent memory leaks. This is critical for high-throughput applications.

Install

• npm install solclientjs npm
• yarn add solclientjs yarn
• pnpm add solclientjs pnpm

Imports

• solace
  wrong:

  import solace from 'solclientjs';

  correct:

  import * as solace from 'solclientjs';

  In CommonJS, `require('solclientjs')` loads the `production` API variation by default. In ESM, `import * as solace from 'solclientjs'` provides the module namespace from which all API components (including `SolclientFactory`, `SessionProperties`, etc.) are accessed.
• solaceDebugAPI
  wrong:

  import { debug } from 'solclientjs';

  correct:

  import * as solace from 'solclientjs'; const solaceDebugAPI = solace.debug;

  This debug variation includes all logging for easier debugging and is not minified. In CommonJS, it's accessed as `require('solclientjs').debug`.
• Session, Message, SessionEventCode
  wrong:

  import { SolaceSession, SolaceMessage } from 'solclientjs';

  correct:

  import { Session, Message, SessionEventCode } from 'solclientjs';

  TypeScript types for core objects and enums, like `Session`, `Message`, and `SessionEventCode`, are typically exported directly from the main package root for strong typing and autocompletion.

Quickstart

This example demonstrates how to connect to a Solace Event Broker, subscribe to a topic, and publish a message using the `solclientjs` API.

import * as solace from 'solclientjs';

const host = process.env.SOLACE_HOST ?? 'localhost:55555';
const vpn = process.env.SOLACE_VPN ?? 'default';
const user = process.env.SOLACE_USERNAME ?? 'client_username';
const password = process.env.SOLACE_PASSWORD ?? 'client_password';

const sessionProperties = new solace.SessionProperties();
sessionProperties.url = host;
sessionProperties.vpnName = vpn;
sessionProperties.userName = user;
sessionProperties.password = password;

const session = solace.SolclientFactory.createSession(sessionProperties,
    new solace.MessageRxCBInfo((session, message) => {
        console.log(`Received message: ${message.getSdtContainer().getValue()} from topic: ${message.getDestination().getName()}`);
        message.destroy(); // Important to destroy messages after processing
    }),
    new solace.SessionEventCBInfo((session, event) => {
        console.log(`Session Event: ${event.sessionEventCode} - ${event.infoStr}`);
        if (event.sessionEventCode === solace.SessionEventCode.UP_NOTICE) {
            console.log('Session connected successfully.');
            session.subscribe(
                solace.SolclientFactory.createTopic('tutorial/topic'),
                true, // generate confirmation
                'my-subscription', // correlation key
                10000 // timeout (ms)
            );
            const message = solace.SolclientFactory.createMessage();
            message.setDestination(solace.SolclientFactory.createTopic('tutorial/topic'));
            message.setSdtContainer(solace.SDTContainer.create('Hello from solclientjs!'));
            session.send(message);
            console.log('Message sent to tutorial/topic');
        } else if (event.sessionEventCode === solace.SessionEventCode.DISCONNECTED) {
            console.log('Session disconnected.');
            session.destroy();
        }
    })
);

try {
    session.connect();
    console.log('Attempting to connect to Solace broker...');
} catch (error: any) {
    console.error(`Error connecting: ${error.message}`);
}

// Keep the process alive for a bit to receive messages
setTimeout(() => {
    if (session.isConnected) {
        session.disconnect();
    }
    console.log('Exiting example.');
    process.exit(0);
}, 10000); // Disconnect after 10 seconds