Move transports to own folder/files for easier dynamic loading. Update tests.

Author: douglascayers

src/RosLib.ts

@@ -12,13 +12,15 @@ export { default as Topic } from "./core/Topic.js";
 export { default as Param } from "./core/Param.js";
 export { default as Service } from "./core/Service.js";
 export { default as Action } from "./core/Action.js";
+
+// Core Transport exports
 export {
+  AbstractTransport,
   type ITransport,
   type ITransportFactory,
   type TransportEvent,
-  AbstractTransport,
-  WebSocketTransportFactory,
-} from "./core/Transport.js";
+} from "./core/transport/Transport.js";
+export { WebSocketTransportFactory } from "./core/transport/WebSocketTransportFactory.js";
 
 // ActionLib exports
 export { default as ActionClient } from "./actionlib/ActionClient.js";

src/core/Ros.ts

@@ -30,8 +30,8 @@ import type {
   ITransport,
   ITransportFactory,
   TransportEvent,
-} from "./Transport.js";
-import { WebSocketTransportFactory } from "./Transport.js";
+} from "./transport/Transport.js";
+import { WebSocketTransportFactory } from "./transport/WebSocketTransportFactory.ts";
 
 /**
  * Manages connection to the rosbridge server and all interactions with ROS.

src/core/transport/NativeWebSocketTransport.ts

@@ -0,0 +1,59 @@
+import type { RosbridgeMessage } from "../../types/protocol.js";
+import { AbstractTransport } from "./Transport.js";
+
+/**
+ * Uses the native `WebSocket` class to send and receive messages.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+ */
+export class NativeWebSocketTransport extends AbstractTransport {
+  private socket: WebSocket;
+
+  constructor(socket: WebSocket) {
+    super();
+    this.socket = socket;
+    this.registerEventListeners();
+  }
+
+  public send(message: RosbridgeMessage): void {
+    this.socket.send(JSON.stringify(message));
+  }
+
+  public close(): void {
+    this.socket.close();
+  }
+
+  public isConnecting(): boolean {
+    return this.socket.readyState === WebSocket.CONNECTING;
+  }
+
+  public isOpen(): boolean {
+    return this.socket.readyState === WebSocket.OPEN;
+  }
+
+  public isClosing(): boolean {
+    return this.socket.readyState === WebSocket.CLOSING;
+  }
+
+  public isClosed(): boolean {
+    return this.socket.readyState === WebSocket.CLOSED;
+  }
+
+  private registerEventListeners(): void {
+    this.socket.onopen = (event: Event) => {
+      this.emit("open", event);
+    };
+
+    this.socket.onclose = (event: CloseEvent) => {
+      this.emit("close", event);
+    };
+
+    this.socket.onerror = (event: Event) => {
+      this.emit("error", event);
+    };
+
+    this.socket.onmessage = (event: MessageEvent) => {
+      this.handleRawMessage(event.data);
+    };
+  }
+}

src/core/Transport.ts src/core/transport/Transport.tssrc/core/Transport.ts renamed to src/core/transport/Transport.ts

@@ -3,17 +3,16 @@ import type {
   RosbridgePngMessage,
   RosbridgeMessage,
   RosbridgeFragmentMessage,
-} from "../types/protocol.js";
+} from "../../types/protocol.js";
 import {
   isRosbridgeFragmentMessage,
   isRosbridgeMessage,
   isRosbridgePngMessage,
-} from "../types/protocol.js";
-import * as ws from "ws";
+} from "../../types/protocol.js";
 import { deserialize } from "bson";
 import CBOR from "cbor-js";
-import typedArrayTagger from "../util/cborTypedArrayTags.js";
-import decompressPng from "../util/decompressPng.js";
+import typedArrayTagger from "../../util/cborTypedArrayTags.js";
+import decompressPng from "../../util/decompressPng.js";
 
 /**
  * Because transport implementations may have different event types
@@ -22,6 +21,12 @@ import decompressPng from "../util/decompressPng.js";
  */
 export type TransportEvent = unknown;
 
