@trpc/client 11.0.0-rc.772 → 11.0.0-rc.781

package/src/links/wsLink/wsClient/options.ts

@@ -0,0 +1,91 @@
+import type { UrlOptionsWithConnectionParams } from '../../internals/urlWithConnectionParams';
+
+export interface WebSocketClientOptions extends UrlOptionsWithConnectionParams {
+  /**
+   * Ponyfill which WebSocket implementation to use
+   */
+  WebSocket?: typeof WebSocket;
+  /**
+   * The number of milliseconds before a reconnect is attempted.
+   * @default {@link exponentialBackoff}
+   */
+  retryDelayMs?: (attemptIndex: number) => number;
+  /**
+   * Triggered when a WebSocket connection is established
+   */
+  onOpen?: () => void;
+  /**
+   * Triggered when a WebSocket connection encounters an error
+   */
+  onError?: (evt?: Event) => void;
+  /**
+   * Triggered when a WebSocket connection is closed
+   */
+  onClose?: (cause?: { code?: number }) => void;
+  /**
+   * Lazy mode will close the WebSocket automatically after a period of inactivity (no messages sent or received and no pending requests)
+   */
+  lazy?: {
+    /**
+     * Enable lazy mode
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Close the WebSocket after this many milliseconds
+     * @default 0
+     */
+    closeMs: number;
+  };
+  /**
+   * Send ping messages to the server and kill the connection if no pong message is returned
+   */
+  keepAlive?: {
+    /**
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Send a ping message every this many milliseconds
+     * @default 5_000
+     */
+    intervalMs?: number;
+    /**
+     * Close the WebSocket after this many milliseconds if the server does not respond
+     * @default 1_000
+     */
+    pongTimeoutMs?: number;
+  };
+}
+
+/**
+ * Default options for lazy WebSocket connections.
+ * Determines whether the connection should be established lazily and defines the delay before closure.
+ */
+export type LazyOptions = Required<NonNullable<WebSocketClientOptions['lazy']>>;
+export const lazyDefaults: LazyOptions = {
+  enabled: false,
+  closeMs: 0,
+};
+
+/**
+ * Default options for the WebSocket keep-alive mechanism.
+ * Configures whether keep-alive is enabled and specifies the timeout and interval for ping-pong messages.
+ */
+export type KeepAliveOptions = Required<
+  NonNullable<WebSocketClientOptions['keepAlive']>
+>;
+export const keepAliveDefaults: KeepAliveOptions = {
+  enabled: false,
+  pongTimeoutMs: 1_000,
+  intervalMs: 5_000,
+};
+
+/**
+ * Calculates a delay for exponential backoff based on the retry attempt index.
+ * The delay starts at 0 for the first attempt and doubles for each subsequent attempt,
+ * capped at 30 seconds.
+ */
+export const exponentialBackoff = (attemptIndex: number) => {
+  return attemptIndex === 0 ? 0 : Math.min(1000 * 2 ** attemptIndex, 30000);
+};

package/src/links/wsLink/wsClient/requestManager.ts

