@ac-kit/node 0.1.0 → 0.2.0

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

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

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

@@ -0,0 +1,63 @@
+import * as net from "node:net";
+import type { Except } from "type-fest";
+import { IpcSocket } from "./ipc-socket.js";
+import { StreamServer, type StreamServerEvents } from "./stream-server.js";
+/** Event map for {@link IpcServer}. */
+export type IpcServerEvents = StreamServerEvents & {
+    /** Emitted when a new connection is accepted. */
+    connection: [socket: IpcSocket];
+};
+/** Options accepted by {@link IpcServer.from}. */
+export type IpcServerOptions = net.ServerOpts;
+/** Options accepted by {@link IpcServer.listen}. */
+export type IpcServerListenOptions = Except<net.ListenOptions, "port" | "host" | "path" | "handle" | "ipv6Only" | "reusePort">;
+/**
+ * Server accepting connections on a Unix domain socket or a Windows named pipe.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const server = IpcServer.from();
+ * server.subscribe("connection", (socket) => {
+ * 	socket.stream.on("data", (data) => {
+ * 		console.log("Received:", data.toString());
+ * 	});
+ * });
+ * await server.listen("/var/run/app.sock");
+ * // ... later
+ * await server.close();
+ * ```
+ *
+ * On Unix the socket file is removed when the server closes, but not when the
+ * process exits abnormally: a stale file makes the next bind fail with
+ * `EADDRINUSE`.
+ */
+export declare class IpcServer extends StreamServer<net.Server, IpcServerEvents> {
+    /**
+     * Creates a new {@link IpcServer} instance.
+     *
+     * @param options Options for creating the underlying Node.js server.
+     * @returns A new `IpcServer` instance.
+     */
+    static from(options?: IpcServerOptions): IpcServer;
+    /**
+     * Binds the server to the given path and resolves once it is listening.
+     *
+     * @param path Filesystem path of the Unix domain socket, or the name of the
+     *   Windows named pipe.
+     * @param options Additional listen options.
+     * @returns A promise that resolves once the server is listening.
+     * @throws When the path is already in use or cannot be bound.
+     */
+    listen(path: string, options?: IpcServerListenOptions): Promise<void>;
+    /**
+     * Returns the path the server is bound to.
+     *
+     * @returns The bound path, or `null` when the server is not listening.
+     * @throws {UnsupportedError} When the server is bound to an IP endpoint
+     *   rather than a path. Use {@link TcpServer} for those.
+     */
+    address(): string | null;
+    protected setupEventForwarding(): void;
+}
+//# sourceMappingURL=ipc-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-server.d.ts","sourceRoot":"","sources":["../../src/net/ipc-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAGhC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IAClD,iDAAiD;IACjD,UAAU,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAChC,CAAC;AAEF,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,UAAU,CAAC;AAE9C,oDAAoD;AACpD,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAC1C,GAAG,CAAC,aAAa,EACjB,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAC9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAU,SAAQ,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC;IACvE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAEjD;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpE;IAED;;;;;;OAMG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI,CAcvB;IAED,UAAmB,oBAAoB,IAAI,IAAI,CAM9C;CACD"}

package/dist/net/ipc-server.js

