@ac-kit/node 0.1.0

package/dist/fs/write-file-atomic.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { constants as osConstants } from "node:os";
+import { fileURLToPath } from "node:url";
+import { defaults } from "@ac-kit/core";
+import { NODE_WRITE_FILE_DEFAULT_OPTIONS, } from "./types.js";
+const PERMISSION_BITS = 0o7777;
+function isAppendFlag(flag) {
+    return typeof flag === "string"
+        ? flag.includes("a")
+        : (flag & constants.O_APPEND) === constants.O_APPEND;
+}
+function isExclusiveFlag(flag) {
+    return typeof flag === "string"
+        ? flag.includes("x")
+        : (flag & constants.O_EXCL) === constants.O_EXCL;
+}
+function toPermissionBits(mode) {
+    return ((typeof mode === "string" ? Number.parseInt(mode, 8) : mode) &
+        PERMISSION_BITS);
+}
+/**
+ * The temporary file sits beside the destination: `rename` is only atomic
+ * within one filesystem, so a system temporary directory would break it.
+ */
+function temporaryPathFor(filePath) {
+    const suffix = `.tmp-${randomUUID()}`;
+    if (filePath instanceof URL) {
+        // `pathname` is percent-encoded; `fileURLToPath` also rejects non-`file:`.
+        return fileURLToPath(filePath) + suffix;
+    }
+    if (Buffer.isBuffer(filePath)) {
+        return Buffer.concat([filePath, Buffer.from(suffix)]);
+    }
+    return filePath + suffix;
+}
+function fileAlreadyExistsError(filePath) {
+    const path = filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+    const errno = -osConstants.errno.EEXIST;
+    return Object.assign(new Error(`EEXIST: file already exists, open '${String(path)}'`), {
+        code: "EEXIST",
+        errno,
+        syscall: "open",
+        path,
+        info: { errno, syscall: "open", path },
+    });
+}
+/**
+ * Replaces a file's contents in one step: a reader sees either the previous
+ * contents or the new ones, never a partial write.
+ *
+ * The data goes to a uniquely named temporary file beside the destination,
+ * which is then `rename`d over it. `rename` replaces the destination
+ * atomically, so no window exists in which the path is missing.
+ *
+ * Appending is rejected — `flag: "a"` and `O_APPEND` throw. Staging an append
+ * means copying the destination into the temporary file and appending there,
+ * which silently discards whatever another process wrote in between: the
+ * opposite of what an appender expects. Read, concatenate and replace instead,
+ * serialising the writers yourself when there is more than one:
+ *
+ * ```ts
+ * const current = await readFile(path, "utf8").catch(() => "");
+ * await writeFileAtomic(path, `${current}${line}\n`);
+ * ```
+ *
+ * When the destination already exists its permission bits carry over, unless
+ * `options.mode` says otherwise. Ownership does not: the replacement belongs to
+ * the calling user.
+ *
+ * Durability is a separate concern from atomicity — pass `flush: true` to fsync
+ * the data before the rename. The parent directory is never fsynced, so the
+ * rename itself may still be lost to a power failure.
+ *
+ * @param filePath The path to replace.
+ * @param data The contents to write.
+ * @param options Encoding, mode, flag, flush and abort signal, as for
+ *   `fs.writeFile`. `flag` may only select exclusive creation (`"wx"`,
+ *   `O_EXCL`); appending throws.
+ * @returns A promise that resolves once the destination holds the new contents.
+ * @throws {TypeError} When `options.flag` requests an append.
+ * @throws When the destination exists and `options.flag` is exclusive (`code:
+ *   "EEXIST"`), or when any underlying syscall fails.
+ */
+export async function writeFileAtomic(filePath, data, options) {
+    const flag = options?.flag ?? NODE_WRITE_FILE_DEFAULT_OPTIONS.flag;
+    if (isAppendFlag(flag)) {
+        throw new TypeError("writeFileAtomic cannot append: staging an append drops concurrent writes. Read the file and write the concatenation instead.");
+    }
+    let stats;
+    try {
+        stats = await stat(filePath);
+    }
+    catch { }
+    if (stats && isExclusiveFlag(flag)) {
+        throw fileAlreadyExistsError(filePath);
+    }
+    const effectiveOptions = defaults(options, NODE_WRITE_FILE_DEFAULT_OPTIONS);
+    // Left unset, the mode is the caller's umask business, exactly as for a
+    // plain `writeFile`; set, it has to survive the umask, hence the `chmod`.
+    const requestedMode = options?.mode ?? stats?.mode;
+    const mode = toPermissionBits(requestedMode ?? NODE_WRITE_FILE_DEFAULT_OPTIONS.mode);
+    const tmpFilePath = temporaryPathFor(filePath);
+    try {
+        await writeFile(tmpFilePath, data, {
+            ...effectiveOptions,
+            mode,
+            // The temporary file is always a fresh create under a name of our own.
+            flag: "wx",
+            signal: effectiveOptions.signal ?? undefined,
+        });
+        if (requestedMode !== undefined) {
+            await chmod(tmpFilePath, mode);
+        }
+        await rename(tmpFilePath, filePath);
+    }
+    catch (error) {
+        try {
+            await unlink(tmpFilePath);
+        }
+        catch { }
+        throw error;
+    }
+}
+//# sourceMappingURL=write-file-atomic.js.map

