snapreq 0.0.1 → 0.0.3

package/types/websocket/websocket-client.d.ts

@@ -0,0 +1,364 @@
+/**
+ * A small WebSocket client that mirrors simple HTTP-style calls and channel
+ * subscriptions over `globalThis.WebSocket`, so the same code runs on web, Expo
+ * / React Native and Node. Supports optional auto-reconnect with exponential
+ * backoff, session resumption and listener re-subscription.
+ *
+ * Response bodies are returned as raw parsed JSON; apps that need their own
+ * (de)serialization should apply it around `post`/`get` and the response
+ * `json()`.
+ */
+export default class SnapReqWebSocketClient {
+    /**
+     * @param {object} args - Options object.
+     * @param {string} args.url - Full WebSocket URL, e.g. `ws://localhost:3006/websocket`.
+     * @param {boolean} [args.autoReconnect] - Enable auto-reconnect with exponential backoff.
+     * @param {boolean} [args.debug] - Whether to log debug output.
+     * @param {{getIsOnline?: () => boolean | Promise<boolean>, subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {remove: () => void}}} [args.networkMonitor] - Optional online-state adapter. When provided, auto-reconnect can wait for the network to report online before reconnecting, and open sockets are closed when the monitor reports offline.
+     * @param {number[]} [args.reconnectDelays] - Backoff delays in ms (default: [1000, 2000, 4000, 8000, 15000]).
+     * @param {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [args.sessionStore] - Optional sessionId persistence hook surviving reloads (localStorage, a cookie, SQLite, etc.).
+     * @param {(value: any) => any} [args.deserialize] - Optional transform applied to a response body inside `response.json()`. Lets an app re-hydrate its own wire format. Defaults to identity.
+     */
+    constructor({ autoReconnect, debug, deserialize, networkMonitor, reconnectDelays, sessionStore, url }?: {
+        url: string;
+        autoReconnect?: boolean;
+        debug?: boolean;
+        networkMonitor?: {
+            getIsOnline?: () => boolean | Promise<boolean>;
+            subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {
+                remove: () => void;
+            };
+        };
+        reconnectDelays?: number[];
+        sessionStore?: {
+            get: () => string | null | undefined | Promise<string | null | undefined>;
+            set: (sessionId: string) => void | Promise<void>;
+            clear: () => void | Promise<void>;
+        };
+        deserialize?: (value: any) => any;
+    });
+    /** @type {Map<string, {reject: (error: unknown) => void, resolve: (response: SnapReqWebSocketResponse) => void}>} */
+    pendingRequests: Map<string, {
+        reject: (error: unknown) => void;
+        resolve: (response: SnapReqWebSocketResponse) => void;
+    }>;
+    /** @type {Map<string, {reject: (error: unknown) => void, resolve: (value?: void) => void}>} */
+    pendingSubscriptions: Map<string, {
+        reject: (error: unknown) => void;
+        resolve: (value?: void) => void;
+    }>;
+    /** @type {Map<string, {callbacks: Set<(payload: any) => void>, channel: string, params: Record<string, any> | undefined, ready: Promise<void>}>} */
+    listeners: Map<string, {
+        callbacks: Set<(payload: any) => void>;
+        channel: string;
+        params: Record<string, any> | undefined;
+        ready: Promise<void>;
+    }>;
+    /** @type {(value: any) => any} */
+    _deserialize: (value: any) => any;
+    /** @type {boolean} */
+    autoReconnect: boolean;
+    debug: boolean;
+    /** @type {number | null} */
+    disconnectedSince: number | null;
+    /** @type {number} */
+    reconnectAttempt: number;
+    /** @type {number} */
+    connectionAttempts: number;
+    /** @type {number[]} */
+    reconnectDelays: number[];
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    reconnectTimer: ReturnType<typeof setTimeout> | null;
+    url: string;
+    nextID: number;
+    /** @type {(() => void | Promise<void>) | null} */
+    onReconnect: (() => void | Promise<void>) | null;
+    /** @type {Record<string, any>} */
+    _metadata: Record<string, any>;
+    /** @type {Map<string, SnapReqWebSocketConnection>} */
+    _connections: Map<string, SnapReqWebSocketConnection>;
+    /** @type {Map<string, SnapReqWebSocketChannel>} */
+    _channelSubscriptions: Map<string, SnapReqWebSocketChannel>;
+    _nextConnectionIdSeq: number;
+    _nextSubscriptionIdSeq: number;
+    /** @type {string | null} - sessionId received from `session-established`; sent on reconnect for resumption. */
+    _sessionId: string | null;
+    /** @type {boolean} - true between a reconnect and the session-resumed / session-gone reply. */
+    _awaitingResume: boolean;
+    /** @type {boolean} - true once the current socket has an active session ready for app messages. */
+    _sessionReady: boolean;
+    /** @type {string | null} - provisional session id announced before a resume attempt finishes. */
+    _pendingSessionId: string | null;
+    /** @type {Promise<void> | null} */
+    _sessionReadyPromise: Promise<void> | null;
+    /** @type {(() => void) | null} */
+    _resolveSessionReady: (() => void) | null;
+    /** @type {unknown | null} */
+    _sessionReadyError: unknown | null;
+    /** @type {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>} | undefined} */
+    _sessionStore: {
+        get: () => string | null | undefined | Promise<string | null | undefined>;
+        set: (sessionId: string) => void | Promise<void>;
+        clear: () => void | Promise<void>;
+    } | undefined;
+    /** @type {boolean} - true once the sessionStore has been consulted for a restored id. */
+    _sessionStoreRestored: boolean;
+    /** @type {{getIsOnline?: () => boolean | Promise<boolean>, subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {remove: () => void}} | undefined} */
+    _networkMonitor: {
+        getIsOnline?: () => boolean | Promise<boolean>;
+        subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {
+            remove: () => void;
+        };
+    } | undefined;
+    /** @type {null | (() => void) | {remove: () => void}} */
+    _networkMonitorSubscription: null | (() => void) | {
+        remove: () => void;
+    };
+    /** @type {boolean} */
+    _waitingForOnline: boolean;
+    /** @returns {boolean} - Whether the socket is open. */
+    isOpen(): boolean;
+    /** @returns {boolean} - Whether the session is ready for app messages. */
+    isSessionReady(): boolean;
+    /**
+     * Opens a 1:1 connection of the given type against the server. Requires the
+     * socket to already be connected (call `connect()` first).
+     * @param {string} connectionType - Name the server registered the class under.
+     * @param {{params?: Record<string, any>, onConnect?: () => void, onMessage?: (body: any) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options.
+     * @returns {SnapReqWebSocketConnection} - The connection handle.
+     */
+    openConnection(connectionType: string, options?: {
+        params?: Record<string, any>;
+        onConnect?: () => void;
+        onMessage?: (body: any) => void;
+        onDisconnect?: () => void;
+        onResume?: () => void;
+        onClose?: (reason: string) => void;
+    }): SnapReqWebSocketConnection;
+    /**
+     * Drops a connection handle from the registry.
+     * @param {string} connectionId - The connection id.
+     * @returns {void}
+     */
+    _removeConnection(connectionId: string): void;
+    /**
+     * Subscribes to a named channel. If the socket is not yet open, the
+     * subscription is queued and sent once a connection is established.
+     * @param {string} channelType - Name the server registered the channel under.
+     * @param {{params?: Record<string, any>, lastEventId?: string, onMessage?: (body: any) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Subscription options.
+     * @returns {SnapReqWebSocketChannel} - The subscription handle.
+     */
+    subscribeChannel(channelType: string, options?: {
+        params?: Record<string, any>;
+        lastEventId?: string;
+        onMessage?: (body: any) => void;
+        onDisconnect?: () => void;
+        onResume?: () => void;
+        onClose?: (reason: string) => void;
+    }): SnapReqWebSocketChannel;
+    /**
+     * @param {string} subscriptionId - The subscription id.
+     * @returns {void}
+     */
+    _removeChannelSubscription(subscriptionId: string): void;
+    /**
+     * @param {SnapReqWebSocketChannel} subscription - The subscription to send.
+     * @returns {void}
+     */
+    _sendChannelSubscribe(subscription: SnapReqWebSocketChannel): void;
+    /** @returns {void} */
+    _sendPendingChannelSubscriptions(): void;
+    /** @returns {Promise<boolean>} - Whether the network reports online. */
+    _isOnline(): Promise<boolean>;
+    /** @returns {Promise<boolean>} - Whether reconnect should wait for online. */
+    _shouldWaitForOnline(): Promise<boolean>;
+    /** @returns {void} */
+    _ensureNetworkMonitorSubscription(): void;
+    /** @returns {void} */
+    _teardownNetworkMonitorSubscription(): void;
+    /**
+     * Sets a global metadata value that is sent to the server. When the socket is
+     * open, a metadata update message is sent immediately.
+     * @param {string} key - Metadata key.
+     * @param {any} value - Metadata value (null to clear).
+     * @returns {void}
+     */
+    setMetadata(key: string, value: any): void;
+    /** @returns {Record<string, any>} - Current metadata. */
+    getMetadata(): Record<string, any>;
+    /**
+     * Ensures a WebSocket connection is open. Auto-reconnect and online gating are
+     * enabled by default.
+     * @param {{autoReconnect?: boolean, waitForOnline?: boolean, resetReconnectState?: boolean}} [options] - Connect options.
+     * @returns {Promise<void>} - Resolves once connected and the session is ready.
+     */
+    connect({ autoReconnect, waitForOnline, resetReconnectState }?: {
+        autoReconnect?: boolean;
+        waitForOnline?: boolean;
+        resetReconnectState?: boolean;
+    }): Promise<void>;
+    connectPromise: Promise<any>;
+    socket: WebSocket;
+    /**
+     * Closes the WebSocket and clears pending state.
+     * @returns {Promise<void>} - Resolves once closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Disables auto-reconnect and closes the WebSocket.
+     * @returns {Promise<void>} - Resolves once closed.
+     */
+    disconnectAndStopReconnect(): Promise<void>;
+    /**
+     * Closes the raw socket without disabling auto-reconnect. Used by tests to
+     * simulate an unexpected network drop.
+     * @returns {Promise<void>} - Resolves once the socket has closed.
+     */
+    dropConnection(): Promise<void>;
+    /**
+     * Performs a POST request over the WebSocket.
+     * @param {string} path - Path.
+     * @param {any} [body] - Request body.
+     * @param {{headers?: Record<string, string>}} [options] - Request options such as headers.
+     * @returns {Promise<SnapReqWebSocketResponse>} - The response.
+     */
+    post(path: string, body?: any, options?: {
+        headers?: Record<string, string>;
+    }): Promise<SnapReqWebSocketResponse>;
+    /**
+     * Performs a GET request over the WebSocket.
+     * @param {string} path - Path.
+     * @param {{headers?: Record<string, string>}} [options] - Request options such as headers.
+     * @returns {Promise<SnapReqWebSocketResponse>} - The response.
+     */
+    get(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<SnapReqWebSocketResponse>;
+    /**
+     * Subscribes to a channel for server-sent events.
+     * @param {string} channel - Channel name.
+     * @param {(payload: any) => void} callback - Callback function.
+     * @returns {() => void} - Unsubscribe function.
+     */
+    on(channel: string, callback: (payload: any) => void): () => void;
+    /**
+     * Returns a snapshot of the client's connection state.
+     * @returns {{disconnectedSince: number | null, isOpen: boolean, listenerCount: number}} - State snapshot.
+     */
+    state(): {
+        disconnectedSince: number | null;
+        isOpen: boolean;
+        listenerCount: number;
+    };
+    /**
+     * Subscribes to a channel for server-sent events with optional params.
+     * @param {string} channel - Channel name.
+     * @param {{lastEventId?: string, params?: Record<string, any>}} options - Subscription options.
+     * @param {(payload: any, message?: Record<string, any>) => void} callback - Callback function.
+     * @returns {(() => void) & {ready: Promise<void>}} - Unsubscribe function with readiness promise.
+     */
+    subscribe(channel: string, options: {
+        lastEventId?: string;
+        params?: Record<string, any>;
+    }, callback: (payload: any, message?: Record<string, any>) => void): (() => void) & {
+        ready: Promise<void>;
+    };
+    /**
+     * Subscribes to a channel and waits until the server acknowledges it.
+     * @param {string} channel - Channel name.
+     * @param {{lastEventId?: string, params?: Record<string, any>}} options - Subscription options.
+     * @param {(payload: any, message?: Record<string, any>) => void} callback - Callback function.
+     * @returns {Promise<(() => void) & {ready: Promise<void>}>} - Ready unsubscribe handle.
+     */
+    subscribeAndWait(channel: string, options: {
+        lastEventId?: string;
+        params?: Record<string, any>;
+    }, callback: (payload: any, message?: Record<string, any>) => void): Promise<(() => void) & {
+        ready: Promise<void>;
+    }>;
+    /**
+     * @param {string} method - HTTP method.
+     * @param {string} path - Path.
+     * @param {object} [options] - Options object.
+     * @param {any} [options.body] - Request body.
+     * @param {Record<string, string>} [options.headers] - Header list.
+     * @returns {Promise<SnapReqWebSocketResponse>} - The response.
+     */
+    request(method: string, path: string, { body, headers }?: {
+        body?: any;
+        headers?: Record<string, string>;
+    }): Promise<SnapReqWebSocketResponse>;
+    /**
+     * @param {MessageEvent<any>} event - Event payload.
+     * @returns {void}
+     */
+    onMessage: (event: MessageEvent<any>) => void;
+    /**
+     * @param {string} channel - Channel name.
+     * @param {Record<string, any> | undefined} params - Subscription params.
+     * @returns {string} - Stable subscription key.
+     */
+    _subscriptionKey(channel: string, params: Record<string, any> | undefined): string;
+    /**
+     * Rejects all pending requests when the socket closes. Schedules reconnect if
+     * enabled.
+     * @returns {void}
+     */
+    onClose: () => void;
+    /**
+     * @param {Record<string, any>} payload - Payload data.
+     * @returns {void}
+     */
+    _sendMessage(payload: Record<string, any>): void;
+    /** @returns {void} */
+    _cancelPendingReconnect(): void;
+    /** @returns {void} */
+    _scheduleReconnect(): void;
+    /** @returns {Promise<void>} */
+    _attemptReconnect(): Promise<void>;
+    /**
+     * Re-sends subscribe messages for all active listeners after reconnection.
+     * @returns {void}
+     */
+    _resubscribeActiveListeners(): void;
+    /**
+     * @param  {...any} args - Log arguments.
+     * @returns {void}
+     */
+    _debug(...args: any[]): void;
+    /**
+     * @param {string} sessionId - Id to persist through the configured sessionStore.
+     * @returns {void}
+     */
+    _persistSessionId(sessionId: string): void;
+    /** @returns {void} */
+    _clearPersistedSessionId(): void;
+    /** @returns {Promise<void>} - Resolves once the session is ready. */
+    _waitForSessionReady(): Promise<void>;
+    /** @returns {void} */
+    _markSessionReady(): void;
+    /**
+     * @param {unknown} [error] - Reason for the reset.
+     * @returns {void}
+     */
+    _resetSessionReadyState(error?: unknown): void;
+}
+/** A response to a request made over the WebSocket transport. */
+export class SnapReqWebSocketResponse {
+    /**
+     * @param {object} message - The response message.
+     * @param {(value: any) => any} [deserialize] - Transform applied to the parsed body in `json()`. Defaults to identity.
+     */
+    constructor(message: object, deserialize?: (value: any) => any);
+    body: any;
+    headers: Record<string, any>;
+    id: string | number;
+    statusCode: number;
+    statusMessage: string;
+    type: string;
+    _deserialize: (value: any) => any;
+    /** @returns {any} - The parsed (and optionally deserialized) JSON body. */
+    json(): any;
+}
+import SnapReqWebSocketConnection from "./websocket-connection.js";
+import SnapReqWebSocketChannel from "./websocket-channel.js";

package/types/websocket/websocket-connection.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Client-side handle for a 1:1 connection opened via
+ * `SnapReqWebSocketClient.openConnection()`. Mirrors the server's connection
+ * lifecycle — `onConnect` / `onMessage` / `onClose` plus `sendMessage` /
+ * `close`.
+ */
+export default class SnapReqWebSocketConnection {
+    /**
+     * @param {object} args - Connection arguments.
+     * @param {import("./websocket-client.js").default} args.client - Owning client.
+     * @param {string} args.connectionId - Generated id unique within the session.
+     * @param {string} args.connectionType - Name the server registered the class under.
+     * @param {Record<string, any>} [args.params] - Opaque params forwarded to the server.
+     * @param {() => void} [args.onConnect] - Fired after the server confirms `connection-opened`.
+     * @param {(body: any) => void} [args.onMessage] - Fired on each `connection-message` from the server.
+     * @param {() => void} [args.onDisconnect] - Fired when the socket drops; connection is preserved pending resume.
+     * @param {() => void} [args.onResume] - Fired when the session successfully resumes after a drop.
+     * @param {(reason: string) => void} [args.onClose] - Fired exactly once when the handle closes permanently.
+     */
+    constructor({ client, connectionId, connectionType, params, onConnect, onMessage, onDisconnect, onResume, onClose }: {
+        client: import("./websocket-client.js").default;
+        connectionId: string;
+        connectionType: string;
+        params?: Record<string, any>;
+        onConnect?: () => void;
+        onMessage?: (body: any) => void;
+        onDisconnect?: () => void;
+        onResume?: () => void;
+        onClose?: (reason: string) => void;
+    });
+    client: import("./websocket-client.js").default;
+    connectionId: string;
+    connectionType: string;
+    params: Record<string, any>;
+    _onConnect: () => void;
+    _onMessage: (body: any) => void;
+    _onDisconnect: () => void;
+    _onResume: () => void;
+    _onClose: (reason: string) => void;
+    _connected: boolean;
+    _closed: boolean;
+    /** @type {Promise<void>} - Resolves once the server sends `connection-opened`. */
+    ready: Promise<void>;
+    _resolveReady: (value: void | PromiseLike<void>) => void;
+    _rejectReady: (reason?: any) => void;
+    /**
+     * Called by the client dispatcher when `{type: "connection-opened"}` arrives.
+     * Fires the user's `onConnect` and resolves `ready`.
+     * @returns {void}
+     */
+    _handleOpened(): void;
+    /**
+     * Called by the client dispatcher for each `connection-message` targeted at
+     * this connection id.
+     * @param {any} body - Message payload.
+     * @returns {void}
+     */
+    _handleMessage(body: any): void;
+    /**
+     * Called by the client when the underlying socket drops. The connection stays
+     * alive pending session resume.
+     * @returns {void}
+     */
+    _handleDisconnected(): void;
+    /**
+     * Called by the client after `session-resumed` confirms the server still has
+     * this connection.
+     * @returns {void}
+     */
+    _handleResumed(): void;
+    /**
+     * Called by the client dispatcher when the connection closes for any reason.
+     * Fires `onClose(reason)` at most once.
+     * @param {string} reason - Why the connection closed.
+     * @returns {void}
+     */
+    _handleClosed(reason: string): void;
+    /**
+     * Sends a message to the server side of this connection.
+     * @param {any} body - Message payload.
+     * @returns {void}
+     */
+    sendMessage(body: any): void;
+    /**
+     * Closes the connection from the client side. Fires `onClose("client_close")`
+     * locally and notifies the server. No-op if already closed.
+     * @returns {void}
+     */
+    close(): void;
+    /** @returns {boolean} - Whether the connection is closed. */
+    isClosed(): boolean;
+    /** @returns {boolean} - Whether the connection is open. */
+    isConnected(): boolean;
+}

package/src/index.js

@@ -1,22 +0,0 @@
-// @ts-check
-
-import SnapReq from "./snap-req.js"
-
-export default SnapReq
-export {default as SnapReq} from "./snap-req.js"
-export {default as SnapReqResponse} from "./response.js"
-export {default as SnapReqHeaders} from "./headers.js"
-export {
-  SnapReqError,
-  SnapReqHttpError,
-  SnapReqUnsupportedFeatureError,
-  SnapReqAbortError
-} from "./errors.js"
-export {defaultRetryableError} from "./retry.js"
-export {detectRuntime, selectTransport} from "./transports/select.js"
-export {default as FetchTransport} from "./transports/fetch-transport.js"
-export {default as XhrTransport} from "./transports/xhr-transport.js"
-
-// The WebSocket client is exported from its own module so importing the HTTP
-// client never pulls WebSocket code into a bundle that does not need it.
-export {default as SnapReqWebSocketClient} from "./websocket/websocket-client.js"