@@ -0,0 +1,75 @@
+import * as net from "node:net";
+import { UnsupportedError } from "@ac-kit/core";
+import { IpcSocket } from "./ipc-socket.js";
+import { StreamServer } from "./stream-server.js";
+/**
+ * Server accepting connections on a Unix domain socket or a Windows named pipe.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const server = IpcServer.from();
+ * server.subscribe("connection", (socket) => {
+ * 	socket.stream.on("data", (data) => {
+ * 		console.log("Received:", data.toString());
+ * 	});
+ * });
+ * await server.listen("/var/run/app.sock");
+ * // ... later
+ * await server.close();
+ * ```
+ *
+ * On Unix the socket file is removed when the server closes, but not when the
+ * process exits abnormally: a stale file makes the next bind fail with
+ * `EADDRINUSE`.
+ */
+export class IpcServer extends StreamServer {
+    /**
+     * Creates a new {@link IpcServer} instance.
+     *
+     * @param options Options for creating the underlying Node.js server.
+     * @returns A new `IpcServer` instance.
+     */
+    static from(options) {
+        return new IpcServer(net.createServer(options));
+    }
+    /**
+     * Binds the server to the given path and resolves once it is listening.
+     *
+     * @param path Filesystem path of the Unix domain socket, or the name of the
+     *   Windows named pipe.
+     * @param options Additional listen options.
+     * @returns A promise that resolves once the server is listening.
+     * @throws When the path is already in use or cannot be bound.
+     */
+    listen(path, options) {
+        return this.listenOn({
+            ...options,
+            path,
+        });
+    }
+    /**
+     * Returns the path the server is bound to.
+     *
+     * @returns The bound path, or `null` when the server is not listening.
+     * @throws {UnsupportedError} When the server is bound to an IP endpoint
+     *   rather than a path. Use {@link TcpServer} for those.
+     */
+    address() {
+        const address = this.server.address();
+        if (address === null) {
+            return null;
+        }
+        if (typeof address !== "string") {
+            throw new UnsupportedError(`Unsupported address type: AddressInfo. Expected a path string.`);
+        }
+        return address;
+    }
+    setupEventForwarding() {
+        super.setupEventForwarding();
+        this.server.on("connection", (socket) => {
+            this.dispatch("connection", [new IpcSocket(socket)]);
+        });
+    }
+}
+//# sourceMappingURL=ipc-server.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-server.js","sourceRoot":"","sources":["../../src/net/ipc-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAiB3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,SAAU,SAAQ,YAAyC;IACvE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAA0B;QACrC,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAY,EAAE,OAAgC;QACpD,OAAO,IAAI,CAAC,QAAQ,CAAC;YACpB,GAAG,OAAO;YACV,IAAI;SACJ,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,OAAO;QACN,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAEtC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,gBAAgB,CACzB,gEAAgE,CAChE,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;IAEkB,oBAAoB;QACtC,KAAK,CAAC,oBAAoB,EAAE,CAAC;QAE7B,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;YACvC,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}

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

@@ -1,34 +1,67 @@
 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];
+/**
+ * Event map for {@link IpcSocket}.
+ *
+ * A local endpoint has no name resolution and no connection-attempt fan-out, so
+ * it adds nothing to {@link StreamSocketEvents}.
+ */
+export type IpcSocketEvents = StreamSocketEvents;
+/** Options accepted by {@link IpcSocket.from} and {@link IpcSocket.fromFd}. */
+export type IpcSocketOptions = Except<net.SocketConstructorOpts, "fd">;
+/** Options accepted by {@link IpcSocket.connect}. */
+export type IpcSocketConnectOptions = Except<net.IpcSocketConnectOpts, "path"> & {
+    /** Aborts the connection attempt and destroys the socket. */
+    signal?: AbortSignal;
+};
+/**
+ * Stream socket over a Unix domain socket or a Windows named pipe.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const socket = IpcSocket.from();
+ * await socket.connect("/var/run/app.sock");
+ * await socket.write(Buffer.from("ping\n"));
+ * await socket.end({ waitForClose: true });
+ * ```
+ *
+ * A pipe inherited from a parent process is already connected and is adopted
+ * through {@link IpcSocket.fromFd} instead.
+ */
+export declare class IpcSocket<TSocket extends net.Socket = net.Socket, TEvents extends IpcSocketEvents = IpcSocketEvents> extends StreamSocket<TSocket, TEvents> {
     /**
-     * Emitted when a connection attempt failed. May be emitted multiple times if
-     * family autoselection is enabled.
+     * Creates a new {@link IpcSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `IpcSocket` instance.
      */
-    connectionAttemptFailed: [endpoint: InetEndpoint, error: Error];
+    static from(options?: IpcSocketOptions): IpcSocket;
     /**
-     * Emitted when a connection attempt timed out. May be emitted multiple times
-     * if family autoselection is enabled.
+     * Adopts an already-open file descriptor, such as a pipe inherited from a
+     * parent process. The returned socket is connected and needs no
+     * {@link IpcSocket.connect} call.
+     *
+     * The descriptor is adopted as bidirectional; pass `readable` or `writable`
+     * to adopt a one-way pipe, since Node.js disables both by default for a
+     * descriptor-backed socket.
+     *
+     * @param fd The open file descriptor to adopt.
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new, already connected `IpcSocket` instance.
      */
-    connectionAttemptTimeout: [endpoint: InetEndpoint];
-};
-export declare class IpcSocket<TSock extends net.Socket = net.Socket, TEvents extends IpcSocketEvents = IpcSocketEvents> extends StreamSocket<TSock, TEvents> {
+    static fromFd(fd: number, options?: IpcSocketOptions): IpcSocket;
     /**
-     * Creates a new {@link IpcSocket} instance.
+     * Connects to the endpoint listening on the given path.
      *
-     * @param options Options for creating the underlying Node.js socket.
-     * @returns A new `StreamSocket` instance.
+     * @param path Filesystem path of the Unix domain socket, or the name of the
+     *   Windows named pipe.
+     * @param options Connection options, including an optional abort signal.
+     * @returns A promise that resolves when the connection is established.
+     * @throws When the connection fails, when the socket closes before
+     *   connecting, or when the signal is aborted.
      */
-    static from(options?: net.SocketConstructorOpts): IpcSocket;
-    constructor(sock: TSock);
-    connect(path: string, options?: Except<net.IpcSocketConnectOpts, "path">): Promise<void>;
-    protected setupEventForwarding(): void;
+    connect(path: string, options?: IpcSocketConnectOptions): Promise<void>;
 }
 //# sourceMappingURL=ipc-socket.d.ts.map

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

