fix: update dependencies to the latest + docs: add more examples + use ES Modules for examples + docs: mention Visual C++ Redistributable in the readme

.github/workflows/CI.yml

@@ -82,9 +82,9 @@ jobs:
 
       - name: Env map
         run: |
-            if [ "${{ matrix.node_arch }}" = "ia32" ]; then
-              echo "setup_node_arch=x86" > $GITHUB_ENV
-            fi
+          if [ "${{ matrix.node_arch }}" = "ia32" ]; then
+            echo "setup_node_arch=x86" > $GITHUB_ENV
+          fi
         shell: bash
 
       - name: Setup Cpp

.prettierignore

@@ -5,3 +5,5 @@
 /node_modules
 pnpm-lock.yaml
 /build
+/script/*.js
+/script/*.mjs

.vscode/launch.json

@@ -1,46 +1,39 @@
 {
-    "configurations": [
-        {
-            "name": "JS-Attach",
-            "type": "node",
-            "request": "attach",
-            "port": 9229,
-            "continueOnAttach": true,
-            "autoAttachChildProcesses": true,
-            "resolveSourceMapLocations": [
-                "!**/node_modules/**",
-                "!**/.vscode/extensions/hbenl.vscode-mocha-test-adapter-*/**"
-            ],
-            "skipFiles": [
-                "<node_internals>/**"
-            ],
-        },
-        {
-            "type": "lldb",
-            "request": "launch",
-            "name": "Native-Launch",
-            "preLaunchTask": "clean_build_debug",
-            "program": "node",
-            "suppressMultipleSessionWarning": true,
-            "sourceLanguages": [
-                "cpp"
-            ],
-            "args": [
-                "--inspect-brk=9229",
-                "--expose-gc",
-                "-r",
-                "ts-node/register",
-                "${workspaceFolder}/test/debug.ts"
-            ],
-        }
-    ],
-    "compounds": [
-        {
-            "name": "Node-Launch",
-            "configurations": [
-                "Native-Launch",
-                "JS-Attach",
-            ]
-        }
-    ]
+  "configurations": [
+    {
+      "name": "JS-Attach",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "continueOnAttach": true,
+      "autoAttachChildProcesses": true,
+      "resolveSourceMapLocations": [
+        "!**/node_modules/**",
+        "!**/.vscode/extensions/hbenl.vscode-mocha-test-adapter-*/**"
+      ],
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "type": "lldb",
+      "request": "launch",
+      "name": "Native-Launch",
+      "preLaunchTask": "clean_build_debug",
+      "program": "node",
+      "suppressMultipleSessionWarning": true,
+      "sourceLanguages": ["cpp"],
+      "args": [
+        "--inspect-brk=9229",
+        "--expose-gc",
+        "-r",
+        "ts-node/register",
+        "${workspaceFolder}/test/debug.ts"
+      ]
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Node-Launch",
+      "configurations": ["Native-Launch", "JS-Attach"]
+    }
+  ]
 }

.vscode/settings.json

@@ -1,9 +1,7 @@
 {
   "mochaExplorer.parallel": true,
   "mochaExplorer.globImplementation": "vscode",
-  "mochaExplorer.nodeArgv": [
-    "--expose-gc"
-  ],
+  "mochaExplorer.nodeArgv": ["--expose-gc"],
   "mochaExplorer.debuggerConfig": "JS-Attach",
   "files.exclude": {
     "**/.git": true,
@@ -16,6 +14,6 @@
     "**/script/*.mjs.map": true,
     "**/script/*.d.ts": true,
     "**/script/*.d.mts": true,
-    "**/script/*.tsbuildinfo": true,
+    "**/script/*.tsbuildinfo": true
   }
 }

.vscode/tasks.json

@@ -1,10 +1,10 @@
 {
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "label": "clean_build_debug",
-            "type": "shell",
-            "command": "pnpm clean.release && pnpm build.debug",
-        }
-    ]
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "clean_build_debug",
+      "type": "shell",
+      "command": "pnpm clean.release && pnpm build.debug"
+    }
+  ]
 }

README.md

@@ -10,6 +10,7 @@
   iterators.
 - High performance.
 - Fully usable with TypeScript (3+).
