@ac-kit/node 0.1.0

package/dist/net/dgram-socket.js

@@ -0,0 +1,341 @@
+import * as dgram from "node:dgram";
+import { EventDispatcherMapBase } from "@ac-kit/async";
+import { composeInetAddress } from "@ac-kit/core";
+import { isNodeErrorWithCode } from "../error/node-error.js";
+/**
+ * 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 class DgramSocket extends EventDispatcherMapBase {
+    sock;
+    /** Creates a new `DgramSocket` instance with the specified options. */
+    static from(options) {
+        return new DgramSocket(dgram.createSocket(options || { type: "udp4" }));
+    }
+    handledErrorEvents = new Set();
+    /**
+     * Constructs a new `DgramSocket` instance wrapping the provided
+     * `dgram.Socket`.
+     */
+    constructor(sock) {
+        super();
+        this.sock = sock;
+        this.setupEventForwarding();
+    }
+    /**
+     * References the socket, preventing the process from exiting while the socket
+     * is active.
+     */
+    ref() {
+        this.sock.ref();
+    }
+    /**
+     * Unreferences the socket, allowing the process to exit even if the socket is
+     * active.
+     */
+    unref() {
+        this.sock.unref();
+    }
+    /**
+     * 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) {
+        this.sock.setBroadcast(flag);
+    }
+    /**
+     * 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, multicastInterface) {
+        this.sock.addMembership(multicastAddress, multicastInterface);
+    }
+    /**
+     * 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) {
+        this.sock.setRecvBufferSize(size);
+    }
+    /**
+     * 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() {
+        return this.sock.getRecvBufferSize();
+    }
+    /**
+     * 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) {
+        this.sock.setSendBufferSize(size);
+    }
+    /**
+     * 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() {
+        return this.sock.getSendBufferSize();
+    }
+    /**
+     * 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, multicastInterface) {
+        this.sock.dropMembership(multicastAddress, multicastInterface);
+    }
+    /**
+     * 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, groupAddress, multicastInterface) {
+        this.sock.addSourceSpecificMembership(sourceAddress, groupAddress, multicastInterface);
+    }
+    /**
+     * 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, groupAddress, multicastInterface) {
+        this.sock.dropSourceSpecificMembership(sourceAddress, groupAddress, multicastInterface);
+    }
+    /**
+     * 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) {
+        this.sock.setMulticastInterface(multicastInterface);
+    }
+    /**
+     * 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) {
+        this.sock.setMulticastLoopback(flag);
+    }
+    /**
+     * 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) {
+        this.sock.setMulticastTTL(ttl);
+    }
+    /**
+     * 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) {
+        this.sock.setTTL(ttl);
+    }
+    /**
+     * 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() {
+        let addr;
+        try {
+            addr = this.sock.address();
+        }
+        catch (error) {
+            // dgram throws "Not running" error when socket is not bound/closed
+            if (isNodeErrorWithCode(error, "EBADF") ||
+                (error instanceof Error && error.message === "Not running")) {
+                return null;
+            }
+            throw error;
+        }
+        return {
+            ...composeInetAddress(addr.family, addr.address),
+            port: addr.port,
+        };
+    }
+    /**
+     * 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 = 0, address, options) {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            this.sock.prependOnceListener("error", handleError);
+            try {
+                this.sock.bind({
+                    ...options,
+                    address,
+                    port,
+                }, () => {
+                    this.sock.removeListener("error", handleError);
+                    resolve();
+                });
+            }
+            catch (error) {
+                this.sock.removeListener("error", handleError);
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Closes the UDP socket.
+     *
+     * @returns A promise that resolves when the socket is successfully closed.
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            this.sock.prependOnceListener("error", handleError);
+            this.sock.close(() => {
+                this.sock.removeListener("error", handleError);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Returns statistics about the underlying send queue.
+     *
+     * This wraps {@link dgram.Socket.getSendQueueCount} and
+     * {@link dgram.Socket.getSendQueueSize} into a single object.
+     */
+    getStat() {
+        return {
+            sendQueueCount: this.sock.getSendQueueCount(),
+            sendQueueSize: this.sock.getSendQueueSize(),
+        };
+    }
+    /**
+     * 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, address, msg, offset, length) {
+        return new Promise((resolve, reject) => {
+            const callback = (error, bytes) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(bytes);
+            };
+            if (offset === undefined || length === undefined) {
+                this.sock.send(msg, port, address, callback);
+                return;
+            }
+            this.sock.send(msg, offset, length, port, address, callback);
+        });
+    }
+    setupEventForwarding() {
+        this.sock.on("close", () => {
+            this.dispatch("close", []);
+        });
+        this.sock.on("connect", () => {
+            this.dispatch("connect", []);
+        });
+        this.sock.on("error", (err) => {
+            if (this.handledErrorEvents.has(err)) {
+                this.handledErrorEvents.delete(err);
+                return;
+            }
+            this.dispatch("error", [err]);
+        });
+        this.sock.on("listening", () => {
+            this.dispatch("listening", []);
+        });
+        this.sock.on("message", (msg, rinfo) => {
+            const from = {
+                ...composeInetAddress(rinfo.family, rinfo.address),
+                port: rinfo.port,
+            };
+            this.dispatch("message", [msg, rinfo.size, from]);
+        });
+    }
+}
+//# sourceMappingURL=dgram-socket.js.map

package/dist/net/dgram-socket.js.map

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

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

@@ -0,0 +1,34 @@
+import * as net from "node:net";
+import { InetEndpoint } from "@ac-kit/core";
+import type { Except } from "type-fest";
+import { StreamSocket, type StreamSocketEvents } from "./stream-socket.js";
+export type IpcSocketEvents = StreamSocketEvents & {
+    /**
+     * Emitted when a new connection attempt is started. May be emitted multiple
+     * times if family autoselection is enabled.
+     */
+    connectionAttempt: [endpoint: InetEndpoint];
+    /**
+     * Emitted when a connection attempt failed. May be emitted multiple times if
+     * family autoselection is enabled.
+     */
+    connectionAttemptFailed: [endpoint: InetEndpoint, error: Error];
+    /**
+     * Emitted when a connection attempt timed out. May be emitted multiple times
+     * if family autoselection is enabled.
+     */
+    connectionAttemptTimeout: [endpoint: InetEndpoint];
+};
+export declare class IpcSocket<TSock extends net.Socket = net.Socket, TEvents extends IpcSocketEvents = IpcSocketEvents> extends StreamSocket<TSock, TEvents> {
+    /**
+     * Creates a new {@link IpcSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `StreamSocket` instance.
+     */
+    static from(options?: net.SocketConstructorOpts): IpcSocket;
+    constructor(sock: TSock);
+    connect(path: string, options?: Except<net.IpcSocketConnectOpts, "path">): Promise<void>;
+    protected setupEventForwarding(): void;
+}
+//# sourceMappingURL=ipc-socket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-socket.d.ts","sourceRoot":"","sources":["../../src/net/ipc-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAsB,YAAY,EAAe,MAAM,cAAc,CAAC;AAC7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IAClD;;;OAGG;IACH,iBAAiB,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAE5C;;;OAGG;IACH,uBAAuB,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAEhE;;;OAGG;IACH,wBAAwB,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;CACnD,CAAC;AAEF,qBAAa,SAAS,CACrB,KAAK,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EACrC,OAAO,SAAS,eAAe,GAAG,eAAe,CAChD,SAAQ,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC;IACrC;;;;;OAKG;IACH,OAAgB,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,qBAAqB,GAAG,SAAS,CAEnE;IAED,YAAY,IAAI,EAAE,KAAK,EAGtB;IAED,OAAO,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,GAChD,OAAO,CAAC,IAAI,CAAC,CAmBf;IAED,UAAmB,oBAAoB,IAAI,IAAI,CA8B9C;CACD"}