+/**
+ * Abstraction responsible for sending and receiving messages
+ * between the client and the rosbridge server.
+ *
+ * Inspired by the WebSocket API, which is the default reference implementation.
+ */
 export interface ITransport {
   on(
     event: "open" | "close" | "error",
@@ -40,8 +45,16 @@ export interface ITransport {
   isClosed(): boolean;
 }
 
+/**
+ * Invoked when the roslib needs a new transport, such as
+ * when (re)connecting to the rosbridge server.
+ */
 export type ITransportFactory = (url: string) => Promise<ITransport>;
 
+/**
+ * Abstract base class for all transport implementations.
+ * Provides a default implementation for decoding raw rosbridge messages.
+ */
 export abstract class AbstractTransport
   extends EventEmitter<{
     open: [TransportEvent];
@@ -227,132 +240,3 @@ export abstract class AbstractTransport
     }
   }
 }
-
-export class NativeWebSocketTransport extends AbstractTransport {
-  private socket: WebSocket;
-
-  constructor(socket: WebSocket) {
-    super();
-    this.socket = socket;
-    this.registerEventListeners();
-  }
-
-  public send(message: RosbridgeMessage): void {
-    this.socket.send(JSON.stringify(message));
-  }
-
-  public close(): void {
-    this.socket.close();
-  }
-
-  public isConnecting(): boolean {
-    return this.socket.readyState === WebSocket.CONNECTING;
-  }
-
-  public isOpen(): boolean {
-    return this.socket.readyState === WebSocket.OPEN;
-  }
-
-  public isClosing(): boolean {
-    return this.socket.readyState === WebSocket.CLOSING;
-  }
-
-  public isClosed(): boolean {
-    return this.socket.readyState === WebSocket.CLOSED;
-  }
-
-  private registerEventListeners(): void {
-    this.socket.onopen = (event: Event) => {
-      this.emit("open", event);
-    };
-
-    this.socket.onclose = (event: CloseEvent) => {
-      this.emit("close", event);
-    };
-
-    this.socket.onerror = (event: Event) => {
-      this.emit("error", event);
-    };
-
-    this.socket.onmessage = (event: MessageEvent) => {
-      this.handleRawMessage(event.data);
-    };
-  }
-}
-
-export class WsWebSocketTransport extends AbstractTransport {
-  private socket: ws.WebSocket;
-
-  constructor(socket: ws.WebSocket) {
-    super();
-    this.socket = socket;
-    this.registerEventListeners();
-  }
-
-  public send(message: RosbridgeMessage): void {
-    this.socket.send(JSON.stringify(message));
-  }
-
-  public close(): void {
-    this.socket.close();
-  }
-
-  public isConnecting(): boolean {
-    return this.socket.readyState === ws.WebSocket.CONNECTING;
-  }
-
-  public isOpen(): boolean {
-    return this.socket.readyState === ws.WebSocket.OPEN;
-  }
-
-  public isClosing(): boolean {
-    return this.socket.readyState === ws.WebSocket.CLOSING;
-  }
-
-  public isClosed(): boolean {
-    return this.socket.readyState === ws.WebSocket.CLOSED;
-  }
-
-  private registerEventListeners(): void {
-    this.socket.onopen = (event: ws.Event) => {
-      this.emit("open", event);
-    };
-
-    this.socket.onclose = (event: ws.CloseEvent) => {
-      this.emit("close", event);
-    };
-
-    this.socket.onerror = (event: ws.ErrorEvent) => {
-      this.emit("error", event);
-    };
-
-    this.socket.onmessage = (event: ws.MessageEvent) => {
-      this.handleRawMessage(event.data);
-    };
-  }
-}
-
-/**
- * A transport factory that uses WebSockets to send and receive messages.
- * Will use the native `WebSocket` class if available, otherwise falls back
- * to the `ws` package.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
- * @see https://github.com/websockets/ws
- */
-export const WebSocketTransportFactory: ITransportFactory = async (
-  url: string,
-): Promise<ITransport> => {
-  // Browsers, Deno, Bun, and Node 22+ support WebSockets natively
-  if (typeof WebSocket === "function") {
-    const socket = new WebSocket(url);
-    socket.binaryType = "arraybuffer";
-    return new NativeWebSocketTransport(socket);
-  }
-
-  // If in Node.js, import ws to replace WebSocket API
-  const ws = await import("ws");
-  const socket = new ws.WebSocket(url);
-  socket.binaryType = "arraybuffer";
-  return new WsWebSocketTransport(socket);
-};