package/dist/fs/write-file-atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-atomic.js","sourceRoot":"","sources":["../../src/fs/write-file-atomic.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export * from "./child-process/exec-async.js";
+export * from "./error/node-aggregate-error.js";
+export * from "./error/node-error.js";
+export * from "./error/node-exec-error.js";
+export * from "./error/node-system-error.js";
+export * from "./error/process-exit-error.js";
+export * from "./fs/compress-file.js";
+export * from "./fs/create-temp-dir.js";
+export * from "./fs/escape-path.js";
+export * from "./fs/exists-async.js";
+export * from "./fs/file-content-equal.js";
+export * from "./fs/is-directory-async.js";
+export * from "./fs/types.js";
+export * from "./fs/walk-paths.js";
+export * from "./fs/write-file-atomic.js";
+export * from "./module/import-module.js";
+export * from "./module/optional-import.js";
+export * from "./module/resolve-module.js";
+export * from "./net/dgram-socket.js";
+export * from "./net/ipc-socket.js";
+export * from "./net/stream-socket.js";
+export * from "./net/tcp-server.js";
+export * from "./net/tcp-socket.js";
+export * from "./net/tls-socket.js";
+export * from "./process/fork-process.js";
+export * from "./process/guarded.js";
+export * from "./process/spawn-process.js";
+export * from "./process/spawned-process.js";
+export * from "./process/start-process.js";
+export * from "./shell/escape-command-arg.js";
+export * from "./shell/escape-command.js";
+export * from "./stream/non-closing-writable-stream.js";
+export * from "./stream/write-async.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+export * from "./child-process/exec-async.js";
+export * from "./error/node-aggregate-error.js";
+export * from "./error/node-error.js";
+export * from "./error/node-exec-error.js";
+export * from "./error/node-system-error.js";
+export * from "./error/process-exit-error.js";
+export * from "./fs/compress-file.js";
+export * from "./fs/create-temp-dir.js";
+export * from "./fs/escape-path.js";
+export * from "./fs/exists-async.js";
+export * from "./fs/file-content-equal.js";
+export * from "./fs/is-directory-async.js";
+export * from "./fs/types.js";
+export * from "./fs/walk-paths.js";
+export * from "./fs/write-file-atomic.js";
+export * from "./module/import-module.js";
+export * from "./module/optional-import.js";
+export * from "./module/resolve-module.js";
+export * from "./net/dgram-socket.js";
+export * from "./net/ipc-socket.js";
+export * from "./net/stream-socket.js";
+export * from "./net/tcp-server.js";
+export * from "./net/tcp-socket.js";
+export * from "./net/tls-socket.js";
+export * from "./process/fork-process.js";
+export * from "./process/guarded.js";
+export * from "./process/spawn-process.js";
+export * from "./process/spawned-process.js";
+export * from "./process/start-process.js";
+export * from "./shell/escape-command-arg.js";
+export * from "./shell/escape-command.js";
+export * from "./stream/non-closing-writable-stream.js";
+export * from "./stream/write-async.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,yBAAyB,CAAC"}

package/dist/module/import-module.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Import module at runtime with custom resolve paths.
+ *
+ * If used, the resolve paths will be used instead of the default node.js ones,
+ * except for the GLOBAL_FOLDERS like $HOME/.node_modules, which are always
+ * included.
+ *
+ * @param id The module to load
+ * @param resolvePaths The paths to use to resolve the module
+ * @returns The loaded module
+ */
+export declare function importModule<T>(id: string, resolvePaths?: string[]): Promise<T>;
+//# sourceMappingURL=import-module.d.ts.map