package/dist/net/ipc-socket.js

@@ -0,0 +1,63 @@
+import * as net from "node:net";
+import { composeInetAddress } from "@ac-kit/core";
+import { StreamSocket } from "./stream-socket.js";
+export class IpcSocket extends StreamSocket {
+    /**
+     * Creates a new {@link IpcSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `StreamSocket` instance.
+     */
+    static from(options) {
+        return new IpcSocket(new net.Socket(options));
+    }
+    constructor(sock) {
+        super(sock);
+        this.setupEventForwarding();
+    }
+    connect(path, options) {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            this.sock.prependOnceListener("error", handleError);
+            this.sock.connect({
+                ...options,
+                path,
+            }, () => {
+                this.sock.removeListener("error", handleError);
+                resolve();
+            });
+        });
+    }
+    setupEventForwarding() {
+        super.setupEventForwarding();
+        this.sock.on("connectionAttempt", (ip, port, family) => {
+            this.dispatch("connectionAttempt", [
+                {
+                    ...composeInetAddress(family, ip),
+                    port,
+                },
+            ]);
+        });
+        this.sock.on("connectionAttemptFailed", (ip, port, family, error) => {
+            this.dispatch("connectionAttemptFailed", [
+                {
+                    ...composeInetAddress(family, ip),
+                    port,
+                },
+                error,
+            ]);
+        });
+        this.sock.on("connectionAttemptTimeout", (ip, port, family) => {
+            this.dispatch("connectionAttemptTimeout", [
+                {
+                    ...composeInetAddress(family, ip),
+                    port,
+                },
+            ]);
+        });
+    }
+}
+//# sourceMappingURL=ipc-socket.js.map

