ZeroMQ.js Next Generation

ØMQ bindings for Node.js. The goals of this library are:

Semantically similar to the native ØMQ library, while sticking to JavaScript idioms.
Use modern JavaScript and Node.js features such as async/await and async iterators.
High performance.
Fully usable with TypeScript (3+).
Compatible with Zeromq 4/5 via "zeromq/v5-compat"
Secure Curve protocol with Libsodium
Zeromq Draft API support

Useful links

ZeroMQ.js API reference.
ZeroMQ project documentation.
- Note: The Node.js examples on zeromq.org do not yet reflect the new API, but the Guide in particular is still a good introduction to ZeroMQ for new users.

ZeroMQ.js Next Generation

Installation

Install ZeroMQ.js with prebuilt binaries:

npm install zeromq

Supported versions:

Node.js v12+ (requires a N-API)

Examples

Here some examples of different features are provided. More examples can be found in the examples directory.

You can also browse the API reference documentation to see all socket types, methods & options as well as more detailed information about how to apply them.

Note: If you are new to ZeroMQ, please start with the ZeroMQ documentation.

Basic Usage

ES modules:

import {Request} from "zeromq"
// or as namespace
import * as zmq from "zeromq"

const reqSock = new Request()
//...
const repSock = new zmq.Reply()

Commonjs:

const zmq = require("zeromq")

const reqSock = new zmq.Request()
//...
const repSock = new zmq.Reply()

Push/Pull

This example demonstrates how a producer pushes information onto a socket and how a worker pulls information from the socket.

`producer.js`

Creates a producer to push information onto a socket.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Push()

  await sock.bind("tcp://127.0.0.1:3000")
  console.log("Producer bound to port 3000")

  while (true) {
    await sock.send("some work")
    await new Promise(resolve => {
      setTimeout(resolve, 500)
    })
  }
}

run()

`worker.js`

Creates a worker to pull information from the socket.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Pull()

  sock.connect("tcp://127.0.0.1:3000")
  console.log("Worker connected to port 3000")

  for await (const [msg] of sock) {
    console.log("work: %s", msg.toString())
  }
}

run()

Pub/Sub

This example demonstrates using zeromq in a classic Pub/Sub, Publisher/Subscriber, application.

`publisher.js`

Create the publisher which sends messages.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Publisher()

  await sock.bind("tcp://127.0.0.1:3000")
  console.log("Publisher bound to port 3000")

  while (true) {
    console.log("sending a multipart message envelope")
    await sock.send(["kitty cats", "meow!"])
    await new Promise(resolve => {
      setTimeout(resolve, 500)
    })
  }
}

run()

`subscriber.js`

Create a subscriber to connect to a publisher's port to receive messages.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Subscriber()

  sock.connect("tcp://127.0.0.1:3000")
  sock.subscribe("kitty cats")
  console.log("Subscriber connected to port 3000")

  for await (const [topic, msg] of sock) {
    console.log(
      "received a message related to:",
      topic,
      "containing message:",
      msg,
    )
  }
}

run()

Req/Rep

This example illustrates a request from a client and a reply from a server.

`client.js`

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Request()

  sock.connect("tcp://127.0.0.1:3000")
  console.log("Producer bound to port 3000")

  await sock.send("4")
  const [result] = await sock.receive()

  console.log(result)
}

run()

`server.js`

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Reply()

  await sock.bind("tcp://127.0.0.1:3000")

  for await (const [msg] of sock) {
    await sock.send((2 * parseInt(msg.toString(), 10)).toString())
  }
}

run()

Zeromq 4 and 5 Compatibility layer

The next generation version of the library features a compatibility layer for ZeroMQ.js versions 4 and 5. This is recommended for users upgrading from previous versions.

Example:

const zmq = require("zeromq/v5-compat")

const pub = zmq.socket("pub")
const sub = zmq.socket("sub")

pub.bind("tcp://*:3456", err => {
  if (err) throw err

  sub.connect("tcp://127.0.0.1:3456")

  pub.send("message")

  sub.on("message", msg => {
    // Handle received message...
  })
})

TypeScript

This library provides typings for TypeScript version 3.0.x and later.

Requirements

For TypeScript version >= 3:
- compilerOptions
For TypeScript version < 3.6:
- either set compilerOptions.target to esnext or later (e.g. es2018)
- or add the following, or similar, libraries to compilerOptions.lib (and include their corresponding polyfills if needed): es2015, ESNext.AsyncIterable

Prebuilt binaries

The following platforms have a prebuilt binary available:

Windows on x86/x86-64

Zeromq binaries on Windows 10 or older need Visual C++ Redistributable to be installed.
Linux on x86-64 with libstdc++.so.6.0.21+ (glibc++ 3.4.21+), for example:
- Debian 9+ (Stretch or later)
- Ubuntu 16.04+ (Xenial or later)
- CentOS 8+
Linux on x86-64 with musl, for example:
- Alpine 3.3+
MacOS 10.9+ on x86-64

If a prebuilt binary is not available for your platform, installing will attempt to start a build from source.

Building from source

If a prebuilt binary is unavailable, or if you want to pass certain options during build, you can build this package from source.

Make sure you have the following installed before attempting to build from source:

Node.js 12+ or Electron
C++17 compiler toolchain (e.g. LLVM, GCC, MSVC)
Python 3
CMake 3.16+
vcpkg dependencies (e.g. on Linux it needs curl, unzip, zip, tar, git, pkg-config)

For Curve:

automake
autoconf
libtool

To install from source, specify build_from_source=true in a .npmrc file

build_from_source=true

When building from source, you can also specify additional build options in a .npmrc file in your project:

Available Build Options

<details> <summary>👉🏻 Options</summary>

Curve with Libsodium support

(Enabled by default)

Enables CURVE security for encrypted communications. Zeromq uses libsodium for CURVE security. To enable CURVE support, add the following to your .npmrc:

zmq_curve="true"
zmq_sodium="true"

Building libsodium requires these dependencies on Linux/MacOS: autoconf automake libtool, which can be installed via apt-get or brew, etc.

Draft support

(Enabled by default)

By default libzmq is built with support for Draft patterns (e.g. server-client, radio-dish, scatter-gather). If you want to build libzmq without support for Draft, you can specify the following in .npmrc:

zmq_draft=false

Websocket support

Enables WebSocket transport, allowing ZeroMQ to communicate over WebSockets. To enable WebSocket support, add the following to your .npmrc:

zmq_websockets="true"

Secure Websocket support

Enables WebSocket transport with TLS (wss), providing secure WebSocket communications. To enable secure WebSocket support, add the following to your .npmrc:

zmq_websockets_secure="true"

Not Synchronous Resolve

Enables immediate send/receive on the socket without synchronous resolution. This option can improve performance in certain scenarios by allowing operations to proceed without waiting for synchronous resolution. To enable this feature, add the following to your .npmrc:

zmq_no_sync_resolve="true"

MacOS Deployment Target

Specifies the minimum macOS version that the binary will

Zeromq.js

Install / Use

README