@ac-kit/node 0.1.0

package/dist/net/stream-socket.js

@@ -0,0 +1,188 @@
+import * as net from "node:net";
+import { EventDispatcherMapBase } from "@ac-kit/async";
+/**
+ * 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 class StreamSocket extends EventDispatcherMapBase {
+    sock;
+    handledErrorEvents = new Set();
+    /**
+     * Creates a new {@link StreamSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `StreamSocket` instance.
+     */
+    static from(options) {
+        return new StreamSocket(new net.Socket(options));
+    }
+    /**
+     * Creates a new {@link StreamSocket} instance.
+     *
+     * @param sock The underlying Node.js socket.
+     */
+    constructor(sock) {
+        super();
+        this.sock = sock;
+        this.setupEventForwarding();
+    }
+    /**
+     * 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() {
+        return this.sock;
+    }
+    /** Indicates whether the socket has been fully closed. */
+    get closed() {
+        return this.sock.closed;
+    }
+    /** Indicates whether the underlying socket has been destroyed. */
+    get destroyed() {
+        return this.sock.destroyed;
+    }
+    /** Total number of bytes read from the socket so far. */
+    get bytesRead() {
+        return this.sock.bytesRead;
+    }
+    /** Total number of bytes written to the socket so far. */
+    get bytesWritten() {
+        return this.sock.bytesWritten;
+    }
+    /** Whether the socket is currently in the process of connecting. */
+    get connecting() {
+        return this.sock.connecting;
+    }
+    /** Current inactivity timeout in milliseconds, or `null` if disabled. */
+    get timeout() {
+        return this.sock.timeout ?? 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) {
+        this.sock.setTimeout(timeout ?? 0);
+    }
+    /**
+     * Marks the socket as referenced, preventing the Node.js process from exiting
+     * while the socket is active.
+     */
+    ref() {
+        this.sock.ref();
+    }
+    /**
+     * Marks the socket as unreferenced, allowing the Node.js process to exit even
+     * if the socket is still active.
+     */
+    unref() {
+        this.sock.unref();
+    }
+    /**
+     * 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) {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            const handleEnd = () => {
+                this.sock.removeListener("error", handleError);
+                resolve();
+            };
+            this.sock.prependOnceListener("error", handleError);
+            if (options?.waitForClose && !this.sock.closed) {
+                this.sock.prependOnceListener("close", () => {
+                    this.sock.removeListener("error", handleError);
+                    resolve();
+                });
+            }
+            this.sock.end(options?.waitForClose && !this.sock.closed ? undefined : handleEnd);
+        });
+    }
+    /**
+     * 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) {
+        return new Promise((resolve, reject) => {
+            const callback = (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            };
+            this.sock.write(data, callback);
+        });
+    }
+    /**
+     * 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() {
+        this.sock.destroy();
+    }
+    setupEventForwarding() {
+        this.sock.on("error", (err) => {
+            if (this.handledErrorEvents.has(err)) {
+                this.handledErrorEvents.delete(err);
+                return;
+            }
+            this.dispatch("error", [err]);
+        });
+        this.sock.on("close", (hadError) => {
+            this.dispatch("close", [hadError]);
+        });
+        this.sock.on("connect", () => {
+            this.dispatch("connect", []);
+        });
+        this.sock.on("ready", () => {
+            this.dispatch("ready", []);
+        });
+        this.sock.on("timeout", () => {
+            this.dispatch("timeout", []);
+        });
+    }
+}
+//# sourceMappingURL=stream-socket.js.map

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

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

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

@@ -0,0 +1,110 @@
+import * as net from "node:net";
+import { EventDispatcherMapBase, IEventDispatcherMap } from "@ac-kit/async";
+import { InetEndpoint, type IError } from "@ac-kit/core";
+import type { Except } from "type-fest";
+import { TcpSocket } from "./tcp-socket.js";
+/** Event map for TcpServer server-specific events. */
+export type TcpServerEvents = {
+    /** Emitted when the server closes. */
+    close: [];
+    /**
+     * Emitted when a new connection is made. The connection is wrapped in a
+     * TcpClient instance.
+     */
+    connection: [client: TcpSocket];
+    /**
+     * Emitted when a new connection is dropped. Provides the local and remote
+     * endpoint information of the dropped connection.
+     */
+    drop: [
+        localEndpoint: InetEndpoint | null,
+        remoteEndpoint: InetEndpoint | null
+    ];
+    /** Emitted when an error occurs. */
+    error: [err: IError];
+    /** Emitted when the server has been bound after calling server.listen(). */
+    listening: [];
+};
+/**
+ * TCP server to accept incoming connections.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const server = TcpServer.from();
+ * server.on("connection", (client) => {
+ * 	console.log("Client connected");
+ * 	client.stream.on("data", (data) => {
+ * 		console.log("Received:", data.toString());
+ * 	});
+ * });
+ * await server.listen(8080, "0.0.0.0");
+ * // ... later
+ * await server.close();
+ * ```
+ */
+export declare class TcpServer extends EventDispatcherMapBase<TcpServerEvents> implements IEventDispatcherMap<TcpServerEvents> {
+    private readonly srv;
+    /**
+     * Creates a new `TcpServer` instance with the specified options.
+     *
+     * @param options Options for creating the TCP server.
+     * @returns A new `TcpServer` instance.
+     */
+    static from(options?: net.ServerOpts): TcpServer;
+    private readonly handledErrorEvents;
+    constructor(srv: net.Server);
+    /**
+     * Gets the current number of concurrent connections on the server.
+     *
+     * @returns A promise that resolves with the connection count.
+     */
+    getConnections(): Promise<number>;
+    /** Gets whether the server is currently listening for connections. */
+    get listening(): boolean;
+    /**
+     * Sets the maximum number of queued pending connections.
+     *
+     * @param maxConnections The maximum number of connections to queue.
+     */
+    set maxConnections(maxConnections: number);
+    /** Gets the maximum number of queued pending connections. */
+    get maxConnections(): number;
+    /**
+     * References the server, preventing the process from exiting while the server
+     * is active.
+     */
+    ref(): void;
+    /**
+     * Unreferences the server, allowing the process from exiting even if the
+     * server is active.
+     */
+    unref(): void;
+    /**
+     * Starts the TCP server listening on the specified port and host.
+     *
+     * @param port The port to listen on. If 0, a random available port will be
+     *   assigned.
+     * @param host The host/interface to bind to. Defaults to '::' (IPv6) or
+     *   '0.0.0.0' (IPv4).
+     * @param options Additional listen options.
+     * @returns A promise that resolves when the server is successfully listening.
+     */
+    listen(port: number, host?: string, options?: Except<net.ListenOptions, "port" | "host">): Promise<void>;
+    /**
+     * Closes the TCP server, stopping it from accepting new connections. Existing
+     * connections are not automatically closed.
+     *
+     * @returns A promise that resolves when the server is fully closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Gets the address information of the server.
+     *
+     * @returns The server's endpoint information or null if the server is not
+     *   listening.
+     */
+    address(): InetEndpoint | null;
+    private setupEventForwarding;
+}
+//# sourceMappingURL=tcp-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tcp-server.d.ts","sourceRoot":"","sources":["../../src/net/tcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAEN,YAAY,EAEZ,KAAK,MAAM,EACX,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG;IAC7B,sCAAsC;IACtC,KAAK,EAAE,EAAE,CAAC;IAEV;;;OAGG;IACH,UAAU,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAEhC;;;OAGG;IACH,IAAI,EAAE;QACL,aAAa,EAAE,YAAY,GAAG,IAAI;QAClC,cAAc,EAAE,YAAY,GAAG,IAAI;KACnC,CAAC;IAEF,oCAAoC;IACpC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAErB,4EAA4E;IAC5E,SAAS,EAAE,EAAE,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SACZ,SAAQ,sBAAsB,CAAC,eAAe,CAC9C,YAAW,mBAAmB,CAAC,eAAe,CAAC;IAcnC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAZhC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,UAAU,GAAG,SAAS,CAE/C;IAED,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA0B;IAE7D,YAA6B,GAAG,EAAE,GAAG,CAAC,MAAM,EAG3C;IAED;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAUhC;IAED,sEAAsE;IACtE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;OAIG;IACH,IAAI,cAAc,CAAC,cAAc,EAAE,MAAM,EAExC;IAED,6DAA6D;IAC7D,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;OAGG;IACH,GAAG,IAAI,IAAI,CAEV;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;;;;OASG;IACH,MAAM,CACL,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CAoBf;IAED;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrB;IAED;;;;;OAKG;IACH,OAAO,IAAI,YAAY,GAAG,IAAI,CAiB7B;IAED,OAAO,CAAC,oBAAoB;CAsD5B"}