package/dist/net/ipc-socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-socket.js","sourceRoot":"","sources":["../../src/net/ipc-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,kBAAkB,EAA6B,MAAM,cAAc,CAAC;AAG7E,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAsB3E,MAAM,OAAO,SAGX,SAAQ,YAA4B;IACrC;;;;;OAKG;IACH,MAAM,CAAU,IAAI,CAAC,OAAmC;QACvD,OAAO,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,YAAY,IAAW;QACtB,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,CACN,IAAY,EACZ,OAAkD;QAElD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,EAAE;gBACrC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBACnC,MAAM,CAAC,KAAK,CAAC,CAAC;YACf,CAAC,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAEpD,IAAI,CAAC,IAAI,CAAC,OAAO,CAChB;gBACC,GAAG,OAAO;gBACV,IAAI;aACJ,EACD,GAAG,EAAE;gBACJ,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBAC/C,OAAO,EAAE,CAAC;YACX,CAAC,CACD,CAAC;QACH,CAAC,CAAC,CAAC;IACJ,CAAC;IAEkB,oBAAoB;QACtC,KAAK,CAAC,oBAAoB,EAAE,CAAC;QAE7B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YACtD,IAAI,CAAC,QAAQ,CAAC,mBAAmB,EAAE;gBAClC;oBACC,GAAG,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC;oBACjC,IAAI;iBACJ;aACD,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,yBAAyB,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;YACnE,IAAI,CAAC,QAAQ,CAAC,yBAAyB,EAAE;gBACxC;oBACC,GAAG,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC;oBACjC,IAAI;iBACJ;gBACD,KAAK;aACL,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,0BAA0B,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC7D,IAAI,CAAC,QAAQ,CAAC,0BAA0B,EAAE;gBACzC;oBACC,GAAG,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC;oBACjC,IAAI;iBACJ;aACD,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}

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

