dgram-as-promised

dgram-as-promised

This module provides promisified version of the standard dgram class. The API is the same as for standard dgram, except bind, close and send methods which return Promise object.

Requirements

This module requires ES2021 with Node >= 16.

Installation

npm install dgram-as-promised

Additionally for Typescript:

npm install -D @types/node

Usage

dgram-as-promised can be used similarly to the standard dgram module.

Example:

import DgramAsPromised from "dgram-as-promised"

const socket = DgramAsPromised.createSocket("udp4")

const MEMBERSHIP = "224.0.0.1"
const PORT = 41234

const message = Buffer.from("ABCDEFGH")

bind

Method bind returns Promise object which resolves to address info when listening event is emitted.

const address = await socket.bind()
console.log(`Socket is listening on ${address.address}:${address.port}`)

socket.setBroadcast(true)
socket.setMulticastTTL(128)

socket.addMembership(MEMBERSHIP)
console.log("Membership is set")

send

Method send returns Promise object which is fulfilled when the message has been sent.

const bytes = await socket.send(message, 0, message.length, PORT, MEMBERSHIP)
console.log(`Message is sent (${bytes} bytes)`)

recv

Method recv returns Promise object which resolves to the object with msg and rinfo properties as from message event or resolves to undefined when the socket is already closed.

It throws an error if a timeout occurs and it was set by setTimeout method.

const packet = await socket.recv()
if (packet) {
  console.log(`Received message: ${packet.msg.toString()}`)
  console.log(`Received ${packet.rinfo.size} bytes`)
}

close

Method close returns Promise object which resolves when close event is emitted or the socket is already closed.

await socket.close()
console.log("Socket is closed")

setTimeout

socket = socket.setTimeout(ms)

Set the timeout used by recv method for the idle socket and after this timeout, the recv method will reject a Promise with a timeout error.

After the error, the socket is not closed and calling another recv method will reset the timeout.

The method returns this object.

Example:

socket.setTimeout(1000)
await socket.recv()

iterate

Method iterate and the socket object returns an asynchronous iterator which will call recv method until the socket is closed.

for await (const packet of socket) {
  console.info(packet.msg.toString())
  // Close socket if Ctrl-D is in the message
  if (packet.msg.indexOf(4) !== -1) {
    await socket.close()
  }
}

destroy

Method destroy cleans internal listeners.

socket = socket.destroy()

The method returns this object.

License

Copyright (c) 2016-2024 Piotr Roszatycki mailto:[e-mail]

MIT

Changelog

v6.0.0 2024-06-22

• Converted to ESM module.
• Requires Node >= 16.
• addMembership, setBroadcast, setTTL, setMulticastTTL, setMulticastInterface, setMulticastLoopback, dropMembership, setRecvBufferSize, setSendBufferSize and destroy return this.
• address method doesn't return string anymore; closes: dex4er/js-dgram-as-promised#51
• setTimeout method sets timeout for recv method; closes: dex4er/js-dgram-as-promised#55