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 the JS client library in ES2017 CommonJS module form, 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"/>

From within a Node.js application

npm install diffusion

...and within a Node.js module

var diffusion = require('diffusion');

From within a rich web application (e.g. React.js or Vue.js)

Adding the Diffusion library to the dependencies of your package.json will make the Diffusion API available to your application.

The Diffusion client is distributed in CommonJS form (written to ES2017 standard), but you may also import the library alongside other ES modules - an approach adhering to modern web apps and build pipelines. (The Diffusion CommonJS modules carry ES-module interoperability metadata for assistance with downstream bundling.)

To use the Diffusion client alongside other ESM imports, use the following form:

import * as diffusion from "diffusion";

Interop Polyfills

When using the Diffusion library in this manner, some additional polyfilling is required to satisfy the runtime library.

(No polyfills are necessary when using the self-contained browser bundle file outlined in the 'webpage' example above - the requirement is specific to the interop context.)

The best polyfill approach will depend upon your particular build stack and bundler, but the example extract provided here is from a Vite/Vue.js configuration, where the vite-plugin-node-polyfills library is 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

Enabling message compression

To enable the optional Diffusion message compression in browser applications, a zlib implementation is required.

In a web page, or simple web application, 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

In a more complex web application, a polyfill library approach is likely a better fit (see Interop Polyfills above).

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

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 any 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 {};