@@ -0,0 +1,156 @@
+import * as net from "node:net";
+import type * as stream from "node:stream";
+import { EventDispatcherMapBase, IEventDispatcherMap } from "@ac-kit/async";
+import { type IError } from "@ac-kit/core";
+/**
+ * Event map for {@link StreamSocket} lifecycle events.
+ *
+ * These correspond to the core {@link net.Socket} events that are meaningful for
+ * any stream-oriented connection, regardless of the underlying transport (TCP,
+ * Unix domain socket, etc.).
+ */
+export type StreamSocketEvents = {
+    /**
+     * Emitted when an error occurs on the underlying socket.
+     *
+     * After this event the implementation will typically attempt to close the
+     * socket and then emit {@link StreamSocketEvents.close}.
+     */
+    error: [error: IError];
+    /**
+     * Emitted once the socket has been fully closed.
+     *
+     * After this event the socket is no longer usable.
+     */
+    close: [hadError: boolean];
+    /**
+     * Emitted when the socket connection is successfully established.
+     *
+     * This maps to the underlying {@link net.Socket} "connect" event.
+     */
+    connect: [];
+    /**
+     * Emitted when the socket is ready for I/O.
+     *
+     * On Node.js this is typically fired immediately after "connect", once the
+     * internal initialization is complete.
+     */
+    ready: [];
+    /**
+     * Emitted if the socket times out from inactivity.
+     *
+     * The underlying connection is not automatically closed; it is up to the
+     * caller to decide whether to end or destroy the socket.
+     */
+    timeout: [];
+};
+/**
+ * Base class for stream-oriented client sockets.
+ *
+ * This abstraction wraps a {@link net.Socket} instance and exposes:
+ *
+ * - A stable, duplex {@link stream} for reading and writing data.
+ * - Common lifecycle properties such as {@link closed}, {@link destroyed},
+ *   {@link bytesRead}, {@link bytesWritten} and {@link connecting}.
+ * - Timeout management via the {@link timeout} property.
+ * - Promise-based {@link end} and {@link write} helpers.
+ * - Strongly-typed lifecycle events via {@link StreamSocketEvents}.
+ *
+ * It is intentionally transport-agnostic: it does not assume a particular
+ * address family or protocol. Concrete subclasses such as {@link TcpSocket} add
+ * protocol-specific concerns (for example `InetEndpoint` accessors, TCP
+ * keep-alive configuration, or DNS resolution events) on top of this base.
+ *
+ * Unless explicitly documented otherwise, methods mirror the semantics of their
+ * underlying {@link net.Socket} counterparts.
+ */
+export declare class StreamSocket<TSock extends net.Socket = net.Socket, TEvents extends StreamSocketEvents = StreamSocketEvents> extends EventDispatcherMapBase<TEvents> implements IEventDispatcherMap<TEvents> {
+    protected readonly sock: TSock;
+    protected readonly handledErrorEvents: Set<IError>;
+    /**
+     * Creates a new {@link StreamSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `StreamSocket` instance.
+     */
+    static from(options?: net.SocketConstructorOpts): StreamSocket;
+    /**
+     * Creates a new {@link StreamSocket} instance.
+     *
+     * @param sock The underlying Node.js socket.
+     */
+    constructor(sock: TSock);
+    /**
+     * Underlying duplex stream for reading and writing data.
+     *
+     * This is the wrapped {@link net.Socket} instance and can be passed directly
+     * to APIs that expect a Node.js stream.
+     */
+    get stream(): stream.Duplex;
+    /** Indicates whether the socket has been fully closed. */
+    get closed(): boolean;
+    /** Indicates whether the underlying socket has been destroyed. */
+    get destroyed(): boolean;
+    /** Total number of bytes read from the socket so far. */
+    get bytesRead(): number;
+    /** Total number of bytes written to the socket so far. */
+    get bytesWritten(): number;
+    /** Whether the socket is currently in the process of connecting. */
+    get connecting(): boolean;
+    /** Current inactivity timeout in milliseconds, or `null` if disabled. */
+    get timeout(): number | null;
+    /**
+     * Updates the inactivity timeout for the socket.
+     *
+     * When set to a positive number, the socket emits a "timeout" event if no I/O
+     * activity occurs within the given number of milliseconds. A value of `0` or
+     * `null` disables the timeout entirely.
+     */
+    set timeout(timeout: number | null);
+    /**
+     * Marks the socket as referenced, preventing the Node.js process from exiting
+     * while the socket is active.
+     */
+    ref(): void;
+    /**
+     * Marks the socket as unreferenced, allowing the Node.js process to exit even
+     * if the socket is still active.
+     */
+    unref(): void;
+    /**
+     * Half-closes the socket, optionally waiting for a full close.
+     *
+     * If `waitForClose` is omitted or `false`, the promise resolves once the
+     * local side has finished sending data and the FIN has been queued. When
+     * `waitForClose` is `true`, the promise resolves only after the remote side
+     * has also closed and the "close" event has fired.
+     *
+     * @param options Optional settings for ending the socket.
+     * @returns A promise that resolves once the socket has ended.
+     */
+    end(options?: {
+        waitForClose?: boolean;
+    }): Promise<void>;
+    /**
+     * Writes data to the socket and resolves once that chunk has been flushed.
+     *
+     * Awaiting the result is what applies backpressure: the promise settles on
+     * the chunk's own flush rather than on the whole buffer draining, so a
+     * producer that awaits each write never outruns the socket. A caller that
+     * does not await is free to queue without bound.
+     *
+     * @param data The data to write.
+     * @throws When the socket errors or is destroyed before the chunk flushes.
+     */
+    write(data: Uint8Array): Promise<void>;
+    /**
+     * Immediately destroys the underlying socket.
+     *
+     * Pending I/O is discarded, the connection is closed and the socket
+     * transitions to a terminal state. Any registered "close" listeners will
+     * still be invoked.
+     */
+    destroy(): void;
+    protected setupEventForwarding(): void;
+}
+//# sourceMappingURL=stream-socket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream-socket.d.ts","sourceRoot":"","sources":["../../src/net/stream-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC;;;;;OAKG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAEvB;;;;OAIG;IACH,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE3B;;;;OAIG;IACH,OAAO,EAAE,EAAE,CAAC;IAEZ;;;;;OAKG;IACH,KAAK,EAAE,EAAE,CAAC;IAEV;;;;;OAKG;IACH,OAAO,EAAE,EAAE,CAAC;CACZ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY,CACxB,KAAK,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EACrC,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,CAEvD,SAAQ,sBAAsB,CAAC,OAAO,CACtC,YAAW,mBAAmB,CAAC,OAAO,CAAC;IAmB3B,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK;IAjB1C,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAa;IAE/D;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,qBAAqB,GAAG,YAAY,CAE7D;IAED;;;;OAIG;IACH,YAA+B,IAAI,EAAE,KAAK,EAGzC;IAED;;;;;OAKG;IACH,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,CAE1B;IAED,0DAA0D;IAC1D,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,kEAAkE;IAClE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yDAAyD;IACzD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,0DAA0D;IAC1D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,oEAAoE;IACpE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,yEAAyE;IACzE,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED;;;;;;OAMG;IACH,IAAI,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAEjC;IAED;;;OAGG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;;;;;OAUG;IACH,GAAG,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBvD;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrC;IAED;;;;;;OAMG;IACH,OAAO,IAAI,IAAI,CAEd;IAED,SAAS,CAAC,oBAAoB,IAAI,IAAI,CAwBrC;CACD"}