JavaScript SDK

This fully-featured Diffusion client library can be used to interact with Diffusion Server instances from within web applications or server side Node.js based apps. It's available in minified and unminified versions, and includes TypeScript definitions out-of-the-box.

Quick Links

JavaScriptFull API Documentation (opens in new tab)JavaScriptCode examples (GitHub) (opens in new tab) JavaScript SDK in the Diffusion manual (opens in new tab)JavaScript SDK - Download JavaScript client tarball (opens in new tab)JavaScript SDK - Download TypeScript definitions file (standalone) (opens in new tab)

Download notes

• The tarball download includes modularized browser bundles, and the TypeScript definition file (refer to the Diffusion manual link for more information)
• Installing the client library via npm will include the TypeScript definitions file (see below).

Usage

Directly within a webpage

Reference the hosted version of the client library from a CDN of your choice:

<script src="https://unpkg.com/[email protected]/dist/diffusion.js"/>

Use with Node.js

npm install diffusion

...and within a Node.js module

var diffusion = require('diffusion');

Enable message compression

To enable the optional Diffusion message compression in browser applications, a zlib implementation is required. You can use browserify to require the browserify-zlib npm module, or package/include this file:

https://download.diffusiondata.com/clients/6.12.2/js/browserify-zlib-0.2.0.js

If you are using Node.js, you don't need to do anything to enable compression. Node.js provides zlib as a standard module.

Notes on using the client library within web application frameworks (Vue.js / React.js)

When using the client library within an ESM or CommonJS web application framework, it may be useful to polyfill the zlib (and other node API) using a third party polyfill library.

For instance, in the Vue/Vite ecosystem, the vite-plugin-node-polyfills library can be used to satisfy dependencies.

E.g. within a vite.config.ts file

import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [
    ...
    nodePolyfills({
      include: ['process', 'zlib', 'stream', 'util'],
      globals: {
        Buffer: true,
      },
    }),
    ...
  ],
  ...

See also the underlying Node standard polyfill library for use in the browser

Additional downloads

Additional client downloads are available for more specialised use cases, e.g. sharing Diffusion sessions across browser tabs, or optimising your web application with smaller feature-specific client bundles.

Links are provided here. Please refer to the Diffusion manual link above for more detailed guidance.

Minified and Unminified client libraries

https://download.diffusiondata.com/clients/6.12.2/js/diffusion-6.12.2.js

https://download.diffusiondata.com/clients/6.12.2/js/diffusion-unminified-6.12.2.js

Web worker bundle

https://download.diffusiondata.com/clients/6.12.2/js/diffusion-worker-6.12.2.js

Related API documentation

Modular browser bundles

The Diffusion JavaScript can also be imported in a modular way. This is useful in situations where size is critical, and tree-shaking may not be available.

Integrating with Grafana k6

The Grafana k6 testing tool is a popular open source library used in performance and reliability testing. It's written in Go, and it uses goja (a pure Go implementation of the JavaScript engine) to support tests written in JavaScript.

You may wish to use the library when testing your own application code in conjunction with the Diffusion client library. To provide detailed metrics relating to network traffic, k6 provides a WebSocket implementation, and this can be assigned for use by the Diffusion client.

There are a number of WebSocket implementations available within k6, and we recommend use of the latest, standards compliant k6/websockets, rather than k6/ws, or ay older 'experimental' implementation.

Patching the WebSocket implementation

To make use of the k6 WebSocket implementation, the easiest approach is to assign it to gloablThis.WebSocket, ahead of loading the Diffusion client script.

import { WebSocket } from 'k6/websockets';
globalThis.WebSocket = WebSocket;

The Diffusion JavaScript client will then detect and use the 'native' browser API.

Placing this code within a polyfill.js file is the recommended approach (illustrated below). This also helps overcome a couple of additional limitations of the k6 runtime environment. (Because k6 doesn't run with Node.js, some APIs are absent at runtime without manual patching.)

An example k6 test script:

import './polyfill.js'; // WebSocket patching occurs here
import diffusion from './diffusion-6.12.2.js'; // Import the diffusion client (or your app code that uses it) after the polyfill

// Alternatively, require app code here within init code.
// k6 will cache, and this provides additional assurance that polyfill executes first.
// const diffusion = require('./diffusion-6.12.2.js');

export default async function() {
    
  // Pre-register a timer before the interceptor so k6/goja's event loop
  // has a pending callback.
  // (k6 will otherwise advance the event loop to the Diffusion connection timeout timer
  // on the first async yield (the connection call) - causing connection fail)
  setTimeout(() => {}, 100);  
    
  let session;
  try {
    session = await diffusion.connect({
      host              : 'localhost',
      port              : 8080,
      principal         : 'admin',
      credentials       : 'password',
      secure            : false,
    });
  } catch (e) {
    console.log('connect error id:', e && e.id, 'message:', e && e.message, 'canReconnect:', e && e.canReconnect);
    throw e;
  }

  console.log("Diffusion client is connected, and using the k6 WebSocket implementation: " + session.sessionId);
  // ...etc
}

polyfill.js:

// Polyfill TextEncoder/TextDecoder - https://github.com/anonyco/FastestSmallestTextEncoderDecoder
// (k6 does not provide an implementation, but the Diffusion SDK requires)
import './fastestsmallestencoder.js';

// Enable zlib compression (optional) - https://download.diffusiondata.com/clients/6.12.2/js/browserify-zlib-0.2.0.js
import './browserify-zlib.js';

// The Diffusion client library will favour the native WebSocket API, where available.
// Patch the native WebSocket impl using the k6 library equivalent: https://grafana.com/docs/k6/latest/javascript-api/k6-websockets/
import { WebSocket } from 'k6/websockets';
globalThis.WebSocket = WebSocket;

export default {};