package/dist/net/tcp-server.js

@@ -0,0 +1,198 @@
+import * as net from "node:net";
+import { EventDispatcherMapBase } from "@ac-kit/async";
+import { composeInetAddress, UnsupportedError, } from "@ac-kit/core";
+import { TcpSocket } from "./tcp-socket.js";
+/**
+ * TCP server to accept incoming connections.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const server = TcpServer.from();
+ * server.on("connection", (client) => {
+ * 	console.log("Client connected");
+ * 	client.stream.on("data", (data) => {
+ * 		console.log("Received:", data.toString());
+ * 	});
+ * });
+ * await server.listen(8080, "0.0.0.0");
+ * // ... later
+ * await server.close();
+ * ```
+ */
+export class TcpServer extends EventDispatcherMapBase {
+    srv;
+    /**
+     * Creates a new `TcpServer` instance with the specified options.
+     *
+     * @param options Options for creating the TCP server.
+     * @returns A new `TcpServer` instance.
+     */
+    static from(options) {
+        return new TcpServer(net.createServer(options));
+    }
+    handledErrorEvents = new Set();
+    constructor(srv) {
+        super();
+        this.srv = srv;
+        this.setupEventForwarding();
+    }
+    /**
+     * Gets the current number of concurrent connections on the server.
+     *
+     * @returns A promise that resolves with the connection count.
+     */
+    getConnections() {
+        return new Promise((resolve, reject) => {
+            this.srv.getConnections((error, count) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(count);
+                }
+            });
+        });
+    }
+    /** Gets whether the server is currently listening for connections. */
+    get listening() {
+        return this.srv.listening;
+    }
+    /**
+     * Sets the maximum number of queued pending connections.
+     *
+     * @param maxConnections The maximum number of connections to queue.
+     */
+    set maxConnections(maxConnections) {
+        this.srv.maxConnections = maxConnections;
+    }
+    /** Gets the maximum number of queued pending connections. */
+    get maxConnections() {
+        return this.srv.maxConnections;
+    }
+    /**
+     * References the server, preventing the process from exiting while the server
+     * is active.
+     */
+    ref() {
+        this.srv.ref();
+    }
+    /**
+     * Unreferences the server, allowing the process from exiting even if the
+     * server is active.
+     */
+    unref() {
+        this.srv.unref();
+    }
+    /**
+     * Starts the TCP server listening on the specified port and host.
+     *
+     * @param port The port to listen on. If 0, a random available port will be
+     *   assigned.
+     * @param host The host/interface to bind to. Defaults to '::' (IPv6) or
+     *   '0.0.0.0' (IPv4).
+     * @param options Additional listen options.
+     * @returns A promise that resolves when the server is successfully listening.
+     */
+    listen(port, host, options) {
+        return new Promise((resolve, reject) => {
+            const handleError = (error) => {
+                this.handledErrorEvents.add(error);
+                reject(error);
+            };
+            this.srv.prependOnceListener("error", handleError);
+            this.srv.listen({
+                ...options,
+                port,
+                host,
+            }, () => {
+                this.srv.removeListener("error", handleError);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Closes the TCP server, stopping it from accepting new connections. Existing
+     * connections are not automatically closed.
+     *
+     * @returns A promise that resolves when the server is fully closed.
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            this.srv.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Gets the address information of the server.
+     *
+     * @returns The server's endpoint information or null if the server is not
+     *   listening.
+     */
+    address() {
+        const addr = this.srv.address();
+        if (addr === null) {
+            return null;
+        }
+        if (typeof addr === "string") {
+            throw new UnsupportedError(`Unsupported address type: string. Expected AddressInfo object.`);
+        }
+        return {
+            ...composeInetAddress(addr.family, addr.address),
+            port: addr.port,
+        };
+    }
+    setupEventForwarding() {
+        this.srv.on("connection", (socket) => {
+            const client = new TcpSocket(socket);
+            this.dispatch("connection", [client]);
+        });
+        this.srv.on("close", () => {
+            this.dispatch("close", []);
+        });
+        this.srv.on("error", (err) => {
+            if (this.handledErrorEvents.has(err)) {
+                this.handledErrorEvents.delete(err);
+                return;
+            }
+            this.dispatch("error", [err]);
+        });
+        this.srv.on("listening", () => {
+            this.dispatch("listening", []);
+        });
+        this.srv.on("drop", (data) => {
+            let localEndpoint;
+            if (data?.localAddress !== undefined &&
+                data?.localPort !== undefined &&
+                data?.localFamily !== undefined) {
+                localEndpoint = {
+                    ...composeInetAddress(data.localFamily, data.localAddress),
+                    port: data.localPort,
+                };
+            }
+            else {
+                localEndpoint = null;
+            }
+            let remoteEndpoint;
+            if (data?.remoteAddress !== undefined &&
+                data?.remotePort !== undefined &&
+                data?.remoteFamily !== undefined) {
+                remoteEndpoint = {
+                    ...composeInetAddress(data.remoteFamily, data.remoteAddress),
+                    port: data.remotePort,
+                };
+            }
+            else {
+                remoteEndpoint = null;
+            }
+            this.dispatch("drop", [localEndpoint, remoteEndpoint]);
+        });
+    }
+}
+//# sourceMappingURL=tcp-server.js.map

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

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

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

@@ -0,0 +1,87 @@
+import * as net from "node:net";
+import { InetAddress, InetEndpoint } from "@ac-kit/core";
+import type { Except } from "type-fest";
+import { StreamSocket, type StreamSocketEvents } from "./stream-socket.js";
+/** Event map for TcpSocket socket-specific events. */
+export type TcpSocketEvents = 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];
+    /** Emitted after resolving the host name but before connecting. */
+    lookup: [err: Error | null, address: InetAddress, host: string];
+};
+export type TcpSocketConnectOptions = Except<net.TcpSocketConnectOpts, "port"> & {
+    signal?: AbortSignal;
+};
+/**
+ * TCP socket for establishing connections to TCP servers.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const tcpSocket = new TcpSocket.from();
+ * await tcpSocket.connect(80, "example.com");
+ * await tcpSocket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
+ * await tcpSocket.end({ waitForClose: true });
+ * ```
+ */
+export declare class TcpSocket<TSock extends net.Socket = net.Socket, TEvents extends TcpSocketEvents = TcpSocketEvents> extends StreamSocket<TSock, TEvents> {
+    /**
+     * Creates a new {@link TcpSocket} instance.
+     *
+     * @param options Options for creating the underlying Node.js socket.
+     * @returns A new `TcpSocket` instance.
+     */
+    static from(options?: Except<net.SocketConstructorOpts, "fd">): TcpSocket;
+    constructor(sock: TSock);
+    /**
+     * Returns the remote endpoint information of the socket.
+     *
+     * @throws {UnsupportedError} If the socket family is not IPv4 or IPv6.
+     */
+    get remoteEndpoint(): InetEndpoint | null;
+    /**
+     * Returns the local endpoint information of the socket.
+     *
+     * @throws {UnsupportedError} If the socket family is not IPv4 or IPv6.
+     */
+    get localEndpoint(): InetEndpoint | null;
+    /**
+     * Sets the keep-alive option for the socket.
+     *
+     * @param enable Whether to enable keep-alive.
+     * @param initialDelay The initial delay in milliseconds before the first
+     *   keep-alive probe.
+     */
+    setKeepAlive(enable: boolean, initialDelay?: number): void;
+    /**
+     * Disables the Nagle algorithm for the socket.
+     *
+     * @param noDelay Whether to disable the Nagle algorithm.
+     */
+    setNoDelay(noDelay: boolean): void;
+    /**
+     * Establishes a TCP connection to the specified port and host.
+     *
+     * @param port The port to connect to.
+     * @param host The host to connect to (defaults to `localhost`).
+     * @param options Connection options.
+     * @returns A promise that resolves when the connection is successfully
+     *   established.
+     */
+    connect(port: number, options?: TcpSocketConnectOptions): Promise<void>;
+    protected setupEventForwarding(): void;
+}
+//# sourceMappingURL=tcp-socket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tcp-socket.d.ts","sourceRoot":"","sources":["../../src/net/tcp-socket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,EAEN,WAAW,EACX,YAAY,EAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,sDAAsD;AACtD,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;IAEnD,mEAAmE;IACnE,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAC3C,GAAG,CAAC,oBAAoB,EACxB,MAAM,CACN,GAAG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,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,CACnB,OAAO,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,IAAI,CAAC,GAC/C,SAAS,CAEX;IAED,YAAY,IAAI,EAAE,KAAK,EAGtB;IAED;;;;OAIG;IACH,IAAI,cAAc,IAAI,YAAY,GAAG,IAAI,CAiBxC;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,YAAY,GAAG,IAAI,CAiBvC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzD;IAED;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjC;IAED;;;;;;;;OAQG;IACG,OAAO,CACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAgCf;IAED,UAAmB,oBAAoB,IAAI,IAAI,CAkC9C;CACD"}