src/core/transport/WebSocketTransportFactory.ts

@@ -0,0 +1,30 @@
+import type { ITransport, ITransportFactory } from "./Transport.js";
+import { NativeWebSocketTransport } from "./NativeWebSocketTransport.js";
+
+/**
+ * A transport factory that uses WebSockets to send and receive messages.
+ * Will use the native `WebSocket` class if available, otherwise falls back
+ * to the `ws` package.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
+ * @see https://github.com/websockets/ws
+ */
+export const WebSocketTransportFactory: ITransportFactory = async (
+  url: string,
+): Promise<ITransport> => {
+  // Browsers, Deno, Bun, and Node 22+ support WebSockets natively
+  if (typeof WebSocket === "function") {
+    const socket = new WebSocket(url);
+    socket.binaryType = "arraybuffer";
+    return new NativeWebSocketTransport(socket);
+  }
+
+  // If in Node.js, import ws to replace WebSocket API
+  // Dynamically import the dependencies as they may not
+  // be available in a browser environment.
+  const ws = await import("ws");
+  const { WsWebSocketTransport } = await import("./WsWebSocketTransport.js");
+  const socket = new ws.WebSocket(url);
+  socket.binaryType = "arraybuffer";
+  return new WsWebSocketTransport(socket);
+};

src/core/transport/WsWebSocketTransport.ts

@@ -0,0 +1,60 @@
+import * as ws from "ws";
+import type { RosbridgeMessage } from "../../types/protocol.js";
+import { AbstractTransport } from "./Transport.js";
+
+/**
+ * Uses the `ws` package to send and receive messages.
+ *
+ * @see https://github.com/websockets/ws
+ */
+export class WsWebSocketTransport extends AbstractTransport {
+  private socket: ws.WebSocket;
+
+  constructor(socket: ws.WebSocket) {
+    super();
+    this.socket = socket;
+    this.registerEventListeners();
+  }
+
+  public send(message: RosbridgeMessage): void {
+    this.socket.send(JSON.stringify(message));
+  }
+
+  public close(): void {
+    this.socket.close();
+  }
+
+  public isConnecting(): boolean {
+    return this.socket.readyState === ws.WebSocket.CONNECTING;
+  }
+
+  public isOpen(): boolean {
+    return this.socket.readyState === ws.WebSocket.OPEN;
+  }
+
+  public isClosing(): boolean {
+    return this.socket.readyState === ws.WebSocket.CLOSING;
+  }
+
+  public isClosed(): boolean {
+    return this.socket.readyState === ws.WebSocket.CLOSED;
+  }
+
+  private registerEventListeners(): void {
+    this.socket.onopen = (event: ws.Event) => {
+      this.emit("open", event);
+    };
+
+    this.socket.onclose = (event: ws.CloseEvent) => {
+      this.emit("close", event);
+    };
+
+    this.socket.onerror = (event: ws.ErrorEvent) => {
+      this.emit("error", event);
+    };
+
+    this.socket.onmessage = (event: ws.MessageEvent) => {
+      this.handleRawMessage(event.data);
+    };
+  }
+}

test/ros.test.ts

@@ -5,8 +5,8 @@ import type {
   ITransport,
   ITransportFactory,
   TransportEvent,
-} from "../src/core/Transport.js";
-import { WebSocketTransportFactory } from "../src/core/Transport.js";
+} from "../src/core/transport/Transport.js";
+import { WebSocketTransportFactory } from "../src/core/transport/WebSocketTransportFactory.js";
 import Ros from "../src/core/Ros.js";
 import type { RosbridgeMessage } from "../src/types/protocol.js";