@@ -0,0 +1,174 @@
+import type { AnyTRPCRouter, inferRouterError } from '@trpc/server';
+import type { Observer } from '@trpc/server/observable';
+import type {
+  TRPCClientOutgoingMessage,
+  TRPCResponseMessage,
+} from '@trpc/server/unstable-core-do-not-import';
+import type { TRPCClientError } from '../../../TRPCClientError';
+import { withResolvers } from './utils';
+
+export type TCallbacks = Observer<
+  TRPCResponseMessage<unknown, inferRouterError<AnyTRPCRouter>>,
+  TRPCClientError<AnyTRPCRouter>
+>;
+
+type MessageId = string;
+type MessageIdLike = string | number | null;
+
+/**
+ * Represents a WebSocket request managed by the RequestManager.
+ * Combines the network message, a utility promise (`end`) that mirrors the lifecycle
+ * handled by `callbacks`, and a set of state monitoring callbacks.
+ */
+interface Request {
+  message: TRPCClientOutgoingMessage;
+  end: Promise<void>;
+  callbacks: TCallbacks;
+}
+
+/**
+ * Manages WebSocket requests, tracking their lifecycle and providing utility methods
+ * for handling outgoing and pending requests.
+ *
+ * - **Outgoing requests**: Requests that are queued and waiting to be sent.
+ * - **Pending requests**: Requests that have been sent and are in flight awaiting a response.
+ *   For subscriptions, multiple responses may be received until the subscription is closed.
+ */
+export class RequestManager {
+  /**
+   * Stores requests that are outgoing, meaning they are registered but not yet sent over the WebSocket.
+   */
+  private outgoingRequests = new Array<Request & { id: MessageId }>();
+
+  /**
+   * Stores requests that are pending (in flight), meaning they have been sent over the WebSocket
+   * and are awaiting responses. For subscriptions, this includes requests
+   * that may receive multiple responses.
+   */
+  private pendingRequests: Record<MessageId, Request> = {};
+
+  /**
+   * Registers a new request by adding it to the outgoing queue and setting up
+   * callbacks for lifecycle events such as completion or error.
+   *
+   * @param message - The outgoing message to be sent.
+   * @param callbacks - Callback functions to observe the request's state.
+   * @returns A cleanup function to manually remove the request.
+   */
+  public register(message: TRPCClientOutgoingMessage, callbacks: TCallbacks) {
+    const { promise: end, resolve } = withResolvers<void>();
+
+    this.outgoingRequests.push({
+      id: String(message.id),
+      message,
+      end,
+      callbacks: {
+        next: callbacks.next,
+        complete: () => {
+          callbacks.complete();
+          resolve();
+        },
+        error: (e) => {
+          callbacks.error(e);
+          resolve();
+        },
+      },
+    });
+
+    return () => {
+      this.delete(message.id);
+      callbacks.complete();
+      resolve();
+    };
+  }
+
+  /**
+   * Deletes a request from both the outgoing and pending collections, if it exists.
+   */
+  public delete(messageId: MessageIdLike) {
+    if (messageId === null) return;
+
+    this.outgoingRequests = this.outgoingRequests.filter(
+      ({ id }) => id !== String(messageId),
+    );
+    delete this.pendingRequests[String(messageId)];
+  }
+
+  /**
+   * Moves all outgoing requests to the pending state and clears the outgoing queue.
+   *
+   * The caller is expected to handle the actual sending of the requests
+   * (e.g., sending them over the network) after this method is called.
+   *
+   * @returns The list of requests that were transitioned to the pending state.
+   */
+  public flush() {
+    const requests = this.outgoingRequests;
+    this.outgoingRequests = [];
+
+    for (const request of requests) {
+      this.pendingRequests[request.id] = request;
+    }
+    return requests;
+  }
+
+  /**
+   * Retrieves all currently pending requests, which are in flight awaiting responses
+   * or handling ongoing subscriptions.
+   */
+  public getPendingRequests() {
+    return Object.values(this.pendingRequests);
+  }
+
+  /**
+   * Retrieves a specific pending request by its message ID.
+   */
+  public getPendingRequest(messageId: MessageIdLike) {
+    if (messageId === null) return null;
+
+    return this.pendingRequests[String(messageId)];
+  }
+
+  /**
+   * Retrieves all outgoing requests, which are waiting to be sent.
+   */
+  public getOutgoingRequests() {
+    return this.outgoingRequests;
+  }
+
+  /**
+   * Retrieves all requests, both outgoing and pending, with their respective states.
+   *
+   * @returns An array of all requests with their state ("outgoing" or "pending").
+   */
+  public getRequests() {
+    return [
+      ...this.getOutgoingRequests().map((request) => ({
+        state: 'outgoing' as const,
+        message: request.message,
+        end: request.end,
+        callbacks: request.callbacks,
+      })),
+      ...this.getPendingRequests().map((request) => ({
+        state: 'pending' as const,
+        message: request.message,
+        end: request.end,
+        callbacks: request.callbacks,
+      })),
+    ];
+  }
+
+  /**
+   * Checks if there are any pending requests, including ongoing subscriptions.
+   */
+  public hasPendingRequests() {
+    return this.getPendingRequests().length > 0;
+  }
+
+  /**
+   * Checks if there are any outgoing requests waiting to be sent.
+   */
+  public hasOutgoingRequests() {
+    return this.outgoingRequests.length > 0;
+  }
+}

package/src/links/wsLink/wsClient/utils.ts

@@ -0,0 +1,94 @@
+import type {
+  TRPCConnectionParamsMessage,
+  TRPCRequestInfo,
+} from '@trpc/server/unstable-core-do-not-import';
+import type {
+  CallbackOrValue,
+  UrlOptionsWithConnectionParams,
+} from '../../internals/urlWithConnectionParams';
+import { resultOf } from '../../internals/urlWithConnectionParams';
+
+export class TRPCWebSocketClosedError extends Error {
+  constructor(opts: { message: string; cause?: unknown }) {
+    super(opts.message, {
+      cause: opts.cause,
+    });
+    this.name = 'TRPCWebSocketClosedError';
+    Object.setPrototypeOf(this, TRPCWebSocketClosedError.prototype);
+  }
+}
+
+/**
+ * Utility class for managing a timeout that can be started, stopped, and reset.
+ * Useful for scenarios where the timeout duration is reset dynamically based on events.
+ */
+export class ResettableTimeout {
+  private timeout: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(
+    private readonly onTimeout: () => void,
+    private readonly timeoutMs: number,
+  ) {}
+
+  /**
+   * Resets the current timeout, restarting it with the same duration.
+   * Does nothing if no timeout is active.
+   */
+  public reset() {
+    if (!this.timeout) return;
+
+    clearTimeout(this.timeout);
+    this.timeout = setTimeout(this.onTimeout, this.timeoutMs);
+  }
+
+  public start() {
+    clearTimeout(this.timeout);
+    this.timeout = setTimeout(this.onTimeout, this.timeoutMs);
+  }
+
+  public stop() {
+    clearTimeout(this.timeout);
+    this.timeout = undefined;
+  }
+}
+
+// Ponyfill for Promise.withResolvers https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
+export function withResolvers<T>() {
+  let resolve: (value: T | PromiseLike<T>) => void;
+  let reject: (reason?: any) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return { promise, resolve: resolve!, reject: reject! };
+}
+
+/**
+ * Resolves a WebSocket URL and optionally appends connection parameters.
+ *
+ * If connectionParams are provided, appends 'connectionParams=1' query parameter.
+ */
+export async function prepareUrl(urlOptions: UrlOptionsWithConnectionParams) {
+  const url = await resultOf(urlOptions.url);
+
+  if (!urlOptions.connectionParams) return url;
+
+  // append `?connectionParams=1` when connection params are used
+  const prefix = url.includes('?') ? '&' : '?';
+  const connectionParams = `${prefix}connectionParams=1`;
+
+  return url + connectionParams;
+}
+
+export async function buildConnectionMessage(
+  connectionParams: CallbackOrValue<TRPCRequestInfo['connectionParams']>,
+) {
+  const message: TRPCConnectionParamsMessage = {
+    method: 'connectionParams',
+    data: await resultOf(connectionParams),
+  };
+
+  return JSON.stringify(message);
+}