@pixotope/zmq-client

ZMQ-over-WebSocket pub/sub client for talking to a Pixotope/Disguise DataHub-style backend.

Install

pnpm add @pixotope/zmq-client

This package depends on @pixotope/utils internally (for shared DataHub-related types). It's resolved automatically as part of installation - you don't need to install or think about it yourself.

Quick start

@pixotope/zmq-client doesn't open the socket connection itself - hand it a connected socket.io-client Socket (e.g. via @pixotope/socket.io-client), and it takes care of mapping get/call/update/set/subscribe/mirror requests onto socket events and routing responses back to your callbacks.

import { io } from "socket.io-client";
import {
  ZMQWebSocketClient,
  ZMQProxyWSClient,
  DEFAULT_PROXY_WS_ENDPOINTS,
} from "@pixotope/zmq-client";

const socket = io("https://example.com");

// The low-level ZMQClient implementation, bound to a socket and an event-name mapping.
const client = new ZMQWebSocketClient(socket, DEFAULT_PROXY_WS_ENDPOINTS);

// A higher-level wrapper that generates request IDs for you and returns
// `[unsubscribe, id]` tuples for long-lived requests.
const proxy = new ZMQProxyWSClient(client);

// Publish a raw message on a topic.
client.send("some/topic", { hello: "world" });

// Fetch the current value of a property once.
proxy.get({
  service: "MyService",
  name: "SomeProperty",
  callback: (value) => console.log(value),
});

// Invoke a remote method and await its result.
const result = await proxy.callAsync({
  service: "MyService",
  functionName: "DoSomething",
  parameters: { foo: "bar" },
});

// Subscribe to changes on a property. Returns a tuple of [unsubscribe, id].
const [unsubscribe] = proxy.subscribe({
  service: "MyService",
  name: "SomeProperty",
  callback: (data) => console.log(data.message.Value),
});

// Later, stop listening.
unsubscribe();

API overview

• ZMQClient - the interface describing the low-level pub/sub + get/call/update/set/subscribe/mirror operations, along with its ZMQClient namespace of option types (Get, Call, Update, Set, Subscribe, Mirror).
• ZMQWebSocketClient - the default ZMQClient implementation, backed by a socket.io-client Socket.
• ZMQProxyWSClient - a higher-level wrapper around a ZMQClient that generates request IDs for you and returns [unsubscribe, id] tuples for cancelable/long-lived requests.
• TEndpointsConfig / DEFAULT_PROXY_WS_ENDPOINTS - the event-name mapping used to carry each operation over the socket, and the default mapping for the standard Pixotope ZMQ-over-WebSocket proxy server.

See the generated API reference (pnpm typedoc) for full type signatures.