Import classes from other libs

Author: Cellivar

package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-device-mux",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A small library for managing connections to WebUSB, WebHID, and Web Serial devices from multiple tabs at the same time.",
   "type": "module",
   "repository": {

src/Channel.ts

@@ -0,0 +1,55 @@
+import type { IDeviceInformation } from "./Device.js";
+import type { DeviceCommunicationError } from "./Error.js";
+
+/** Possible ways to communicate with a device */
+export type DeviceChannelType
+  = "USB"
+  | "Serial"
+  | "Bluetooth"
+  | "Network"
+
+/** Whether data can be transmitted or received from the device. */
+export enum ConnectionDirectionMode {
+  none,
+  unidirectional,
+  bidirectional
+}
+
+/** Behavior options when communicating with a device. */
+export interface IDeviceCommunicationOptions {
+  /** Whether to display printer communication to the dev console. */
+  debug: boolean;
+
+  /** Milliseconds to wait for messages from a device before assuming it's done talking. Defaults to 500ms. */
+  messageWaitTimeoutMS?: number
+}
+
+/** A communication channel for talking to a device. */
+export interface IDeviceChannel<TOutput, TInput> {
+  /** Gets the mode the communication is set up as. */
+  get commMode(): ConnectionDirectionMode;
+
+  /** Gets this channel type. */
+  readonly channelType: DeviceChannelType;
+
+  /** A promise indicating this communication channel is ready for use. */
+  get ready(): Promise<boolean>;
+
+  /** Whether the device is connected. */
+  get connected(): boolean;
+
+  /** Close the channel, disallowing future communication. */
+  dispose(): Promise<void>;
+
+  /** Gets the basic information for the device connected on this channel. */
+  getDeviceInfo(): IDeviceInformation
+
+  /**
+   * Send a series of commands to the device.
+   * @param commandBuffer The series of commands to send in order.
+   */
+  sendCommands(commandBuffer: TOutput): Promise<DeviceCommunicationError | undefined>;
+
+  /** Request data from the device. */
+  getInput(): Promise<TInput[] | DeviceCommunicationError>;
+}

src/Device.ts

@@ -0,0 +1,28 @@
+
+/** Interface describing a device that can be connected to. */
+export interface IDevice {
+  /** Close the connection to this device and clean up unmanaged resources. */
+  dispose(): Promise<void>;
+
+  /** Whether the device is connected. */
+  get connected(): boolean;
+
+  /** A promise indicating this device is ready to be used. */
+  ready: Promise<boolean>;
+}
+
+/** An event object corresponding to a particular device. */
+export interface IDeviceEvent<TDevice extends IDevice> {
+  /** The device the event is for. */
+  device: TDevice;
+}
+
+/** Basic metadata about a device, including from before we connect to it. */
+export interface IDeviceInformation {
+  /** A string representing the manufacturer, if available. */
+  readonly manufacturerName?: string | undefined;
+  /** A string representing the device product name, if available. */
+  readonly productName?: string | undefined;
+  /** A string representing the device's unique serial number, if available. */
+  readonly serialNumber?: string | undefined;
+}

src/Error.ts

@@ -0,0 +1,34 @@
+/** Exception thrown from the WebDeviceMux library. */
+export class WebDeviceMuxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/** Error indicating communication with the device could not be initiated. */
+export class DeviceConnectionError extends WebDeviceMuxError {
+  constructor(message?: string, innerException?: Error) {
+    super(message ?? innerException?.message ?? 'Error connecting to device');
+    this.innerException = innerException;
+  }
+
+  innerException?: Error;
+}
+
+/** Error indicating communication with the device failed. */
+export class DeviceCommunicationError extends WebDeviceMuxError {
+  constructor(message?: string, innerException?: Error) {
+    super(message ?? innerException?.message ?? 'Error communicating with device');
+    this.innerException = innerException;
+  }
+
+  innerException?: Error;
+}
+
+/** Error indicating the device was not ready to communicate. */
+export class DeviceNotReadyError extends DeviceCommunicationError {
+  constructor(message?: string, innerException?: Error) {
+    super(message ?? innerException?.message ?? 'Device not ready to communicate.');
+  }
+}

src/InputListener.ts

@@ -0,0 +1,71 @@
+// TODO: Rewrite the entire message handling system as a stream transformer?
+
+import { DeviceCommunicationError } from "./Error.js";
+
+export type DataProvider<TInput> = () => Promise<TInput[] | DeviceCommunicationError>;
+export type InputHandler<TInput> = (input: TInput[]) => IHandlerResponse<TInput>;
+export interface IHandlerResponse<TInput> {
+  remainderData?: TInput[];
+}
+
+export class InputMessageListener<TInput> {
+  public start() {
+    // We intentionally want to kick off an async promise here without needing
+    // the calling function to be async. The promise we're starting is meant to
+    // run forever and never resolve until it's being shut down.
+    // eslint-disable-next-line no-async-promise-executor
+    new Promise<void>(async (_, reject) => {
+      let aggregate: TInput[] = [];
+      do {
+        const data = await this._dataProvider();
+
+        if (data instanceof DeviceCommunicationError) {
+          console.error(`Error getting data from source: `, data);
+          reject(data);
+          break;
+        }
+
+        if (data.length === 0) {
+          continue;
+        }
+
+        aggregate.push(...data);
+        this.logIfDebug(`Got data from provider, now has ${aggregate.length} items in receive buffer. Data: `, data);
+
+        // The handler determines if what we got was sufficient, or if we need more.
+        const handleResult = this._inputHandler(aggregate);
+        if (handleResult.remainderData !== undefined && handleResult.remainderData.length !== 0) {
+          this.logIfDebug(`Input handler provided a ${handleResult.remainderData.length} length incomplete buffer.`);
+        }
+
+        // The handler is not required to be stateful, this is instead.
+        // The handler  may indicate more data is expected by returning incomplete
+        // data back. We prefix our buffer with that incomplete data to add more
+        // to it and wait again for more.
+        aggregate = handleResult.remainderData ?? [];
+      } while (!this._disposed);
+    })
+    .catch((reason) => {
+      // TODO: Better logging?
+      this.logIfDebug(`Device stream listener stopped listening unexpectedly.`, reason);
+    });
+  }
+
+  private _disposed = false;
+  public dispose() {
+    if (this._disposed) { return; }
+    this._disposed = true;
+  }
+
+  constructor(
+    private readonly _dataProvider: DataProvider<TInput>,
+    private readonly _inputHandler: InputHandler<TInput>,
+    private readonly _debugLogging: boolean = true, // TODO: false
+  ) {}
+
+  private logIfDebug(...obj: unknown[]) {
+    if (this._debugLogging) {
+      console.debug(...obj);
+    }
+  }
+}