Class DgramSocket

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();

Hierarchy

EventDispatcherMapBase<DgramSocketEvents>
- DgramSocket

Implements

IEventDispatcherMap<DgramSocketEvents>

Constructors

constructor

new DgramSocket(sock: Socket): DgramSocket
Constructs a new DgramSocket instance wrapping the provided dgram.Socket.
Parameters
- sock: Socket
Returns DgramSocket
Overrides EventDispatcherMapBase<DgramSocketEvents>.constructor
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:97

Methods

addMembership

addMembership(multicastAddress: string, multicastInterface?: string): void
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
- OptionalmulticastInterface: string
Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:135

address

address(): InetEndpoint | null
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.
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:273

addSourceMembership

addSourceMembership(
    sourceAddress: string,
    groupAddress: string,
    multicastInterface?: string,
): void
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
- OptionalmulticastInterface: string
Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:196

bind

bind(
    port?: number,
    address?: string,
    options?: { exclusive?: boolean; fd?: number },
): Promise<void>
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.
- Optionaladdress: string
  The address to bind to. If not specified, the socket will bind to all available interfaces.
- Optionaloptions: { exclusive?: boolean; fd?: number }
  Binding options.
Returns Promise<void>
A promise that resolves when the socket is successfully bound.
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:303

close

close(): Promise<void>
Closes the UDP socket.

Returns Promise<void>
A promise that resolves when the socket is successfully closed.
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:339

`Protected`dispatch

dispatch<K extends keyof DgramSocketEvents>(
event: K,
...args: DgramSocketEvents[K],
): void
Dispatches an event to all listeners for the given event name.
Type Parameters
- K extends keyof DgramSocketEvents
Parameters
- event: K
  The event name.
- ...args: DgramSocketEvents[K]
  Arguments to pass to listeners.
Returns void
Inherited from EventDispatcherMapBase.dispatch
- Defined in packages/misc-util/src/async/events/_event-dispatcher-map-base.ts:58

dropMembership

dropMembership(multicastAddress: string, multicastInterface?: string): void
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
- OptionalmulticastInterface: string
Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:185

dropSourceMembership

dropSourceMembership(
    sourceAddress: string,
    groupAddress: string,
    multicastInterface?: string,
): void
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
- OptionalmulticastInterface: string
Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:215

getRecvBufferSize

getRecvBufferSize(): number
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:155

getSendBufferSize

getSendBufferSize(): number
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:175

getStat

getStat(): DgramSocketStat
Returns statistics about the underlying send queue.

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

Returns DgramSocketStat
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:360

isSubscribed

isSubscribed<K extends keyof DgramSocketEvents>(
event: K,
listener: Callable<DgramSocketEvents[K]>,
): boolean
Check if a callback is subscribed to a specific event.
Type Parameters
- 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
- Defined in packages/misc-util/src/async/events/_event-dispatcher-map-base.ts:38

ref

ref(): void
References the socket, preventing the process from exiting while the socket is active.

Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:105

send

send(
    port: number,
    address: string,
    msg: string | TypedArray | DataView<ArrayBufferLike>,
    offset?: number,
    length?: number,
): Promise<number>
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 | TypedArray | DataView<ArrayBufferLike>
  The message to send. This can be a Buffer, TypedArray, or DataView.
- Optionaloffset: number
  Optional offset in the message buffer to start sending from.
- Optionallength: number
  Optional number of bytes to send from the message buffer.
Returns Promise<number>
A promise that resolves with the number of bytes sent.
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:389

setBroadcast

setBroadcast(flag: boolean): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:125

setMulticastInterface

setMulticastInterface(multicastInterface: string): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:233

setMulticastLoop

setMulticastLoop(flag: boolean): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:243

setMulticastTtl

setMulticastTtl(ttl: number): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:253

setRecvBufferSize

setRecvBufferSize(size: number): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:145

setSendBufferSize

setSendBufferSize(size: number): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:165

setTtl

setTtl(ttl: number): void
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
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:263

subscribe<K extends keyof DgramSocketEvents>(
    event: K,
    listener: Callable<DgramSocketEvents[K]>,
    options?: EventDispatcherSubscribeOptions,
): Callable | null
Type Parameters
- K extends keyof DgramSocketEvents
Parameters
- event: K
- listener: Callable<DgramSocketEvents[K]>
- Optionaloptions: EventDispatcherSubscribeOptions
Returns Callable | null
Implementation of IEventDispatcherMap.subscribe
Inherited from EventDispatcherMapBase.subscribe
- Defined in packages/misc-util/src/async/events/_event-dispatcher-map-base.ts:23

unref

unref(): void
Unreferences the socket, allowing the process to exit even if the socket is active.

Returns void
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:112

unsubscribe

unsubscribe<K extends keyof DgramSocketEvents>(
event: K,
listener: Callable<DgramSocketEvents[K]>,
): void
Unsubscribe a callback from a specific event.
Type Parameters
- 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
- Defined in packages/misc-util/src/async/events/_event-dispatcher-map-base.ts:31

wait

wait<K extends keyof DgramSocketEvents>(
event: K,
options?: EventDispatcherWaitOptions<DgramSocketEvents[K]>,
): Promise<DgramSocketEvents[K]>
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 extends keyof DgramSocketEvents
Parameters
- event: K
  The event name to wait for.
- Optionaloptions: 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
- Defined in packages/misc-util/src/async/events/_event-dispatcher-map-base.ts:45

`Static`from

from(options?: SocketOptions): DgramSocket
Creates a new DgramSocket instance with the specified options.
Parameters
- Optionaloptions: SocketOptions
Returns DgramSocket
- Defined in packages/misc-util/src/node/net/dgram-socket.ts:88

Class DgramSocket

Hierarchy

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns DgramSocket

Methods

addMembership

Parameters

Returns void

address

Returns InetEndpoint | null

Throws

addSourceMembership

Parameters

Returns void

bind

Parameters

Returns Promise<void>

close

Returns Promise<void>

Protecteddispatch

Type Parameters

Parameters

Returns void

dropMembership

Parameters

Returns void

dropSourceMembership

Parameters

Returns void

getRecvBufferSize

Returns number

getSendBufferSize

Returns number

getStat

Returns DgramSocketStat

isSubscribed

Type Parameters

Parameters

Returns boolean

ref

Returns void

send

Parameters

Returns Promise<number>

setBroadcast

Parameters

Returns void

setMulticastInterface

Parameters

Returns void

setMulticastLoop

Parameters

Returns void

setMulticastTtl

Parameters

Returns void

setRecvBufferSize

Parameters

Returns void

setSendBufferSize

Parameters

Returns void

setTtl

Parameters

Returns void

subscribe

Type Parameters

Parameters

Returns Callable | null

unref

Returns void

unsubscribe

Type Parameters

Parameters

`Protected`dispatch

`Static`from