Diffusion JavaScript Client

Common errors

• Failed to connect

  cause Incorrect host, port, principal, or credentials provided during `diffusion.connect()`, or the Diffusion server is not running or accessible.
  fix Verify the `host`, `port`, `principal`, and `credentials` parameters in your `diffusion.connect()` call. Ensure the Diffusion server is running and network accessible. Check server logs for connection attempts and authentication failures.

• Error being thrown (when accessing feature after using modular/diffusion-core.js)

  cause Attempting to use a Diffusion client feature (e.g., advanced topic management) that has not been loaded when using the `modular/diffusion-core.js` bundle, which provides only core features like value streams and topic subscription.
  fix When using modular bundles, ensure that all required feature bundles are dynamically loaded *after* the `diffusion-core.js` bundle if you need features beyond basic subscription and value streams. Alternatively, use the full `diffusion.js` bundle if bundle size is not a critical concern.

• SessionError: <error message>

  cause A generic error reported asynchronously from a service call, indicating an unexpected server-side condition that the application typically cannot directly recover from.
  fix Log the `SessionError` details, including the message and any `cause` property. Consult the Diffusion server logs for more information about the underlying issue. It is often appropriate to close the current session and attempt to reconnect.

Warnings

• breaking Upgrading from Diffusion JavaScript client v5.x to v6.x involves significant breaking changes. The 'Classic API' has been entirely removed; applications must migrate to the 'Unified API'. Additionally, several legacy topic types (e.g., Paged string, Paged record, Protocol buffer, Service topics) are no longer supported. Server-side components compiled against older versions may also require recompilation.
  Fix: Review the official Diffusion documentation's 'Upgrading from version 5.x to version 6.0' guide. Recompile server-side components. Refactor client-side code to use the Unified API and supported topic types.
• gotcha Client-side message compression via zlib is not included by default in browser bundles to reduce size. If compression is desired in a browser environment, you must explicitly include `browserify-zlib-0.2.0.js` or polyfill zlib (e.g., via `vite-plugin-node-polyfills` in frameworks like Vue/Vite). Node.js environments do not require this, as zlib is a standard module.
  Fix: For browser applications, include `browserify-zlib-0.2.0.js` in your build process or use a polyfill library if working within a modern framework. For Node.js, no action is typically needed.
• gotcha Topic selectors, which can include regular expressions, may behave differently on the Diffusion client and server due to different underlying regular expression engines. This can lead to unexpected subscription or topic selection behavior.
  Fix: Thoroughly test topic selectors in both client and server environments. Simplify regular expressions where possible or use exact topic paths to minimize discrepancies. Consult Diffusion documentation on regular expression behavior.
• gotcha Restarting a Diffusion Cloud service (e.g., for updates or maintenance) results in the loss of all transient topic information (tree structure, topic state) and subscription data. All connected clients are disconnected. While security and authentication information persists, clients must reconnect, re-register handlers, re-create topics, and resubscribe.
  Fix: Design client applications to gracefully handle disconnections and reconnections. Implement logic for re-establishing subscriptions, re-creating topics, and re-registering handlers upon reconnection.
• deprecated The `ServerStatisticsConfig` API and related elements in `Statistics.xml` are deprecated and no longer have any function as of Diffusion v6.0.
  Fix: Remove any usage of the `ServerStatisticsConfig` API or `server-statistics` elements from `Statistics.xml` in your Diffusion server configuration and custom applications.

Install

• npm install diffusion npm
• yarn add diffusion yarn
• pnpm add diffusion pnpm

Imports

• diffusion
  wrong:

  const diffusion = require('diffusion');

  correct:

  import * as diffusion from 'diffusion';

  ESM import for TypeScript and modern JavaScript. CommonJS `require` is also supported but not idiomatic for new projects shipping types.
• connect
  wrong:

  import connect from 'diffusion';

  correct:

  import { connect } from 'diffusion';

  The `connect` function is a named export from the `diffusion` module. While `import * as diffusion from 'diffusion';` is common, direct named imports are also possible.
• Session

  import { Session } from 'diffusion';

  The `Session` interface/type is crucial for type-checking when working with connected Diffusion sessions. The primary `diffusion` object itself is not a class to be instantiated with `new`.

Quickstart

This quickstart demonstrates how to establish a connection to a Diffusion server, subscribe to a JSON topic, and receive real-time updates. It also shows how to publish a message to the topic, handling connection errors and ensuring proper session closure.

import * as diffusion from 'diffusion';

async function runDiffusionClient() {
  const host = process.env.DIFFUSION_HOST ?? 'ws://localhost:8080';
  const principal = process.env.DIFFUSION_PRINCIPAL ?? 'admin';
  const credentials = process.env.DIFFUSION_CREDENTIALS ?? 'password';
  const topicPath = 'my/topic/path';

  let session: diffusion.Session | undefined;
  try {
    session = await diffusion.connect({
      host: host,
      principal: principal,
      credentials: credentials,
      // secure: true // Uncomment for WSS connections
    });
    console.log(`Connected to Diffusion server: ${session.sessionId}`);

    // Create a value stream for a JSON topic
    session.addStream(topicPath, diffusion.datatypes.json()).on(
      'value', 
      (topic, spec, newValue, oldValue) => {
        console.log(`Update for ${topic}: ${JSON.stringify(newValue?.get())}`);
      }
    );

    // Subscribe to the topic
    await session.select(topicPath);
    console.log(`Subscribed to topic: ${topicPath}`);

    // Example: Publish a JSON value (requires appropriate permissions on the Diffusion server)
    const topicControl = session.topicUpdate.createUpdateContext();
    await topicControl.set(
      topicPath,
      diffusion.datatypes.json(),
      diffusion.datatypes.json().newValue({ message: 'Hello, Diffusion!', timestamp: Date.now() })
    );
    console.log('Published a message to the topic.');

    // Keep the session open for a bit to receive updates
    await new Promise(resolve => setTimeout(resolve, 10000));

  } catch (error: any) {
    console.error('Diffusion connection or operation failed:', error.message || error);
  } finally {
    if (session) {
      await session.close();
      console.log('Diffusion session closed.');
    }
  }
}

runDiffusionClient();