nano-sdk 1.0.0

package/dist/nano/web-socket/client/web-socket-client.d.ts

@@ -0,0 +1,334 @@
+import { BootstrapResponse, ConfirmationResponse, NewUnconfirmedBlockResponse, StartedElectionResponse, StoppedElectionResponse, TelemetryResponse, VoteResponse, WorkResponse } from "../responses";
+import { PongAckResponse } from "../responses/pong-ack-response";
+import { SubscribeAckResponse } from "../responses/subscribe-ack-response";
+import { UnsubscribeAckResponse } from "../responses/unsubscribe-ack-response";
+import { UpdateAckResponse } from "../responses/update-ack-response";
+import { Topic } from "../types";
+import { Ack } from "../types/ack";
+/**
+ * Based on the MIT-licensed "reconnecting-websocket" implementation
+ * by Pedro Ladaria (https://github.com/pladaria/reconnecting-websocket).
+ *
+ * Modified and adapted for the nano-sdk project.
+ */
+export declare const ReadyStates: {
+    Connecting: number;
+    Open: number;
+    Closing: number;
+    Closed: number;
+};
+export interface WebSocketLikeEvents {
+    open: Event;
+    message: MessageEvent;
+    error: ErrorEvent;
+    close: CloseEvent;
+}
+export interface WebSocketLike {
+    binaryType: string;
+    readonly bufferedAmount: number;
+    readonly extensions: string;
+    readonly protocol: string;
+    readonly readyState: number;
+    readonly url: string;
+    addEventListener<K extends keyof WebSocketLikeEvents>(type: K, listener: WebSocketEventListener<WebSocketLikeEvents[K]>): void;
+    removeEventListener<K extends keyof WebSocketLikeEvents>(type: K, listener: WebSocketEventListener<WebSocketLikeEvents[K]>): void;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+}
+export type WebSocketConstructor = {
+    new (url: string, protocols?: string | string[]): WebSocketLike;
+};
+export interface Event {
+    target: any;
+    type: string;
+}
+export interface MessageEvent extends Event {
+    data: unknown;
+}
+export interface ErrorEvent extends Event {
+    message: string;
+    error: Error;
+}
+export interface CloseEvent extends Event {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+export type WebSocketClientOptions = {
+    webSocketClass?: WebSocketConstructor;
+    connectionTimeout?: number;
+    minUptime?: number;
+    maxEnqueuedMessages?: number;
+    maxReconnectionAttempts?: number;
+    maxReconnectionDelay?: number;
+    minReconnectionDelay?: number;
+    reconnectionDelayGrowFactor?: number;
+    startClosed?: boolean;
+};
+type UrlProvider = string | (() => string) | (() => Promise<string>);
+type Message = string | ArrayBuffer | Blob | ArrayBufferView;
+export interface WebSocketEvents extends WebSocketLikeEvents {
+}
+export type WebSocketEventListener<E> = ((event: E) => void) | {
+    handleEvent(event: E): void;
+};
+type WebSocketEventListenerMap = {
+    [K in keyof WebSocketEvents]: WebSocketEventListener<WebSocketEvents[K]>;
+};
+export type AckResponseTypeMap = {
+    pong: PongAckResponse;
+    subscribe: SubscribeAckResponse;
+    unsubscribe: UnsubscribeAckResponse;
+    update: UpdateAckResponse;
+};
+export type AckListener<A extends Ack> = ((response: AckResponseTypeMap[A]) => void) | {
+    handleAck(response: AckResponseTypeMap[A]): void;
+};
+export type TopicResponseTypeMap = {
+    bootstrap: BootstrapResponse;
+    confirmation: ConfirmationResponse;
+    new_unconfirmed_block: NewUnconfirmedBlockResponse;
+    started_election: StartedElectionResponse;
+    stopped_election: StoppedElectionResponse;
+    telemetry: TelemetryResponse;
+    vote: VoteResponse;
+    work: WorkResponse;
+};
+export type TopicListener<T extends Topic> = ((response: TopicResponseTypeMap[T]) => void) | {
+    handleTopic(response: TopicResponseTypeMap[T]): void;
+};
+export declare class WebSocketClient {
+    private readonly _url;
+    private readonly _protocols?;
+    private readonly _options;
+    private _socket?;
+    private _binaryType;
+    private _reconnectEnabled;
+    private _reconnectionAttempts;
+    private _messageQueue;
+    private _connectLock;
+    private _closeCalled;
+    private _connectTimeout?;
+    private _uptimeTimeout?;
+    private _listeners;
+    private _ackListeners;
+    private _topicListeners;
+    /**
+     * The resolved WebSocket URL as provided by the underlying socket instance.
+     * Returns an empty string if no socket has been created yet.
+     */
+    get url(): string;
+    /**
+     * The name of the sub-protocol selected by the server.
+     * This will be one of the values specified in the `protocols` parameter
+     * when the WebSocket connection was created, or an empty string if no
+     * sub-protocol was negotiated or the socket is not yet available.
+     */
+    get protocol(): string;
+    /**
+     * The current state of the connection.
+     * This value corresponds to one of the ReadyState constants.
+     *
+     * If no underlying socket exists yet, the state is derived from the
+     * `startClosed` option:
+     * - `Closed` if `startClosed` is true
+     * - `Connecting` otherwise
+     */
+    get readyState(): number;
+    /**
+     * The type of binary data being transmitted by the connection.
+     *
+     * If no socket is currently active, this returns the internally stored
+     * binaryType that will be applied once the socket is created.
+     */
+    get binaryType(): string;
+    /**
+     * Sets the type of binary data being transmitted by the connection.
+     *
+     * The value is stored internally and immediately applied to the underlying
+     * socket if it already exists.
+     */
+    set binaryType(value: string);
+    /**
+     * The number of bytes of data that have been queued via `send()` but not yet
+     * transmitted to the network.
+     *
+     * This includes:
+     * - Data queued internally before a socket is available
+     * - Data buffered by the underlying WebSocket implementation
+     *
+     * Note:
+     * - String sizes are based on character length, not UTF-8 byte length
+     * - The value does not reset to zero when the connection is closed
+     *
+     * Read-only.
+     */
+    get bufferedAmount(): number;
+    /**
+     * The extensions selected by the server, if any.
+     *
+     * This is either an empty string or a space-separated list of extensions
+     * negotiated during the WebSocket handshake. Returns an empty string if
+     * no socket is currently available.
+     */
+    get extensions(): string;
+    /**
+     * The number of reconnection attempts that have been performed so far.
+     *
+     * This value is always non-negative.
+     */
+    get reconnectionAttempts(): number;
+    /**
+     * Creates a new WebSocketClient instance.
+     *
+     * @param url - A URL or URL provider used to resolve the WebSocket endpoint
+     * @param protocols - An optional sub-protocol or list of sub-protocols
+     * @param options - Optional client configuration options
+     *
+     * Note:
+     * - The connection attempt is initiated immediately by calling `connect()`
+     * - If `startClosed` is enabled, automatic connection is disabled initially
+     */
+    constructor(url: UrlProvider, protocols?: string | string[], options?: WebSocketClientOptions);
+    /**
+     * Event handler invoked when the WebSocket connection transitions to the OPEN state.
+     *
+     * At this point, the connection is established and ready to send and receive data.
+     */
+    onopen: ((event: Event) => void) | null;
+    /**
+     * Event handler invoked when a message is received from the server.
+     */
+    onmessage: ((event: MessageEvent) => void) | null;
+    /**
+     * Event handler invoked when an error occurs on the WebSocket connection.
+     */
+    onerror: ((event: ErrorEvent) => void) | null;
+    /**
+     * Event handler invoked when the WebSocket connection transitions to the CLOSED state.
+     */
+    onclose: ((event: CloseEvent) => void) | null;
+    /**
+     * Registers an event listener for the specified WebSocket event type.
+     */
+    addEventListener<T extends keyof WebSocketEventListenerMap>(type: T, listener: WebSocketEventListenerMap[T]): void;
+    /**
+     * Dispatches an event to all registered listeners of the corresponding event type.
+     *
+     * Returns `true` to match the EventTarget `dispatchEvent` contract.
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Invokes an event listener, supporting both function listeners and
+     * EventListener objects with a `handleEvent` method.
+     */
+    private callEventListener;
+    /**
+     * Removes a previously registered event listener for the specified event type.
+     *
+     * If the listener is not registered, this method has no effect.
+     */
+    removeEventListener<T extends keyof WebSocketEventListenerMap>(type: T, listener: WebSocketEventListenerMap[T]): void;
+    /**
+     * Registers an acknowledgment listener for the specified ack type.
+     */
+    addAckListener<A extends Ack>(ack: A, listener: AckListener<A>): void;
+    /**
+     * Dispatches an acknowledgment message to all registered listeners
+     * of the corresponding ack type.
+     *
+     * Returns `true` to match the EventTarget `dispatchEvent` contract.
+     */
+    dispatchAck<A extends Ack>(ack: A, response: AckResponseTypeMap[A]): boolean;
+    /**
+     * Invokes an acknowledgment listener, supporting both function listeners
+     * and listener objects with a `handleAck` method.
+     */
+    private callAckListener;
+    /**
+     * Removes a previously registered acknowledgment listener
+     * for the specified ack type.
+     *
+     * If the listener is not registered, this method has no effect.
+     */
+    removeAckListener<A extends Ack>(ack: A, listener: AckListener<A>): void;
+    /**
+     * Registers a listener for the specified topic.
+     */
+    addTopicListener<T extends Topic>(topic: T, listener: TopicListener<T>): void;
+    /**
+     * Dispatches a message to all registered listeners of the given topic.
+     *
+     * Returns `true` to match the EventTarget `dispatchEvent` contract.
+     */
+    dispatchTopic<T extends Topic>(topic: T, response: TopicResponseTypeMap[T]): boolean;
+    /**
+     * Invokes a topic listener, supporting both function listeners and
+     * listener objects with a `handleTopic` method.
+     */
+    private callTopicListener;
+    /**
+     * Removes a previously registered listener for the specified topic.
+     *
+     * If the listener is not registered, this method has no effect.
+     */
+    removeTopicListener<T extends Topic>(topic: T, listener: TopicListener<T>): void;
+    /**
+     * Initiates a WebSocket connection attempt.
+     *
+     * This method respects internal connection locks, reconnection settings,
+     * maximum reconnection attempts, and optional reconnection delays.
+     *
+     * @returns `true` if a connection attempt was started, `false` otherwise
+     */
+    connect(): boolean;
+    /**
+     * Closes the current WebSocket connection or connection attempt
+     * and immediately starts a new one.
+     *
+     * This method:
+     * - Re-enables automatic reconnection
+     * - Resets the reconnection attempts counter
+     * - Clears the internal "close called" flag
+     */
+    reconnect(code?: number, reason?: string): void;
+    /**
+     * Enqueues data to be transmitted to the server over the WebSocket connection.
+     *
+     * If the connection is currently OPEN, the data is sent immediately.
+     * Otherwise, the data is queued and sent once the connection is established,
+     * subject to the `maxEnqueuedMessages` limit.
+     */
+    send(data: Message): void;
+    /**
+     * Internally closes the WebSocket connection and cleans up listeners and timers.
+     *
+     * This method is used during reconnection and does not permanently disable
+     * future connection attempts.
+     */
+    private disconnect;
+    /**
+     * Closes the WebSocket connection or connection attempt, if any.
+     *
+     * This permanently disables automatic reconnection until `reconnect()` or
+     * `connect()` is called again.
+     *
+     * If the connection is already closed, this method has no effect.
+     */
+    close(code?: number, reason?: string): void;
+    private acceptOpen;
+    private handleTimeout;
+    private handleOpen;
+    private handleMessage;
+    private dispatchError;
+    private handleError;
+    private handleErrorDuringTransition;
+    private handleClose;
+    private removeListeners;
+    private addListeners;
+    private waitNextReconnectionDelay;
+    private getNextReconnectionDelay;
+    private getNextUrl;
+    private clearTimeouts;
+}
+export {};