@ayonli/jsext/types/net/types.d.ts

A JavaScript extension package for building strong and modern applications.

import type { ToDict } from "../types.ts";
/**
 * Represents the network address of a connection peer.
 */
export interface NetAddress {
    /**
     * The hostname of the remote peer.
     */
    hostname: string;
    /**
     * The port number of the remote peer.
     */
    port: number;
}
/**
 * The options for {@link connect} to establish a TCP connection.
 */
export interface TcpConnectOptions extends NetAddress {
    transport?: "tcp";
    /**
     * Whether to enable TLS for the connection.
     */
    tls?: boolean;
}
/**
 * The options for {@link connect} to establish a Unix domain socket connection.
 */
export interface UnixConnectOptions {
    transport?: "unix";
    path: string;
}
/**
 * The options for {@link connect} to establish a UDP connection.
 */
export interface UdpConnectOptions extends NetAddress {
    transport: "udp";
}
/**
 * The options for {@link udpSocket} to bind a UDP socket.
 */
export interface UdpBindOptions {
    /**
     * The hostname to be bound, if not provided, the system will try to listen
     * on all available addresses.
     */
    hostname?: string;
    /**
     * The port number to be bound, if not provided, the system will assign a
     * random port.
     */
    port?: number;
}
declare const _impl: unique symbol;
/**
 * A socket represents an open transport to a remote peer.
 */
export declare class Socket implements Disposable {
    protected [_impl]: ToDict<Socket>;
    constructor(impl: ToDict<Socket>);
    /**
     * A promise that resolves when the socket is closed cleanly, or rejects if
     * closed with an error.
     */
    get closed(): Promise<void>;
    /**
     * Closes the socket immediately, if there are any queued data, they will be
     * discarded.
     */
    close(): void;
    /**
     * Opposite of `unref()`, calling `ref()` on a previously unrefed socket will
     * not let the program exit if it's the only socket left (the default behavior).
     * If the socket is refed calling `ref()` again will have no effect.
     *
     * NOTE: This function only works in Node.js, Deno and Bun, it is a no-op in
     * other environments.
     */
    ref(): void;
    /**
     * Calling `unref()` on a socket will allow the program to exit if this is
     * the only active socket in the event system. If the socket is already
     * unrefed calling `unref()` again will have no effect.
     *
     * NOTE: This function only works in Node.js, Deno and Bun, it is a no-op in
     * other environments.
     */
    unref(): void;
    [Symbol.dispose](): void;
}
/**
 * A socket stream represents a connection to a remote peer with a `readable`
 * stream and a `writable` stream.
 */
export declare class SocketStream extends Socket {
    protected [_impl]: ToDict<SocketStream>;
    constructor(impl: ToDict<SocketStream>);
    /**
     * The readable side of the socket.
     */
    get readable(): ReadableStream<Uint8Array>;
    /**
     * The writable side of the socket.
     */
    get writable(): WritableStream<Uint8Array>;
}
/**
 * A connection with TCP socket.
 */
export declare class TcpSocketStream extends SocketStream {
    protected [_impl]: ToDict<TcpSocketStream>;
    constructor(impl: ToDict<TcpSocketStream>);
    /**
     * The address of the local peer.
     */
    get localAddress(): NetAddress;
    /**
     * The address of the remote peer.
     */
    get remoteAddress(): NetAddress;
    /**
     * Enable/disable keep-alive functionality.
     *
     * NOTE: This function is a no-op in Cloudflare Workers and Deno with TLS enabled.
     */
    setKeepAlive(keepAlive?: boolean | undefined): void;
    /**
     * Enable/disable the use of Nagle's algorithm.
     *
     * NOTE: This function is a no-op in Cloudflare Workers and Deno with TLS enabled.
     */
    setNoDelay(noDelay?: boolean | undefined): void;
}
/**
 * A connection with Unix domain socket.
 */
export declare class UnixSocketStream extends SocketStream {
}
/**
 * A UDP socket bound to a local address, with the ability to send and receive
 * messages.
 */
export declare class UdpSocket extends Socket implements AsyncIterable<[data: Uint8Array, sender: NetAddress]> {
    protected [_impl]: ToDict<UdpSocket>;
    constructor(impl: ToDict<UdpSocket>);
    /**
     * The address that this socket is bound to.
     */
    get localAddress(): NetAddress;
    /**
     * Receives a message from the socket, returns the data and the sender
     * address in a tuple.
     */
    receive(): Promise<[data: Uint8Array, sender: NetAddress]>;
    /**
     * Sends a message to the specified receiver, returns the number of bytes
     * sent.
     *
     * NOTE: UDP messages have size limits, see
     * https://nodejs.org/docs/latest/api/dgram.html#note-about-udp-datagram-size.
     *
     */
    send(data: Uint8Array, receiver: NetAddress): Promise<number>;
    /**
     * Associates the socket to a remote peer so that future communications will
     * only be with that peer.
     *
     * This function returns a {@link UdpSocketStream} instance that comes with
     * a `readable` stream and a `writable` stream, which gives a more
     * convenient interface that is similar to TCP connections.
     *
     * Once connected, the `send` and `receive` methods of the original socket
     * will be disabled.
     */
    connect(to: NetAddress): Promise<UdpSocketStream>;
    /**
     * Tells the kernel to join a multicast group at the given `address` and
     * the optional `interfaceAddress` using the `IP_ADD_MEMBERSHIP` socket
     * option.
     */
    joinMulticast(address: string, interfaceAddress?: string | undefined): void;
    /**
     * Instructs the kernel to leave a multicast group at `address` using the
     * `IP_DROP_MEMBERSHIP` socket option.
     */
    leaveMulticast(address: string, interfaceAddress?: string | undefined): void;
    /**
     * Sets or clears the `SO_BROADCAST` socket option. When enabled, this
     * socket is allowed to send packets to a broadcast address.
     */
    setBroadcast(flag: boolean): void;
    /**
     * Sets or clears the `IP_MULTICAST_LOOP` socket option. When enabled, this
     * socket will receive packets that it sends to the multicast group.
     */
    setMulticastLoopback(flag: boolean): void;
    /**
     * Sets the `IP_MULTICAST_TTL` socket option.
     *
     * See https://nodejs.org/docs/latest/api/dgram.html#socketsetmulticastttlttl
     */
    setMulticastTTL(ttl: number): void;
    /**
     * Sets the `IP_TTL` socket option
     *
     * See https://nodejs.org/docs/latest/api/dgram.html#socketsetttlttl
     */
    setTTL(ttl: number): void;
    [Symbol.asyncIterator](): AsyncIterableIterator<[data: Uint8Array, sender: NetAddress]>;
}
/**
 * A UDP socket stream represents a UDP socket that is bound to a local address
 * and associated to a remote address, the socket will only send and receive
 * messages to and from that remote address.
 *
 * The instance of this class comes with a `readable` stream and a `writable`
 * stream, which gives a more convenient interface that is similar to TCP
 * connections.
 */
export declare class UdpSocketStream extends Socket {
    protected [_impl]: ToDict<UdpSocketStream>;
    constructor(impl: ToDict<UdpSocketStream>);
    /**
     * The address that this socket is bound to.
     */
    get localAddress(): NetAddress;
    /**
     * The address of the remote peer.
     */
    get remoteAddress(): NetAddress;
    /**
     * The readable side of the socket.
     */
    get readable(): ReadableStream<Uint8Array>;
    /**
     * The writable side of the socket.
     */
    get writable(): WritableStream<Uint8Array>;
}
export {};