DgramSocket

Defined in: packages/node/src/net/dgram-socket.ts:77

High-level wrapper around Node.js dgram.Socket | UDP datagram sockets.

This class delegates almost all behavior to an underlying dgram.Socket instance while:

• Providing strongly-typed events via DgramSocketEvents.
• Using InetEndpoint instead of Node’s RemoteInfo.
• Exposing promise-based bind and close helpers.
• Aggregating send-queue statistics through DgramSocket.getStat.

Unless explicitly documented otherwise, methods have the same semantics as their counterparts on dgram.Socket.

Example usage:

const dgramSocket = DgramSocket.from({ type: "udp4" });
await dgramSocket.bind(12345, "localhost");
dgramSocket.on("message", (msg, msgSize, from) => {
  console.log(
    `Received ${msgSize} bytes from ${from.address}:${from.port}`,
  );
});
await dgramSocket.send(54321, "localhost", Buffer.from("Hello, UDP!"));
await dgramSocket.close();

Extends

• EventDispatcherMapBase<DgramSocketEvents>

Implements

• IEventDispatcherMap<DgramSocketEvents>

Constructors

Constructor

new DgramSocket(socket): DgramSocket

Defined in: packages/node/src/net/dgram-socket.ts:92

Constructs a new DgramSocket instance wrapping the provided dgram.Socket.

Parameters

socket

Socket

Returns

DgramSocket

Overrides

EventDispatcherMapBase<DgramSocketEvents>.constructor

Methods

addMembership()

addMembership(multicastAddress, multicastInterface?): void

Defined in: packages/node/src/net/dgram-socket.ts:132

Adds this socket to the given multicast group.

This is a thin wrapper around dgram.Socket.addMembership, which configures IP_ADD_MEMBERSHIP for the given multicast group.

Parameters

multicastAddress

string

multicastInterface?

string

Returns

void

---

address()

address(): InetEndpoint | null

Defined in: packages/node/src/net/dgram-socket.ts:272

Gets the address information of the bound socket.

Returns

InetEndpoint | null

The socket’s endpoint information or null if the socket is not bound.

Throws

If the address type is not an AddressInfo object.

---

addSourceMembership()

addSourceMembership(sourceAddress, groupAddress, multicastInterface?): void

Defined in: packages/node/src/net/dgram-socket.ts:193

Adds this socket to a source-specific multicast group.

This is a thin wrapper around dgram.Socket.addSourceSpecificMembership, configuring source-specific multicast membership for the given source and group.

Parameters

sourceAddress

string

groupAddress

string

multicastInterface?

string

Returns

void

---

bind()

bind(port?, address?, options?): Promise<void>

Defined in: packages/node/src/net/dgram-socket.ts:304

Binds the UDP socket to the specified address and port.

Parameters

port?

number = 0

The port to bind to. If not specified, a random available port will be used.

address?

string

The address to bind to. If not specified, the socket will bind to all available interfaces.

options?

Binding options.

exclusive?

boolean

fd?

number

Returns

Promise<void>

A promise that resolves when the socket is successfully bound.

---

close()

close(): Promise<void>

Defined in: packages/node/src/net/dgram-socket.ts:416

Closes the UDP socket.

Returns

Promise<void>

A promise that resolves when the socket is successfully closed.

---

connect()

connect(port, address?): Promise<void>

Defined in: packages/node/src/net/dgram-socket.ts:350

Associates the socket with one remote endpoint, binding it to a random port first if it is not bound.

Once connected, datagrams from any other endpoint are dropped by the kernel, DgramSocket.sendConnected sends to the remote endpoint, and an ICMP port unreachable it answers with surfaces as an ECONNREFUSED error event rather than being ignored.

Parameters

port

number

The remote port.

address?

string

The remote address; resolved like send’s, and defaulting to the loopback address.

Returns

Promise<void>

A promise that resolves once the socket is connected, and rejects when it already is or when binding or resolving address fails.

---

disconnect()

disconnect(): void

Defined in: packages/node/src/net/dgram-socket.ts:384

Dissociates a connected socket from its remote endpoint.

This is a thin wrapper around dgram.Socket.disconnect.

Returns

void

Throws

With code ERR_SOCKET_DGRAM_NOT_CONNECTED when the socket is not connected.

---

dropMembership()

dropMembership(multicastAddress, multicastInterface?): void

Defined in: packages/node/src/net/dgram-socket.ts:182

