@ebarahona/loopback-transport-core 1.0.0 → 1.2.0

package/dist/client/client-proxy.d.ts

@@ -1,5 +1,5 @@
 import { Observable, ReplaySubject } from 'rxjs';
-import { TransportClient, TransportStatus, WritePacket, ReadPacket, PacketId } from '../interfaces';
+import type { PacketId, ReadPacket, TransportClient, TransportStatus, WritePacket } from '../interfaces';
 /**
  * Abstract base class for transport clients.
  *
@@ -8,35 +8,37 @@ import { TransportClient, TransportStatus, WritePacket, ReadPacket, PacketId } f
  * - `send()`/`emit()` lazily connect on first use.
  * - Concurrent send/emit calls share one connect().
  * - `close()` transitions to 'closing', waits for any pending connect
- *   (bounded by `closeConnectTimeoutMs`, default 5s), calls doClose(),
+ *   (bounded by `closeConnectTimeoutMs`, default 5s), calls `doClose()`,
  *   then transitions to 'idle'.
  * - If the pending connect does not settle within the timeout, close
- *   proceeds anyway. The adapter's doClose() must safely tear down
+ *   proceeds anyway. The adapter's `doClose()` must safely tear down
  *   partially opened native resources in this case.
  * - `send()`/`emit()` during 'closing' fail fast.
  * - After close, the next send/emit reconnects.
  * - A stale connect that resolves after close always rejects for its
  *   original caller, even if a newer connection is already healthy.
- * - State is always reset in finally -- failed doClose() does not
+ * - State is always reset in finally — a failed `doClose()` does not
  *   leave the client stuck.
  *
  * ## Stale async detection
  *
- * A monotonic `epoch` counter increments on each close(). The
- * connect callback only transitions to 'connected' if the epoch
- * has not changed, preventing a late-resolving connect from
- * overriding a close that happened while it was pending.
+ * A monotonic `epoch` counter increments on each `close()`. The connect
+ * callback only transitions to `connected` if the epoch has not changed,
+ * preventing a late-resolving connect from overriding a close that
+ * happened while it was pending.
  *
- * The connectionPromise is only cleared by its own .finally()
+ * The `connectionPromise` is only cleared by its own `.finally()`
  * callback if it is still the current promise, preventing a stale
  * promise from clobbering a newer one.
+ *
+ * @public
  */
 export declare abstract class ClientProxy implements TransportClient {
     protected readonly statusSubject: ReplaySubject<TransportStatus>;
     private state;
-    private connectionPromise?;
-    private connectionEpoch?;
-    private closePromise?;
+    private connectionPromise;
+    private connectionEpoch;
+    private closePromise;
     private epoch;
     private readonly closeConnectTimeoutMs;
     readonly status$: Observable<TransportStatus>;
@@ -44,16 +46,19 @@ export declare abstract class ClientProxy implements TransportClient {
         closeConnectTimeoutMs?: number;
     });
     /**
-     * Establish connection to the broker.
-     * Implementations should be idempotent (safe to call multiple times).
+     * Establish connection to the broker. Implementations should be
+     * idempotent (safe to call multiple times).
+     *
+     * @public
      */
     abstract connect(): Promise<void>;
     /**
      * Close the native connection. Implemented by transport adapters.
-     * Called by the base close() template method after waiting for any
-     * pending connect (bounded by closeConnectTimeoutMs). If the timeout
-     * fires before connect settles, doClose() is still called -- adapters
-     * must handle partially opened native resources in that case.
+     * Called by the base `close()` template method after waiting for any
+     * pending connect (bounded by `closeConnectTimeoutMs`). If the
+     * timeout fires before connect settles, `doClose()` is still called —
+     * adapters must handle partially opened native resources in that
+     * case.
      */
     protected abstract doClose(): Promise<void>;
     /**
@@ -62,25 +67,33 @@ export declare abstract class ClientProxy implements TransportClient {
      * - If idle with no pending connect, returns immediately (no-op).
      * - If already closing, returns the existing close promise (dedupe).
      * - Otherwise:
-     *   1. Increments epoch to invalidate any in-flight connect().
-     *   2. Transitions to 'closing' so new send/emit fails fast.
-     *   3. Waits for pending connect (bounded by closeConnectTimeoutMs).
-     *   4. Calls doClose() for adapter-specific teardown.
-     *   5. Resets to 'idle' in finally (even if doClose throws).
+     *   1. Increments epoch to invalidate any in-flight `connect()`.
+     *   2. Transitions to `closing` so new send/emit fails fast.
+     *   3. Waits for pending connect (bounded by `closeConnectTimeoutMs`).
+     *   4. Calls `doClose()` for adapter-specific teardown.
+     *   5. Resets to `idle` in finally (even if `doClose` throws).
      *
-     * After close, the client is reusable: the next send/emit
-     * will trigger a fresh connect().
+     * After close, the client is reusable: the next send/emit will
+     * trigger a fresh `connect()`.
+     *
+     * @public
+     * @throws TransportError When the adapter's `doClose()` rejects.
+     *   State is still reset to `idle` so the client remains reusable.
      */
     close(): Promise<void>;
     private doCloseInternal;
     /**
-     * Wait for a pending connect to settle, bounded by timeout.
-     * If connect does not settle in time, proceed anyway -- the epoch
+     * Wait for a pending connect to settle, bounded by timeout. If
+     * connect does not settle in time, proceed anyway — the epoch
      * invalidation ensures the stale connect result is ignored.
      */
     private waitForPendingConnect;
     /**
      * Access the underlying native client.
+     *
+     * @public
+     * @typeParam T - Caller-asserted shape of the native client.
+     * @returns The native client cast to `T`.
      */
     abstract unwrap<T>(): T;
     /**
@@ -97,22 +110,40 @@ export declare abstract class ClientProxy implements TransportClient {
      *
      * Returns a cold Observable: the message is sent only when subscribed.
      * The connection is established lazily on first subscription.
+     *
+     * @public
+     * @typeParam TResult - Expected response shape.
+     * @typeParam TInput - Caller-provided payload shape.
+     * @param pattern - Pattern to match on the server side.
+     * @param data - The message payload.
+     * @returns A cold Observable that emits the response value(s).
      */
     send<TResult = unknown, TInput = unknown>(pattern: string | Record<string, unknown>, data: TInput): Observable<TResult>;
     /**
      * Emit an event with no response expected (fire-and-forget pattern).
      *
-     * Returns a Promise that resolves when the event is dispatched.
-     * The connection is established lazily if not already connected.
+     * Returns a Promise that resolves when the event is dispatched. The
+     * connection is established lazily if not already connected.
+     *
+     * @public
+     * @typeParam TInput - Caller-provided payload shape.
+     * @param pattern - Event pattern.
+     * @param data - The event payload.
+     * @returns Resolves when the broker has accepted the event.
+     * @throws TransportError When the client is closing or a concurrent
+     *   close invalidated the pending connect.
      */
     emit<TInput = unknown>(pattern: string | Record<string, unknown>, data: TInput): Promise<void>;
     /**
-     * Assign a unique correlation ID to a packet.
-     * Uses crypto.randomUUID() for distributed-system-safe IDs.
+     * Assign a unique correlation ID to a packet. Uses
+     * `crypto.randomUUID()` for distributed-system-safe IDs.
      */
     protected assignPacketId(packet: ReadPacket): ReadPacket & PacketId;
     /**
-     * Create an Observer callback that maps WritePacket to Observable emissions.
+     * Create an Observer callback that maps `WritePacket` values to
+     * Observable emissions.
+     *
+     * @typeParam T - Expected response type.
      */
     protected createObserver<T>(observer: {
         next: (value: T) => void;
@@ -120,27 +151,27 @@ export declare abstract class ClientProxy implements TransportClient {
         complete: () => void;
     }): (packet: WritePacket) => void;
     /**
-     * Verify the client is in connected state.
-     * Throws if a concurrent close() prevented the transition.
+     * Verify the client is in connected state. Throws if a concurrent
+     * close prevented the transition.
      */
     private assertConnected;
     /**
      * Ensure the client is connected. Concurrent calls share the same
      * connection promise to prevent duplicate connections.
      *
-     * - 'closing': reject immediately.
-     * - 'connected': return immediately.
-     * - 'connecting': await the shared promise.
-     * - 'idle': start connect, capture epoch, only transition to
-     *   'connected' if epoch hasn't changed.
+     * - `closing`: reject immediately.
+     * - `connected`: return immediately.
+     * - `connecting`: await the shared promise.
+     * - `idle`: start connect, capture epoch, only transition to
+     *   `connected` if epoch hasn't changed.
      *
      * After await, the caller validates that the epoch it waited on
      * still matches. A stale connect that was invalidated by close()
-     * always rejects for its original caller, even if a newer
-     * connection is already healthy.
+     * always rejects for its original caller, even if a newer connection
+     * is already healthy.
      *
      * The connectionPromise/connectionEpoch are only cleared in
-     * .finally() if the finishing promise is still the current one,
+     * `.finally()` if the finishing promise is still the current one,
      * preventing a stale promise from clobbering a newer one.
      */
     private ensureConnected;

package/dist/client/client-proxy.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientProxy = void 0;
 const crypto_1 = require("crypto");
 const rxjs_1 = require("rxjs");
+const errors_1 = require("../helpers/errors");
 const utils_1 = require("../utils");
 /**
  * Abstract base class for transport clients.
@@ -12,35 +13,41 @@ const utils_1 = require("../utils");
  * - `send()`/`emit()` lazily connect on first use.
  * - Concurrent send/emit calls share one connect().
  * - `close()` transitions to 'closing', waits for any pending connect
- *   (bounded by `closeConnectTimeoutMs`, default 5s), calls doClose(),
+ *   (bounded by `closeConnectTimeoutMs`, default 5s), calls `doClose()`,
  *   then transitions to 'idle'.
  * - If the pending connect does not settle within the timeout, close
- *   proceeds anyway. The adapter's doClose() must safely tear down
+ *   proceeds anyway. The adapter's `doClose()` must safely tear down
  *   partially opened native resources in this case.
  * - `send()`/`emit()` during 'closing' fail fast.
  * - After close, the next send/emit reconnects.
  * - A stale connect that resolves after close always rejects for its
  *   original caller, even if a newer connection is already healthy.
- * - State is always reset in finally -- failed doClose() does not
+ * - State is always reset in finally — a failed `doClose()` does not
  *   leave the client stuck.
  *
  * ## Stale async detection
  *
- * A monotonic `epoch` counter increments on each close(). The
- * connect callback only transitions to 'connected' if the epoch
- * has not changed, preventing a late-resolving connect from
- * overriding a close that happened while it was pending.
+ * A monotonic `epoch` counter increments on each `close()`. The connect
+ * callback only transitions to `connected` if the epoch has not changed,
+ * preventing a late-resolving connect from overriding a close that
+ * happened while it was pending.
  *
- * The connectionPromise is only cleared by its own .finally()
+ * The `connectionPromise` is only cleared by its own `.finally()`
  * callback if it is still the current promise, preventing a stale
  * promise from clobbering a newer one.
+ *
+ * @public
  */
 class ClientProxy {
+    statusSubject = new rxjs_1.ReplaySubject(1);
+    state = 'idle';
+    connectionPromise;
+    connectionEpoch;
+    closePromise;
+    epoch = 0;
+    closeConnectTimeoutMs;
+    status$ = this.statusSubject.asObservable();
     constructor(options) {
-        this.statusSubject = new rxjs_1.ReplaySubject(1);
-        this.state = 'idle';
-        this.epoch = 0;
-        this.status$ = this.statusSubject.asObservable();
         this.closeConnectTimeoutMs = options?.closeConnectTimeoutMs ?? 5000;
     }
     /**
@@ -49,14 +56,18 @@ class ClientProxy {
      * - If idle with no pending connect, returns immediately (no-op).
      * - If already closing, returns the existing close promise (dedupe).
      * - Otherwise:
-     *   1. Increments epoch to invalidate any in-flight connect().
-     *   2. Transitions to 'closing' so new send/emit fails fast.
-     *   3. Waits for pending connect (bounded by closeConnectTimeoutMs).
-     *   4. Calls doClose() for adapter-specific teardown.
-     *   5. Resets to 'idle' in finally (even if doClose throws).
+     *   1. Increments epoch to invalidate any in-flight `connect()`.
+     *   2. Transitions to `closing` so new send/emit fails fast.
+     *   3. Waits for pending connect (bounded by `closeConnectTimeoutMs`).
+     *   4. Calls `doClose()` for adapter-specific teardown.
+     *   5. Resets to `idle` in finally (even if `doClose` throws).
+     *
+     * After close, the client is reusable: the next send/emit will
+     * trigger a fresh `connect()`.
      *
-     * After close, the client is reusable: the next send/emit
-     * will trigger a fresh connect().
+     * @public
+     * @throws TransportError When the adapter's `doClose()` rejects.
+     *   State is still reset to `idle` so the client remains reusable.
      */
     async close() {
         if (this.state === 'idle' && !this.connectionPromise)
@@ -71,7 +82,7 @@ class ClientProxy {
     async doCloseInternal() {
         this.epoch++;
         this.state = 'closing';
-        // Wait for pending connect with timeout so close never hangs
+        // Wait for pending connect with timeout so close never hangs.
         await this.waitForPendingConnect();
         try {
             await this.doClose();
@@ -84,8 +95,8 @@ class ClientProxy {
         }
     }
     /**
-     * Wait for a pending connect to settle, bounded by timeout.
-     * If connect does not settle in time, proceed anyway -- the epoch
+     * Wait for a pending connect to settle, bounded by timeout. If
+     * connect does not settle in time, proceed anyway — the epoch
      * invalidation ensures the stale connect result is ignored.
      */
     async waitForPendingConnect() {
@@ -102,6 +113,13 @@ class ClientProxy {
      *
      * Returns a cold Observable: the message is sent only when subscribed.
      * The connection is established lazily on first subscription.
+     *
+     * @public
+     * @typeParam TResult - Expected response shape.
+     * @typeParam TInput - Caller-provided payload shape.
+     * @param pattern - Pattern to match on the server side.
+     * @param data - The message payload.
+     * @returns A cold Observable that emits the response value(s).
      */
     send(pattern, data) {
         const normalizedPattern = (0, utils_1.normalizePattern)(pattern);
@@ -117,8 +135,16 @@ class ClientProxy {
     /**
      * Emit an event with no response expected (fire-and-forget pattern).
      *
-     * Returns a Promise that resolves when the event is dispatched.
-     * The connection is established lazily if not already connected.
+     * Returns a Promise that resolves when the event is dispatched. The
+     * connection is established lazily if not already connected.
+     *
+     * @public
+     * @typeParam TInput - Caller-provided payload shape.
+     * @param pattern - Event pattern.
+     * @param data - The event payload.
+     * @returns Resolves when the broker has accepted the event.
+     * @throws TransportError When the client is closing or a concurrent
+     *   close invalidated the pending connect.
      */
     async emit(pattern, data) {
         const normalizedPattern = (0, utils_1.normalizePattern)(pattern);
@@ -126,14 +152,17 @@ class ClientProxy {
         await this.dispatchEvent({ pattern: normalizedPattern, data });
     }
     /**
-     * Assign a unique correlation ID to a packet.
-     * Uses crypto.randomUUID() for distributed-system-safe IDs.
+     * Assign a unique correlation ID to a packet. Uses
+     * `crypto.randomUUID()` for distributed-system-safe IDs.
      */
     assignPacketId(packet) {
         return { ...packet, id: (0, crypto_1.randomUUID)() };
     }
     /**
-     * Create an Observer callback that maps WritePacket to Observable emissions.
+     * Create an Observer callback that maps `WritePacket` values to
+     * Observable emissions.
+     *
+     * @typeParam T - Expected response type.
      */
     createObserver(observer) {
         return (packet) => {
@@ -149,40 +178,40 @@ class ClientProxy {
         };
     }
     /**
-     * Verify the client is in connected state.
-     * Throws if a concurrent close() prevented the transition.
+     * Verify the client is in connected state. Throws if a concurrent
+     * close prevented the transition.
      */
     assertConnected() {
         if (this.state !== 'connected') {
-            throw new Error('Client was closed during connection');
+            throw new errors_1.TransportError('Client was closed during connection');
         }
     }
     /**
      * Ensure the client is connected. Concurrent calls share the same
      * connection promise to prevent duplicate connections.
      *
-     * - 'closing': reject immediately.
-     * - 'connected': return immediately.
-     * - 'connecting': await the shared promise.
-     * - 'idle': start connect, capture epoch, only transition to
-     *   'connected' if epoch hasn't changed.
+     * - `closing`: reject immediately.
+     * - `connected`: return immediately.
+     * - `connecting`: await the shared promise.
+     * - `idle`: start connect, capture epoch, only transition to
+     *   `connected` if epoch hasn't changed.
      *
      * After await, the caller validates that the epoch it waited on
      * still matches. A stale connect that was invalidated by close()
-     * always rejects for its original caller, even if a newer
-     * connection is already healthy.
+     * always rejects for its original caller, even if a newer connection
+     * is already healthy.
      *
      * The connectionPromise/connectionEpoch are only cleared in
-     * .finally() if the finishing promise is still the current one,
+     * `.finally()` if the finishing promise is still the current one,
      * preventing a stale promise from clobbering a newer one.
      */
     async ensureConnected() {
         if (this.state === 'closing') {
-            throw new Error('Client is closing');
+            throw new errors_1.TransportError('Client is closing');
         }
         if (this.state === 'connected')
             return;
-        // Capture the epoch this caller will wait on
+        // Capture the epoch this caller will wait on.
         const awaitedEpoch = this.connectionEpoch ?? this.epoch;
         if (!this.connectionPromise) {
             const ep = this.epoch;
@@ -195,7 +224,7 @@ class ClientProxy {
                     this.statusSubject.next('connected');
                 }
                 else {
-                    throw new Error('Client was closed during connection');
+                    throw new errors_1.TransportError('Client was closed during connection');
                 }
             })
                 .catch(err => {
@@ -216,7 +245,7 @@ class ClientProxy {
         // Validate that this caller's epoch is still current.
         // A stale caller whose connect was invalidated must not proceed.
         if (this.epoch !== awaitedEpoch) {
-            throw new Error('Client was closed during connection');
+            throw new errors_1.TransportError('Client was closed during connection');
         }
         this.assertConnected();
     }

package/dist/client/client-proxy.js.map

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

package/dist/client/index.d.ts

@@ -1 +1 @@
-export * from './client-proxy';
+export { ClientProxy } from './client-proxy';

package/dist/client/index.js

@@ -1,18 +1,6 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./client-proxy"), exports);
+exports.ClientProxy = void 0;
+var client_proxy_1 = require("./client-proxy");
+Object.defineProperty(exports, "ClientProxy", { enumerable: true, get: function () { return client_proxy_1.ClientProxy; } });
 //# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;AAAA,+CAA2C;AAAnC,2GAAA,WAAW,OAAA"}

package/dist/context/execution-context.d.ts

@@ -1,17 +1,26 @@
 /**
  * The type of transport handling the current request.
+ *
+ * @public
  */
 export type ContextType = 'http' | 'rpc' | 'event';
 /**
  * Handler function type. Avoids bare `Function`.
+ *
+ * @public
  */
 export type HandlerFunction = (...args: unknown[]) => unknown;
 /**
  * Controller class type. Avoids bare `Function`.
+ *
+ * @public
+ * @typeParam T - The constructed instance type.
  */
 export type ControllerClass<T = unknown> = abstract new (...args: never[]) => T;
 /**
  * HTTP-specific context. Wraps Express request/response.
+ *
+ * @public
  */
 export interface HttpContext {
     getRequest<T = unknown>(): T;
@@ -19,6 +28,8 @@ export interface HttpContext {
 }
 /**
  * RPC-specific context (gRPC, request/response patterns).
+ *
+ * @public
  */
 export interface RpcContext {
     getData<T = unknown>(): T;
@@ -27,6 +38,8 @@ export interface RpcContext {
 }
 /**
  * Event-specific context (Kafka, RabbitMQ, MQTT, NATS events).
+ *
+ * @public
  */
 export interface EventContext {
     getData<T = unknown>(): T;
@@ -34,14 +47,17 @@ export interface EventContext {
     getContext<T = unknown>(): T;
 }
 /**
- * Unified execution context that works across HTTP, RPC, and event transports.
+ * Unified execution context that works across HTTP, RPC, and event
+ * transports.
  *
- * Immutable after construction. Created via static factory methods
- * that guarantee the transport-specific context is present.
- * No half-built contexts, no post-construction mutation.
+ * Immutable after construction. Created via static factory methods that
+ * guarantee the transport-specific context is present. No half-built
+ * contexts, no post-construction mutation.
  *
- * NestJS-compatible mental model: getType() + switchToHttp/Rpc/Event.
+ * NestJS-compatible mental model: `getType()` + `switchToHttp/Rpc/Event`.
  * Cleaner construction: factory methods enforce correct state.
+ *
+ * @public
  */
 export declare class ExecutionContext {
     private readonly type;
@@ -54,49 +70,80 @@ export declare class ExecutionContext {
     private constructor();
     /**
      * Create an HTTP execution context.
+     *
+     * @public
      */
     static forHttp(args: unknown[], handler: HandlerFunction, controllerClass: ControllerClass, httpCtx: HttpContext): ExecutionContext;
     /**
      * Create an RPC execution context (gRPC, request/response patterns).
+     *
+     * @public
      */
     static forRpc(args: unknown[], handler: HandlerFunction, controllerClass: ControllerClass, rpcCtx: RpcContext): ExecutionContext;
     /**
      * Create an event execution context (Kafka, RabbitMQ, MQTT, NATS).
+     *
+     * @public
      */
     static forEvent(args: unknown[], handler: HandlerFunction, controllerClass: ControllerClass, eventCtx: EventContext): ExecutionContext;
     /**
      * Returns the transport type handling this request.
+     *
+     * @public
      */
     getType(): ContextType;
     /**
      * Returns the controller class the handler belongs to.
+     *
+     * @experimental The generic parameter is asserted, not inferred.
+     *   Callers must verify the resulting class shape themselves.
+     * @typeParam T - Caller-asserted instance type.
      */
     getClass<T = unknown>(): ControllerClass<T>;
     /**
      * Returns the handler function that will be invoked.
+     *
+     * @public
      */
     getHandler(): HandlerFunction;
     /**
      * Returns a copy of the arguments array.
+     *
+     * @experimental Callers assert the tuple shape; no runtime check is
+     *   performed.
+     * @typeParam T - Caller-asserted tuple type.
      */
     getArgs<T extends readonly unknown[] = readonly unknown[]>(): T;
     /**
      * Returns a specific argument by index.
+     *
+     * @experimental Callers assert the value type; no runtime check is
+     *   performed.
+     * @typeParam T - Caller-asserted argument type.
      */
     getArgByIndex<T = unknown>(index: number): T;
     /**
-     * Switch to HTTP context.
-     * Throws if the current type is not 'http' or context is missing.
+     * Switch to HTTP context. Throws if the current type is not `http`
+     * or the context is missing.
+     *
+     * @public
+     * @throws TransportError When the current transport type is not HTTP.
      */
     switchToHttp(): HttpContext;
     /**
-     * Switch to RPC context.
-     * Throws if the current type is not 'rpc' or context is missing.
+     * Switch to RPC context. Throws if the current type is not `rpc` or
+     * the context is missing.
+     *
+     * @public
+     * @throws TransportError When the current transport type is not RPC.
      */
     switchToRpc(): RpcContext;
     /**
-     * Switch to event context.
-     * Throws if the current type is not 'event' or context is missing.
+     * Switch to event context. Throws if the current type is not `event`
+     * or the context is missing.
+     *
+     * @public
+     * @throws TransportError When the current transport type is not event.
      */
     switchToEvent(): EventContext;
 }