package/dist/module/import-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-module.d.ts","sourceRoot":"","sources":["../../src/module/import-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,CAAC,EACnC,EAAE,EAAE,MAAM,EACV,YAAY,CAAC,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/module/import-module.js

@@ -0,0 +1,18 @@
+/**
+ * Import module at runtime with custom resolve paths.
+ *
+ * If used, the resolve paths will be used instead of the default node.js ones,
+ * except for the GLOBAL_FOLDERS like $HOME/.node_modules, which are always
+ * included.
+ *
+ * @param id The module to load
+ * @param resolvePaths The paths to use to resolve the module
+ * @returns The loaded module
+ */
+export async function importModule(id, resolvePaths) {
+    if (resolvePaths && resolvePaths.length > 0) {
+        id = require.resolve(id, { paths: resolvePaths });
+    }
+    return import(id);
+}
+//# sourceMappingURL=import-module.js.map

package/dist/module/import-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-module.js","sourceRoot":"","sources":["../../src/module/import-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,EAAU,EACV,YAAuB;IAEvB,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC;AACnB,CAAC"}

package/dist/module/optional-import.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Import a module optionally, returning `null` if the module is not found.
+ *
+ * This is useful for optional peer dependencies, where a module may or may not
+ * be installed.
+ *
+ * `load` must contain a literal `import("specifier")` expression written in the
+ * caller's own module: dynamic import specifiers resolve against the file the
+ * expression is written in, not the file that happens to invoke `load` at
+ * runtime. Passing a specifier string here instead would resolve it against
+ * this module's own dependencies, which fails under strict (non-hoisting)
+ * package managers whenever the optional dependency belongs to the caller
+ * instead.
+ *
+ * @param load - A thunk containing the `import("specifier")` expression.
+ * @returns The imported module, or `null` if the module cannot be found.
+ */
+export declare function optionalImport<T>(load: () => Promise<T>): Promise<T | null>;
+//# sourceMappingURL=optional-import.d.ts.map

package/dist/module/optional-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-import.d.ts","sourceRoot":"","sources":["../../src/module/optional-import.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CASnB"}

package/dist/module/optional-import.js

