ØMQ bindings for Node.js. The goals of this library are:
async/await and async
iterators.Install ZeroMQ.js with prebuilt binaries:
npm install zeromq
Supported versions:
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:
Linux on x86-64 with musl, for example:
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.
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:
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:
Enables CURVE security for encrypted communications. To enable CURVE support, add the following to your .npmrc:
zmq_curve="true"
Enable libsodium for CURVE security instead of the built-in tweetnacl implementation. This can provide better performance for CURVE operations. To use libsodium, add the following to your .npmrc:
zmq_sodium="true"
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
Enables WebSocket transport, allowing ZeroMQ to communicate over WebSockets. To enable WebSocket support, add the following to your .npmrc:
zmq_websockets="true"
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"
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"
Specifies the minimum macOS version that the binary will be compatible with. This is particularly useful when building for different macOS versions. To set this, add the following to your .npmrc, replacing 10.15 with your desired minimum macOS version:
macosx_deployment_target="10.15"
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.
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()
This example demonstrates how a producer pushes information onto a socket and how a worker pulls information from the socket.
producer.jsCreates 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.jsCreates 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()
This example demonstrates using zeromq in a classic Pub/Sub,
Publisher/Subscriber, application.
publisher.jsCreate 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.jsCreate 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()
This example illustrates a request from a client and a reply from a server.
client.jsimport * 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.jsimport * 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()
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...
})
})
This library provides typings for TypeScript version 3.0.x and later.
Requirements
compilerOptions.target to esnext or later (e.g. es2018)compilerOptions.lib (and
include their corresponding polyfills if needed): es2015,
ESNext.AsyncIterableIf you are interested in making contributions to this project, please read the following sections.
In order to develop and test the library, you'll need the tools required to build from source (see above).
Additionally, having clang-format is strongly recommended.
Socket and context options can be set at runtime, even if they are not implemented by this library. By design, this requires no recompilation if the built version of ZeroMQ has support for them. This allows library users to test and use options that have been introduced in recent versions of ZeroMQ without having to modify this library. Of course we'd love to include support for new options in an idiomatic way.
Options can be set as follows:
const {Dealer} = require("zeromq")
/* This defines an accessor named 'sendHighWaterMark', which corresponds to
the constant ZMQ_SNDHWM, which is defined as '23' in zmq.h. The option takes
integers. The accessor name has been converted to idiomatic JavaScript.
Of course, this particular option already exists in this library. */
class MyDealer extends Dealer {
get sendHighWaterMark(): number {
return this.getInt32Option(23)
}
set sendHighWaterMark(value: number) {
this.setInt32Option(23, value)
}
}
const sock = new MyDealer({sendHighWaterMark: 456})
When submitting pull requests for new socket/context options, please consider the following:
camelCase naming conventions.The test suite can be run with:
npm install
npm run build
npm run test
The test suite will validate and fix the coding style, run all unit tests and verify the validity of the included TypeScript type definitions.
Some tests are not enabled by default:
INCLUDE_COMPAT_TESTS=1 npm run testTo publish a new version, run:
npm version <new version>
git push && git push --tags
Wait for continuous integration to finish. Prebuilds will be generated for all
supported platforms and attached to a Github release. Documentation is
automatically generated and committed to gh-pages. Finally, a new NPM package
version will be automatically released.
Version 6+ is a complete rewrite of previous versions of ZeroMQ.js in order to
be more reliable, correct, and usable in modern JavaScript & TypeScript code as
first outlined in this issue.
Previous versions of ZeroMQ.js were based on zmq and a fork that included
prebuilt binaries.
See detailed changes in the CHANGELOG.
FAQs
Next-generation ZeroMQ bindings for Node.js
The npm package zeromq receives a total of 46,609 weekly downloads. As such, zeromq popularity was classified as popular.
We found that zeromq demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.