Registry / http-networking / diffusion

diffusion

JSON →
library6.12.2jsnpmunverified

The Diffusion JavaScript Client is a comprehensive library for interacting with Diffusion servers (on-premise or Diffusion Cloud) from both browser and Node.js environments. It enables real-time data streaming, pub/sub messaging, and management of topic trees over WebSockets or HTTP. Currently stable at version 6.12.1, the library typically sees regular updates, with minor versions being backward-compatible, while major versions (e.g., v5 to v6) often introduce breaking changes that require client application updates. Key differentiators include its robust support for diverse topic types, built-in TypeScript definitions, and modular bundles for optimized loading, alongside its use of Promises for asynchronous operations. It is designed for applications requiring high-performance, secure, and scalable real-time data distribution infrastructure.

npm install diffusion
INSTALL
IMPORT
SIG · DIFFUSION
D
diffusion
http-networkingjavascriptv6.12.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

diffusion
import * as diffusion from 'diffusion';
const diffusion = require('diffusion');
ESM import for TypeScript and modern JavaScript. CommonJS `require` is also supported but not idiomatic for new projects shipping types.
connect
import { connect } from 'diffusion';
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`.

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();
Debug
Known issues
breakingUpgrading 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.
affects: >=6.0
gotchaClient-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.
affects: >=6.1
gotchaTopic 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.
affects: >=5.0
gotchaRestarting 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.
affects: >=5.0
deprecatedThe `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.
affects: >=6.0
Errors
Common errors & fixes
Failed to connect
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)
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>
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.
Upgrade
Version history
6.12.2latest on npm
Audit
Dependencies
browserify-zliboptionalRequired for client-side message compression in browser environments. Not needed in Node.js as it uses native zlib.
vite-plugin-node-polyfillsoptionalRecommended for ESM/CommonJS web application frameworks (like Vue/Vite) to polyfill Node.js APIs (e.g., zlib, Buffer) if client-side compression or binary data handling is needed.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
diffusion — npm install diffusion · libregistry