+- Compatible with Zeromq 4/5 via "zeromq/v5-compat"
 
 ## Useful links
 
@@ -51,14 +52,19 @@ Requirements for using 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](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version)
+  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
-- Windows on x86/x86-64
 
 If a prebuilt binary is not available for your platform, installing will attempt
 to start a build from source.
@@ -161,11 +167,40 @@ macos_deployment_target="10.15"
 
 ## Examples
 
-**Note:** These examples assume the reader is familiar with ZeroMQ. If you are
-new to ZeroMQ, please start with the
+Here some examples of different features are provided. More examples can be
+found in the [examples directory](examples).
+
+You can also browse
+[the API reference documentation](http://zeromq.github.io/zeromq.js/globals.html)
+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](https://zeromq.org/get-started/).
 
-More examples can be found in the [examples directory](examples).
+### Basic Usage
+
+ES modules:
+
+```typescript
+import {Request} from "zeromq"
+// or as namespace
+import * as zmq from "zeromq"
+
+const reqSock = new Request()
+//...
+const repSock = new zmq.Reply()
+```
+
+Commonjs:
+
+```js
+const zmq = require("zeromq")
+
+const reqSock = new zmq.Request()
+//...
+const repSock = new zmq.Reply()
+```
 
 ### Push/Pull
 
@@ -177,7 +212,7 @@ how a worker pulls information from the socket.
 Creates a producer to push information onto a socket.
 
 ```js
-const zmq = require("zeromq")
+import * as zmq from "zeromq"
 
 async function run() {
   const sock = new zmq.Push()
@@ -201,7 +236,7 @@ run()
 Creates a worker to pull information from the socket.
 
 ```js
-const zmq = require("zeromq")
+import * as zmq from "zeromq"
 
 async function run() {
   const sock = new zmq.Pull()
@@ -227,7 +262,7 @@ Publisher/Subscriber, application.
 Create the publisher which sends messages.
 
 ```js
-const zmq = require("zeromq")
+import * as zmq from "zeromq"
 
 async function run() {
   const sock = new zmq.Publisher()
@@ -252,7 +287,7 @@ run()
 Create a subscriber to connect to a publisher's port to receive messages.
 
 ```js
-const zmq = require("zeromq")
+import * as zmq from "zeromq"
 
 async function run() {
   const sock = new zmq.Subscriber()
@@ -281,7 +316,7 @@ This example illustrates a request from a client and a reply from a server.
 #### `client.js`
 
 ```js
-const zmq = require("zeromq")
+import * as zmq from "zeromq"
 
 async function run() {
   const sock = new zmq.Request()
@@ -301,58 +336,22 @@ run()
 #### `server.js`
 
 ```js
-const zmq = require("zeromq")
+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, 10))
+    await sock.send((2 * parseInt(msg.toString(), 10)).toString())
   }
 }
 
 run()
 ```
 
-## TypeScript
-
-This library provides typings for TypeScript version 3.0.x and later.
-
-_Requirements_
-
-- For TypeScript version >= 3:
-  - [compilerOptions](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
-- 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`
-
-_Example Usage_
-
-```typescript
-import {Request} from "zeromq"
-// or as namespace
-import * as zmq from "zeromq"
-
-const reqSock = new Request()
-//...
-const repSock = new zmq.Reply()
-```
-
-### More examples
-
-More advanced examples can be found in the [examples](examples) directory of
-this repository.
-
-Or you can
-[browse the API reference documentation](http://zeromq.github.io/zeromq.js/globals.html)
-to see all socket types, methods & options as well as more detailed information
-about how to apply them.
-
-### Compatibility layer for version 4/5
+## 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
@@ -379,6 +378,20 @@ pub.bind("tcp://*:3456", err => {
 })
 ```
 
+## TypeScript
+
+This library provides typings for TypeScript version 3.0.x and later.
+
+_Requirements_
+
+- For TypeScript version >= 3:
+  - [compilerOptions](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
+- 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`
+
 ## Contribution
 
 If you are interested in making contributions to this project, please read the

examples/pub-sub/publisher.ts

@@ -0,0 +1,18 @@
+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()

examples/pub-sub/subscriber.ts

@@ -0,0 +1,20 @@
+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()

examples/push-pull/producer.ts

@@ -0,0 +1,17 @@
+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()