@@ -0,0 +1,30 @@
+import { isNodeErrorWithCode } from "../error/node-error.js";
+/**
+ * Import a module optionally, returning `null` if the module is not found.
+ *
+ * This is useful for optional peer dependencies, where a module may or may not
+ * be installed.
+ *
+ * `load` must contain a literal `import("specifier")` expression written in the
+ * caller's own module: dynamic import specifiers resolve against the file the
+ * expression is written in, not the file that happens to invoke `load` at
+ * runtime. Passing a specifier string here instead would resolve it against
+ * this module's own dependencies, which fails under strict (non-hoisting)
+ * package managers whenever the optional dependency belongs to the caller
+ * instead.
+ *
+ * @param load - A thunk containing the `import("specifier")` expression.
+ * @returns The imported module, or `null` if the module cannot be found.
+ */
+export async function optionalImport(load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ERR_MODULE_NOT_FOUND")) {
+            return null;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=optional-import.js.map

package/dist/module/optional-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-import.js","sourceRoot":"","sources":["../../src/module/optional-import.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,IAAsB;IAEtB,IAAI,CAAC;QACJ,OAAO,MAAM,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,CAAC,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC;QACb,CAAC;QACD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC"}

package/dist/module/resolve-module.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve a module id to its full path.
+ *
+ * If defined, the resolve paths will be used instead of the default node.js
+ * ones, except for the GLOBAL_FOLDERS like $HOME/.node_modules, which are
+ * always included.
+ *
+ * @param id Module identifier
+ * @param resolvePaths Optional paths to use to resolve the module
+ * @returns The resolved module path, or null if it cannot be found.
+ */
+export declare function resolveModule(id: string, resolvePaths?: string[]): string | null;
+//# sourceMappingURL=resolve-module.d.ts.map

package/dist/module/resolve-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-module.d.ts","sourceRoot":"","sources":["../../src/module/resolve-module.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC5B,EAAE,EAAE,MAAM,EACV,YAAY,CAAC,EAAE,MAAM,EAAE,GACrB,MAAM,GAAG,IAAI,CAcf"}

package/dist/module/resolve-module.js

@@ -0,0 +1,26 @@
+import { isNodeErrorWithCode } from "../error/node-error.js";
+/**
+ * Resolve a module id to its full path.
+ *
+ * If defined, the resolve paths will be used instead of the default node.js
+ * ones, except for the GLOBAL_FOLDERS like $HOME/.node_modules, which are
+ * always included.
+ *
+ * @param id Module identifier
+ * @param resolvePaths Optional paths to use to resolve the module
+ * @returns The resolved module path, or null if it cannot be found.
+ */
+export function resolveModule(id, resolvePaths) {
+    let result;
+    try {
+        result = require.resolve(id, { paths: resolvePaths });
+    }
+    catch (error) {
+        if (!isNodeErrorWithCode(error, "MODULE_NOT_FOUND")) {
+            throw error;
+        }
+        result = null;
+    }
+    return result;
+}
+//# sourceMappingURL=resolve-module.js.map

package/dist/module/resolve-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-module.js","sourceRoot":"","sources":["../../src/module/resolve-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC5B,EAAU,EACV,YAAuB;IAEvB,IAAI,MAAqB,CAAC;IAE1B,IAAI,CAAC;QACJ,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,CAAC,EAAE,CAAC;YACrD,MAAM,KAAK,CAAC;QACb,CAAC;QAED,MAAM,GAAG,IAAI,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/net/dgram-socket.d.ts

@@ -0,0 +1,235 @@
+import * as dgram from "node:dgram";
+import { EventDispatcherMapBase, IEventDispatcherMap } from "@ac-kit/async";
+import { InetEndpoint, type IError } from "@ac-kit/core";
+import type { Except, TypedArray } from "type-fest";
+/** Event map for DgramSocket socket-specific events. */
+export type DgramSocketEvents = {
+    /** Emitted when the socket is closed. */
+    close: [];
+    /** Emitted after a socket is addressed using `bind()`. */
+    connect: [];
+    /** Emitted when an error occurs. */
+    error: [error: IError];
+    /** Emitted when the socket is ready to receive data. */
+    listening: [];
+    /**
+     * Emitted when a new datagram is available on a socket.
+     *
+     * @param msg - The message buffer received
+     * @param msgSize - The size of the message in bytes
+     * @param from - The sender's endpoint information (address, port, and family)
+     */
+    message: [msg: Buffer, msgSize: number, from: InetEndpoint];
+};
+export interface DgramSocketStat {
+    /** The number of datagrams currently queued for sending. */
+    sendQueueCount: number;
+    /** The total number of bytes currently queued for sending. */
+    sendQueueSize: number;
+}
+/**
+ * High-level wrapper around Node.js
+ * {@link dgram.Socket | UDP datagram sockets}.
+ *
+ * This class delegates almost all behavior to an underlying
+ * {@link dgram.Socket} instance while:
+ *
+ * - Providing strongly-typed events via {@link DgramSocketEvents}.
+ * - Using {@link InetEndpoint} instead of Node's `RemoteInfo`.
+ * - Exposing promise-based {@link DgramSocket.bind | bind} and
+ *   {@link DgramSocket.close | close} helpers.
+ * - Aggregating send-queue statistics through {@link DgramSocket.getStat}.
+ *
+ * Unless explicitly documented otherwise, methods have the same semantics as
+ * their counterparts on {@link dgram.Socket}.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * 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();
+ * ```
+ */
+export declare class DgramSocket extends EventDispatcherMapBase<DgramSocketEvents> implements IEventDispatcherMap<DgramSocketEvents> {
+    private readonly sock;
+    /** Creates a new `DgramSocket` instance with the specified options. */
+    static from(options?: dgram.SocketOptions): DgramSocket;
+    private readonly handledErrorEvents;
+    /**
+     * Constructs a new `DgramSocket` instance wrapping the provided
+     * `dgram.Socket`.
+     */
+    constructor(sock: dgram.Socket);
+    /**
+     * References the socket, preventing the process from exiting while the socket
+     * is active.
+     */
+    ref(): void;
+    /**
+     * Unreferences the socket, allowing the process to exit even if the socket is
+     * active.
+     */
+    unref(): void;
+    /**
+     * Enables or disables sending of broadcast datagrams.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setBroadcast}, which
+     * toggles the `SO_BROADCAST` socket option. When enabled, UDP packets may be
+     * sent to broadcast addresses.
+     *
+     * @param flag Whether broadcast should be enabled.
+     */
+    setBroadcast(flag: boolean): void;
+    /**
+     * Adds this socket to the given multicast group.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.addMembership}, which
+     * configures `IP_ADD_MEMBERSHIP` for the given multicast group.
+     */
+    addMembership(multicastAddress: string, multicastInterface?: string): void;
+    /**
+     * Sets the size in bytes of the underlying receive buffer.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setRecvBufferSize}, which
+     * sets the `SO_RCVBUF` socket option.
+     */
+    setRecvBufferSize(size: number): void;
+    /**
+     * Returns the size in bytes of the underlying receive buffer.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.getRecvBufferSize}, which
+     * reads the `SO_RCVBUF` socket option.
+     */
+    getRecvBufferSize(): number;
+    /**
+     * Sets the size in bytes of the underlying send buffer.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setSendBufferSize}, which
+     * sets the `SO_SNDBUF` socket option.
+     */
+    setSendBufferSize(size: number): void;
+    /**
+     * Returns the size in bytes of the underlying send buffer.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.getSendBufferSize}, which
+     * reads the `SO_SNDBUF` socket option.
+     */
+    getSendBufferSize(): number;
+    /**
+     * Removes this socket from the given multicast group.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.dropMembership}, which
+     * configures `IP_DROP_MEMBERSHIP` for the given multicast group.
+     */
+    dropMembership(multicastAddress: string, multicastInterface?: string): void;
+    /**
+     * Adds this socket to a source-specific multicast group.
+     *
+     * This is a thin wrapper around
+     * {@link dgram.Socket.addSourceSpecificMembership}, configuring
+     * source-specific multicast membership for the given source and group.
+     */
+    addSourceMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void;
+    /**
+     * Removes this socket from a source-specific multicast group.
+     *
+     * This is a thin wrapper around
+     * {@link dgram.Socket.dropSourceSpecificMembership}, removing source-specific
+     * multicast membership for the given source and group.
+     */
+    dropSourceMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void;
+    /**
+     * Sets the outbound multicast interface.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setMulticastInterface},
+     * which controls the default outgoing interface for multicast traffic.
+     */
+    setMulticastInterface(multicastInterface: string): void;
+    /**
+     * Enables or disables loopback for multicast packets sent from this socket.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setMulticastLoopback},
+     * which toggles the `IP_MULTICAST_LOOP` socket option.
+     */
+    setMulticastLoop(flag: boolean): void;
+    /**
+     * Sets the time-to-live (TTL) value for multicast packets.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setMulticastTTL}, which
+     * configures the `IP_MULTICAST_TTL` socket option.
+     */
+    setMulticastTtl(ttl: number): void;
+    /**
+     * Sets the unicast time-to-live (TTL) value for outgoing packets.
+     *
+     * This is a thin wrapper around {@link dgram.Socket.setTTL}, which configures
+     * the `IP_TTL` socket option.
+     */
+    setTtl(ttl: number): void;
+    /**
+     * Gets the address information of the bound socket.
+     *
+     * @returns The socket's endpoint information or null if the socket is not
+     *   bound.
+     * @throws {UnsupportedError} If the address type is not an AddressInfo
+     *   object.
+     */
+    address(): InetEndpoint | null;
+    /**
+     * Binds the UDP socket to the specified address and port.
+     *
+     * @param port The port to bind to. If not specified, a random available port
+     *   will be used.
+     * @param address The address to bind to. If not specified, the socket will
+     *   bind to all available interfaces.
+     * @param options Binding options.
+     * @returns A promise that resolves when the socket is successfully bound.
+     */
+    bind(port?: number, address?: string, options?: Except<dgram.BindOptions, "address" | "port">): Promise<void>;
+    /**
+     * Closes the UDP socket.
+     *
+     * @returns A promise that resolves when the socket is successfully closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns statistics about the underlying send queue.
+     *
+     * This wraps {@link dgram.Socket.getSendQueueCount} and
+     * {@link dgram.Socket.getSendQueueSize} into a single object.
+     */
+    getStat(): DgramSocketStat;
+    /**
+     * 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.
+     *
+     * @param port The destination port.
+     * @param address The destination address.
+     * @param msg The message to send. This can be a `Buffer`, `TypedArray`, or
+     *   `DataView`.
+     * @param offset Optional offset in the message buffer to start sending from.
+     * @param length Optional number of bytes to send from the message buffer.
+     * @returns A promise that resolves with the number of bytes sent.
+     */
+    send(port: number, address: string, msg: string | TypedArray | DataView, offset?: number, length?: number): Promise<number>;
+    private setupEventForwarding;
+}
+//# sourceMappingURL=dgram-socket.d.ts.map

package/dist/net/dgram-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dgram-socket.d.ts","sourceRoot":"","sources":["../../src/net/dgram-socket.ts"],"names":[],"mappings":"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"}