feat: expose in public api ability to create a ws connection by specifying a WsSocketFactory, and referencing it in WsConnectionOptions.

WsConnectionOptions is a ConnectionOptions that exposes `wsFactory?: WsSocketFactory`

This enables uses where the runtime is known to provide additional options that may be necessary for the connection but differ from standard W3C `new WebSocket(url)` usages.

Signed-off-by: Alberto Ricart <[email protected]>

Author: aricart

core/src/internal_mod.ts

@@ -146,6 +146,8 @@ export { isIPV4OrHostname, Servers } from "./servers.ts";
 
 export { wsconnect, wsUrlParseFn } from "./ws_transport.ts";
 
+export type { WsConnectionOptions, WsSocketFactory } from "./ws_transport.ts";
+
 export {
   AuthorizationError,
   ClosedConnectionError,

core/src/mod.ts

@@ -105,4 +105,6 @@ export type {
   TlsOptions,
   TokenAuth,
   UserPass,
+  WsConnectionOptions,
+  WsSocketFactory,
 } from "./internal_mod.ts";

core/src/ws_transport.ts

@@ -33,11 +33,26 @@ import { errors, InvalidArgumentError } from "./errors.ts";
 const VERSION = version;
 const LANG = "nats.ws";
 
+/**
+ * WsSocketFactory is a factory that returns a WebSocket and a boolean
+ * indicating if the connection is encrypted. Client code is responsible
+ * for creating a W3C WebSocket compliant transport.
+ *
+ * @param u the url to connect to
+ * @param opts the connection options
+ * @returns a promise that resolves to a WebSocket and a boolean indicating if
+ * the connection is encrypted
+ */
 export type WsSocketFactory = (u: string, opts: ConnectionOptions) => Promise<{
   socket: WebSocket;
   encrypted: boolean;
 }>;
-interface WsConnectionOptions extends ConnectionOptions {
+
+/**
+ * WsConnectionOptions exposes wsconnect specific options not applicable to
+ * other transports.
+ */
+export interface WsConnectionOptions extends ConnectionOptions {
   wsFactory?: WsSocketFactory;
 }
 
@@ -334,7 +349,7 @@ export function wsUrlParseFn(u: string, encrypted?: boolean): string {
 }
 
 export function wsconnect(
-  opts: ConnectionOptions = {},
+  opts: ConnectionOptions | WsConnectionOptions = {},
 ): Promise<NatsConnection> {
   setTransportFactory({
     defaultPort: 443,