Removes this socket from the given multicast group.

This is a thin wrapper around dgram.Socket.dropMembership, which configures IP_DROP_MEMBERSHIP for the given multicast group.

Parameters

multicastAddress

string

multicastInterface?

string

Returns

void

---

dropSourceMembership()

dropSourceMembership(sourceAddress, groupAddress, multicastInterface?): void

Defined in: packages/node/src/net/dgram-socket.ts:212

Removes this socket from a source-specific multicast group.

This is a thin wrapper around dgram.Socket.dropSourceSpecificMembership, removing source-specific multicast membership for the given source and group.

Parameters

sourceAddress

string

groupAddress

string

multicastInterface?

string

Returns

void

---

getRecvBufferSize()

getRecvBufferSize(): number

Defined in: packages/node/src/net/dgram-socket.ts:152

Returns the size in bytes of the underlying receive buffer.

This is a thin wrapper around dgram.Socket.getRecvBufferSize, which reads the SO_RCVBUF socket option.

Returns

number

---

getSendBufferSize()

getSendBufferSize(): number

Defined in: packages/node/src/net/dgram-socket.ts:172

Returns the size in bytes of the underlying send buffer.

This is a thin wrapper around dgram.Socket.getSendBufferSize, which reads the SO_SNDBUF socket option.

Returns

number

---

getStat()

getStat(): DgramSocketStat

Defined in: packages/node/src/net/dgram-socket.ts:437

Returns statistics about the underlying send queue.

This wraps dgram.Socket.getSendQueueCount and dgram.Socket.getSendQueueSize into a single object.

Returns

DgramSocketStat

---

isSubscribed()

isSubscribed<K>(event, listener): boolean

Defined in: packages/async/src/events/event-dispatcher-map-base.ts:38

Check if a callback is subscribed to a specific event.

Type Parameters

K

K extends keyof DgramSocketEvents

Parameters

event

K

The event name.

listener

Callable<DgramSocketEvents[K]>

The callback to check.

Returns

boolean

Implementation of

IEventDispatcherMap.isSubscribed

Inherited from

EventDispatcherMapBase.isSubscribed

---

ref()

ref(): void

Defined in: packages/node/src/net/dgram-socket.ts:101

References the socket, preventing the process from exiting while the socket is active.

Returns

void

---

remoteAddress()

remoteAddress(): InetEndpoint | null

Defined in: packages/node/src/net/dgram-socket.ts:393

Gets the remote endpoint of a connected socket.

Returns

InetEndpoint | null

The remote endpoint, or null if the socket is not connected.

---

send()

send(port, address, msg, offset?, length?): Promise<number>

Defined in: packages/node/src/net/dgram-socket.ts:467

Sends a message to the specified address and port.

The msg argument contains the message to be sent. Depending on its type, different behavior can apply. If msg is a Buffer, any TypedArray or a DataView, the offset and length specify the offset within the Buffer where the message begins and the number of bytes in the message, respectively.

If msg is a String, then it is automatically converted to a Buffer with ‘utf8’ encoding.

With messages that contain multi-byte characters, offset and length will be calculated with respect to byte length and not the character position. If msg is an array, offset and length must not be specified.

Parameters

port

number

The destination port.

address

string

The destination address.

msg

string | DataView<ArrayBufferLike> | TypedArray

The message to send. This can be a Buffer, TypedArray, or DataView.

offset?

number

Optional offset in the message buffer to start sending from.

length?

number

Optional number of bytes to send from the message buffer.

Returns

Promise<number>

A promise that resolves with the number of bytes sent.

---

sendConnected()

sendConnected(msg, offset?, length?): Promise<number>

Defined in: packages/node/src/net/dgram-socket.ts:503

Sends a message to the remote endpoint of a connected socket.

The message, offset and length behave as in DgramSocket.send.

Parameters

msg

string | DataView<ArrayBufferLike> | TypedArray

The message to send.

offset?

number

Optional offset in the message buffer to start sending from.

length?

number

Optional number of bytes to send from the message buffer.

Returns

Promise<number>

A promise that resolves with the number of bytes sent, and rejects when the socket is not connected.

---

setBroadcast()

setBroadcast(flag): void

Defined in: packages/node/src/net/dgram-socket.ts:122

Enables or disables sending of broadcast datagrams.

This is a thin wrapper around dgram.Socket.setBroadcast, which toggles the SO_BROADCAST socket option. When enabled, UDP packets may be sent to broadcast addresses.