@@ -1 +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"}
+{"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,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAEjD,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;AAEvE,qDAAqD;AACrD,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAC3C,GAAG,CAAC,oBAAoB,EACxB,MAAM,CACN,GAAG;IACH,6DAA6D;IAC7D,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS,CACrB,OAAO,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EACvC,OAAO,SAAS,eAAe,GAAG,eAAe,CAChD,SAAQ,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC;IACvC;;;;;OAKG;IACH,OAAgB,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAE1D;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAI/D;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtE;CACD"}

package/dist/net/ipc-socket.js

@@ -1,62 +1,66 @@
 import * as net from "node:net";
-import { composeInetAddress } from "@ac-kit/core";
 import { StreamSocket } from "./stream-socket.js";
+/**
+ * Stream socket over a Unix domain socket or a Windows named pipe.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const socket = IpcSocket.from();
+ * await socket.connect("/var/run/app.sock");
+ * await socket.write(Buffer.from("ping\n"));
+ * await socket.end({ waitForClose: true });
+ * ```
+ *
+ * A pipe inherited from a parent process is already connected and is adopted
+ * through {@link IpcSocket.fromFd} instead.
+ */
 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.
+     * @returns A new `IpcSocket` instance.
      */
     static from(options) {
         return new IpcSocket(new net.Socket(options));
     }
-    constructor(sock) {
-        super(sock);
-        this.setupEventForwarding();
+    /**
+     * Adopts an already-open file descriptor, such as a pipe inherited from a
+     * parent process. The returned socket is connected and needs no
+     * {@link IpcSocket.connect} call.
+     *
+     * The descriptor is adopted as bidirectional; pass `readable` or `writable`
+     * to adopt a one-way pipe, since Node.js disables both by default for a
+     * descriptor-backed socket.
+     *
+     * @param fd The open file descriptor to adopt.
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new, already connected `IpcSocket` instance.
+     */
+    static fromFd(fd, options) {
+        return new IpcSocket(new net.Socket({ readable: true, writable: true, ...options, fd }));
     }
+    /**
+     * Connects to the endpoint listening on the given path.
+     *
+     * @param path Filesystem path of the Unix domain socket, or the name of the
+     *   Windows named pipe.
+     * @param options Connection options, including an optional abort signal.
+     * @returns A promise that resolves when the connection is established.
+     * @throws When the connection fails, when the socket closes before
+     *   connecting, or when the signal is aborted.
+     */
     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,
-                },
-            ]);
+        const { signal, ...connectOptions } = options ?? {};
+        return this.awaitReady("connect", {
+            signal,
+            start: () => {
+                this.socket.connect({
+                    ...connectOptions,
+                    path,
+                });
+            },
         });
     }
 }

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

@@ -1 +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"}
+{"version":3,"file":"ipc-socket.js","sourceRoot":"","sources":["../../src/net/ipc-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAIhC,OAAO,EAAE,YAAY,EAA2B,MAAM,oBAAoB,CAAC;AAsB3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,SAGX,SAAQ,YAA8B;IACvC;;;;;OAKG;IACH,MAAM,CAAU,IAAI,CAAC,OAA0B;QAC9C,OAAO,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CAAC,EAAU,EAAE,OAA0B;QACnD,OAAO,IAAI,SAAS,CACnB,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,CAClE,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAY,EAAE,OAAiC;QACtD,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAEpD,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE;YACjC,MAAM;YACN,KAAK,EAAE,GAAG,EAAE;gBACX,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;oBACnB,GAAG,cAAc;oBACjB,IAAI;iBACJ,CAAC,CAAC;YACJ,CAAC;SACD,CAAC,CAAC;IACJ,CAAC;CACD"}

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

@@ -0,0 +1,80 @@
+import * as net from "node:net";
+import { EventDispatcherMapBase, IEventDispatcherMap } from "@ac-kit/async";
+import { type IError } from "@ac-kit/core";
+/** Event map for {@link StreamServer} lifecycle events. */
+export type StreamServerEvents = {
+    /** Emitted once the server stopped listening and all connections ended. */
+    close: [];
+    /** Emitted when an error occurs on the server. */
+    error: [error: IError];
+    /** Emitted once the server is bound and accepting connections. */
+    listening: [];
+};
+/**
+ * Base class for stream-oriented servers.
+ *
+ * This abstraction wraps a {@link net.Server} instance and exposes the lifecycle
+ * that is independent of the transport: binding state, connection accounting,
+ * event-loop referencing and closing.
+ *
+ * Binding and address reporting are transport-specific and are added by the
+ * concrete subclasses {@link TcpServer} and {@link IpcServer}, as is the
+ * "connection" event, whose payload is a socket of the matching type.
+ */
+export declare class StreamServer<TServer extends net.Server = net.Server, TEvents extends StreamServerEvents = StreamServerEvents> extends EventDispatcherMapBase<TEvents> implements IEventDispatcherMap<TEvents> {
+    protected readonly server: TServer;
+    protected readonly handledErrorEvents: Set<IError>;
+    /**
+     * Creates a new {@link StreamServer} instance.
+     *
+     * @param server The underlying Node.js server.
+     */
+    constructor(server: TServer);
+    /** Whether the server is currently listening for connections. */
+    get listening(): boolean;
+    /** Maximum number of concurrent connections accepted by the server. */
+    get maxConnections(): number;
+    /**
+     * Updates the maximum number of concurrent connections.
+     *
+     * Connections accepted beyond this limit are dropped.
+     */
+    set maxConnections(maxConnections: number);
+    /**
+     * Counts the connections currently handled by the server.
+     *
+     * @returns A promise that resolves with the connection count.
+     */
+    getConnections(): Promise<number>;
+    /**
+     * Marks the server as referenced, preventing the Node.js process from exiting
+     * while it is listening.
+     */
+    ref(): void;
+    /**
+     * Marks the server as unreferenced, allowing the Node.js process to exit even
+     * while it is listening.
+     */
+    unref(): void;
+    /**
+     * Stops the server from accepting new connections. Established connections
+     * are not closed; the promise resolves once the last of them ends.
+     *
+     * @returns A promise that resolves when the server is fully closed.
+     * @throws When the server was not listening.
+     */
+    close(): Promise<void>;
+    /**
+     * Binds the server and resolves once it is listening.
+     *
+     * The bind error is consumed rather than dispatched, so that a rejected
+     * promise is not also reported as an unhandled "error" event.
+     *
+     * @param options The listen options to bind with. Without any, the server
+     *   binds a system-assigned port on every interface.
+     * @returns A promise that resolves once the server is listening.
+     */
+    protected listenOn(options?: net.ListenOptions): Promise<void>;
+    protected setupEventForwarding(): void;
+}
+//# sourceMappingURL=stream-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream-server.d.ts","sourceRoot":"","sources":["../../src/net/stream-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG;IAChC,2EAA2E;IAC3E,KAAK,EAAE,EAAE,CAAC;IAEV,kDAAkD;IAClD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAEvB,kEAAkE;IAClE,SAAS,EAAE,EAAE,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,YAAY,CACxB,OAAO,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EACvC,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,CAEvD,SAAQ,sBAAsB,CAAC,OAAO,CACtC,YAAW,mBAAmB,CAAC,OAAO,CAAC;IAS3B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO;IAP9C,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAa;IAE/D;;;;OAIG;IACH,YAA+B,MAAM,EAAE,OAAO,EAG7C;IAED,iEAAiE;IACjE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,uEAAuE;IACvE,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;OAIG;IACH,IAAI,cAAc,CAAC,cAAc,EAAE,MAAM,EAExC;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAUhC;IAED;;;OAGG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrB;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAa7D;IAED,SAAS,CAAC,oBAAoB,IAAI,IAAI,CAgBrC;CACD"}

package/dist/net/stream-server.js

@@ -0,0 +1,129 @@
+import { EventDispatcherMapBase } from "@ac-kit/async";
+/**
+ * Base class for stream-oriented servers.
+ *
+ * This abstraction wraps a {@link net.Server} instance and exposes the lifecycle
+ * that is independent of the transport: binding state, connection accounting,
+ * event-loop referencing and closing.
+ *
+ * Binding and address reporting are transport-specific and are added by the
+ * concrete subclasses {@link TcpServer} and {@link IpcServer}, as is the
+ * "connection" event, whose payload is a socket of the matching type.
+ */
+export class StreamServer extends EventDispatcherMapBase {
+    server;
+    handledErrorEvents = new Set();
+    /**
+     * Creates a new {@link StreamServer} instance.
+     *
+     * @param server The underlying Node.js server.
+     */
+    constructor(server) {
+        super();
+        this.server = server;
+        this.setupEventForwarding();
+    }
+    /** Whether the server is currently listening for connections. */
+    get listening() {
+        return this.server.listening;
+    }
+    /** Maximum number of concurrent connections accepted by the server. */
+    get maxConnections() {
+        return this.server.maxConnections;
+    }
+    /**
+     * Updates the maximum number of concurrent connections.
+     *
+     * Connections accepted beyond this limit are dropped.
+     */
+    set maxConnections(maxConnections) {
+        this.server.maxConnections = maxConnections;
+    }
+    /**
+     * Counts the connections currently handled by the server.
+     *
+     * @returns A promise that resolves with the connection count.
+     */
+    getConnections() {
+        return new Promise((resolve, reject) => {
+            this.server.getConnections((error, count) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(count);
+            });
+        });
+    }
+    /**
+     * Marks the server as referenced, preventing the Node.js process from exiting
+     * while it is listening.
+     */
+    ref() {
+        this.server.ref();
+    }
+    /**
+     * Marks the server as unreferenced, allowing the Node.js process to exit even
+     * while it is listening.
+     */
+    unref() {
+        this.server.unref();
+    }
+    /**
+     * Stops the server from accepting new connections. Established connections
+     * are not closed; the promise resolves once the last of them ends.
+     *
+     * @returns A promise that resolves when the server is fully closed.
+     * @throws When the server was not listening.
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            this.server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * Binds the server and resolves once it is listening.
+     *
+     * The bind error is consumed rather than dispatched, so that a rejected
+     * promise is not also reported as an unhandled "error" event.
+     *
+     * @param options The listen options to bind with. Without any, the server
+     *   binds a system-assigned port on every interface.
+     * @returns A promise that resolves once the server is listening.
+     */
+    listenOn(options) {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            this.server.prependOnceListener("error", handleError);
+            this.server.listen(options ?? {}, () => {
+                this.server.removeListener("error", handleError);
+                resolve();
+            });
+        });
+    }
+    setupEventForwarding() {
+        this.server.on("close", () => {
+            this.dispatch("close", []);
+        });
+        this.server.on("error", (error) => {
+            if (this.handledErrorEvents.has(error)) {
+                this.handledErrorEvents.delete(error);
+                return;
+            }
+            this.dispatch("error", [error]);
+        });
+        this.server.on("listening", () => {
+            this.dispatch("listening", []);
+        });
+    }
+}
+//# sourceMappingURL=stream-server.js.map

package/dist/net/stream-server.js.map

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