Parameters

flag

boolean

Whether broadcast should be enabled.

Returns

void

---

setMulticastInterface()

setMulticastInterface(multicastInterface): void

Defined in: packages/node/src/net/dgram-socket.ts:230

Sets the outbound multicast interface.

This is a thin wrapper around dgram.Socket.setMulticastInterface, which controls the default outgoing interface for multicast traffic.

Parameters

multicastInterface

string

Returns

void

---

setMulticastLoop()

setMulticastLoop(flag): void

Defined in: packages/node/src/net/dgram-socket.ts:240

Enables or disables loopback for multicast packets sent from this socket.

This is a thin wrapper around dgram.Socket.setMulticastLoopback, which toggles the IP_MULTICAST_LOOP socket option.

Parameters

flag

boolean

Returns

void

---

setMulticastTtl()

setMulticastTtl(ttl): void

Defined in: packages/node/src/net/dgram-socket.ts:250

Sets the time-to-live (TTL) value for multicast packets.

This is a thin wrapper around dgram.Socket.setMulticastTTL, which configures the IP_MULTICAST_TTL socket option.

Parameters

ttl

number

Returns

void

---

setRecvBufferSize()

setRecvBufferSize(size): void

Defined in: packages/node/src/net/dgram-socket.ts:142

Sets the size in bytes of the underlying receive buffer.

This is a thin wrapper around dgram.Socket.setRecvBufferSize, which sets the SO_RCVBUF socket option.

Parameters

size

number

Returns

void

---

setSendBufferSize()

setSendBufferSize(size): void

Defined in: packages/node/src/net/dgram-socket.ts:162

Sets the size in bytes of the underlying send buffer.

This is a thin wrapper around dgram.Socket.setSendBufferSize, which sets the SO_SNDBUF socket option.

Parameters

size

number

Returns

void

---

setTtl()

setTtl(ttl): void

Defined in: packages/node/src/net/dgram-socket.ts:260

Sets the unicast time-to-live (TTL) value for outgoing packets.

This is a thin wrapper around dgram.Socket.setTTL, which configures the IP_TTL socket option.

Parameters

ttl

number

Returns

void

---

subscribe()

subscribe<K>(event, listener, options?): Callable | null

Defined in: packages/async/src/events/event-dispatcher-map-base.ts:23

Type Parameters

K

K extends keyof DgramSocketEvents

Parameters

event

K

listener

Callable<DgramSocketEvents[K]>

options?

EventDispatcherSubscribeOptions

Returns

Callable | null

Implementation of

IEventDispatcherMap.subscribe

Inherited from

EventDispatcherMapBase.subscribe

---

unref()

unref(): void

Defined in: packages/node/src/net/dgram-socket.ts:109

Unreferences the socket, allowing the process to exit even if the socket is active.

Returns

void

---

unsubscribe()

unsubscribe<K>(event, listener): void

Defined in: packages/async/src/events/event-dispatcher-map-base.ts:31

Unsubscribe a callback from a specific event.

Type Parameters

K

K extends keyof DgramSocketEvents

Parameters

event

K

The event name.

listener

Callable<DgramSocketEvents[K]>

The callback to remove.

Returns

void

Implementation of

IEventDispatcherMap.unsubscribe

Inherited from

EventDispatcherMapBase.unsubscribe

---

wait()

wait<K>(event, options?): Promise<DgramSocketEvents[K]>

Defined in: packages/async/src/events/event-dispatcher-map-base.ts:45

Wait for the next occurrence of a specific event, optionally matching a predicate.

This is a convenience method that subscribes to the dispatcher, waits for the next event that matches the predicate (if provided), and then unsubscribes automatically.

Type Parameters

K

K extends keyof DgramSocketEvents

Parameters

event

K

The event name to wait for.

options?

EventDispatcherWaitOptions<DgramSocketEvents[K]>

Optional settings including predicate and abort signal.

Returns

Promise<DgramSocketEvents[K]>

A promise that resolves with the event arguments as an array.

Implementation of

IEventDispatcherMap.wait

Inherited from

EventDispatcherMapBase.wait

---

from()

static from(options?): DgramSocket

Defined in: packages/node/src/net/dgram-socket.ts:82

Creates a new DgramSocket instance with the specified options.

Parameters

options?

SocketOptions

Returns

DgramSocket