Added connection-specific interfaces and factory functions for exporting instead

.gitignore

@@ -11,7 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
-docs
+docs/build
 
 # Editor directories and files
 .vscode/*

README.md

@@ -1,6 +1,6 @@
 # micro:bit connection library
 
-[This documentation is best viewed on the documentation site rather than GitHub](https://microbit-foundation.github.io/microbit-connection/).
+<a href="https://microbit-foundation.github.io/microbit-connection/" class="typedoc-ignore">This documentation is best viewed on the documentation site rather than GitHub or NPM package site.</a>
 
 This is a JavaScript library for micro:bit connections in browsers via USB and Bluetooth.
 
@@ -18,12 +18,12 @@ This project is a work in progress. We are extracting WebUSB and Web Bluetooth c
 
 ### Flash a micro:bit
 
-Instantiate a WebUSB connection using {@link MicrobitWebUSBConnection} class and use it to connect to a micro:bit.
+Instantiate a WebUSB connection using {@link createWebUSBConnection} class and use it to connect to a micro:bit.
 
 ```ts
-import { MicrobitWebUSBConnection } from "@microbit/microbit-connection";
+import { createWebUSBConnection } from "@microbit/microbit-connection";
 
-const usb = new MicrobitWebUSBConnection();
+const usb = createWebUSBConnection();
 const connectionStatus = await usb.connect();
 
 console.log("Connection status: ", connectionStatus);
@@ -80,20 +80,20 @@ For more examples of using other methods in the {@link MicrobitWebUSBConnection}
 
 By default, the micro:bit's Bluetooth service is not enabled. Visit our [Bluetooth tech site page](https://tech.microbit.org/bluetooth/) to download a hex file that would enable the bluetooth service.
 
-Instantiate a Bluetooth connection using {@link MicrobitWebBluetoothConnection} class and use it to connect to a micro:bit.
+Instantiate a Bluetooth connection using {@link createWebBluetoothConnection} class and use it to connect to a micro:bit.
 
 ```ts
-import { MicrobitWebBluetoothConnection } from "@microbit/microbit-connection";
+import { createWebBluetoothConnection } from "@microbit/microbit-connection";
 
-const bluetooth = new MicrobitWebBluetoothConnection();
+const bluetooth = createWebBluetoothConnection();
 const connectionStatus = await bluetooth.connect();
 
 console.log("Connection status: ", connectionStatus);
 ```
 
 {@link ConnectionStatus | Connection status} is `"CONNECTED"` if connection succeeds.
 
-For more examples of using other methods in the {@link MicrobitWebBluetoothConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
+For more examples of using other methods in the {@link createWebBluetoothConnection} class, see our [demo code](https://github.com/microbit-foundation/microbit-connection/blob/main/src/demo.ts) for our [demo site](https://microbit-connection.pages.dev/).
 
 ## License
 

docs/custom.css

@@ -0,0 +1,4 @@
+/* Styling for hiding elements in the generated TypeDoc site. */
+a.typedoc-ignore {
+  display: none;
+}

lib/bluetooth.ts

@@ -33,12 +33,126 @@ export interface MicrobitWebBluetoothConnectionOptions {
   logging?: Logging;
 }
 
+export interface MicrobitWebBluetoothConnection
+  extends DeviceConnection<ServiceConnectionEventMap> {
+  /**
+   * Sets micro:bit name filter for device requesting.
+   *
+   * @param name The name of the micro:bit.
+   */
+  setNameFilter(name: string): void;
+
+  /**
+   * Gets micro:bit accelerometer data.
+   *
+   * @returns accelerometer data or undefined if there is no connection.
+   */
+  getAccelerometerData(): Promise<AccelerometerData | undefined>;
+
+  /**
+   * Gets micro:bit accelerometer period.
+   *
+   * @returns accelerometer period or undefined if there is no connection.
+   */
+  getAccelerometerPeriod(): Promise<number | undefined>;
+
+  /**
+   * Sets micro:bit accelerometer period.
+   *
+   * @param value The accelerometer period.
+   */
+  setAccelerometerPeriod(value: number): Promise<void>;
+
+  /**
+   * Sets micro:bit LED text.
+   *
+   * @param text The text displayed on micro:bit LED.
+   */
+  setLedText(text: string): Promise<void>;
+
+  /**
+   * Gets micro:bit LED scrolling delay.
+   *
+   * @returns LED scrolling delay in milliseconds.
+   */
+  getLedScrollingDelay(): Promise<number | undefined>;
+
+  /**
+   * Sets micro:bit LED scrolling delay.
+   *
+   * @param delayInMillis LED scrolling delay in milliseconds.
+   */
+  setLedScrollingDelay(delayInMillis: number): Promise<void>;
+
+  /**
+   * Gets micro:bit LED matrix.
+   *
+   * @returns a boolean matrix representing the micro:bit LED display.
+   */
+  getLedMatrix(): Promise<LedMatrix | undefined>;
+
+  /**
+   * Sets micro:bit LED matrix.
+   *
+   * @param matrix an boolean matrix representing the micro:bit LED display.
+   */
+  setLedMatrix(matrix: LedMatrix): Promise<void>;
+
+  /**
+   * Gets micro:bit magnetometer data.
+   *
+   * @returns magnetometer data.
+   */
+  getMagnetometerData(): Promise<MagnetometerData | undefined>;
+
+  /**
+   * Gets micro:bit magnetometer bearing.
+   *
+   * @returns magnetometer bearing.
+   */
+  getMagnetometerBearing(): Promise<number | undefined>;
+
+  /**
+   * Gets micro:bit magnetometer period.
+   *
+   * @returns magnetometer period.
+   */
+  getMagnetometerPeriod(): Promise<number | undefined>;
+
+  /**
+   * Sets micro:bit magnetometer period.
+   *
+   * @param value magnetometer period.
+   */
+  setMagnetometerPeriod(value: number): Promise<void>;
+
+  /**
+   * Triggers micro:bit magnetometer calibration.
+   */
+  triggerMagnetometerCalibration(): Promise<void>;
+
+  /**
+   * Write UART messages.
+   *
+   * @param data UART message.
+   */
+  writeUART(data: Uint8Array): Promise<void>;
+}
+
+/**
+ * A Bluetooth connection factory.
+ */
+export const createWebBluetoothConnection = (
+  options?: MicrobitWebBluetoothConnectionOptions,
+): MicrobitWebBluetoothConnection =>
+  new MicrobitWebBluetoothConnectionImpl(options);
+
 /**
  * A Bluetooth connection to a micro:bit device.
  */
-export class MicrobitWebBluetoothConnection
+class MicrobitWebBluetoothConnectionImpl
   extends TypedEventTarget<DeviceConnectionEventMap & ServiceConnectionEventMap>
-  implements DeviceConnection
+  implements MicrobitWebBluetoothConnection
 {
   status: ConnectionStatus = ConnectionStatus.SUPPORT_NOT_KNOWN;
 

lib/device.ts

@@ -3,8 +3,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-import { TypedEventTarget } from "./events.js";
-import { UARTDataEvent } from "./uart.js";
+import { TypedEventTarget, ValueIsEvent } from "./events.js";
 
 /**
  * Specific identified error types.
@@ -134,30 +133,6 @@ export class ConnectionStatusEvent extends Event {
   }
 }
 
-export class SerialDataEvent extends Event {
-  constructor(public readonly data: string) {
-    super("serialdata");
-  }
-}
-
-export class SerialResetEvent extends Event {
-  constructor() {
-    super("serialreset");
-  }
-}
-
-export class SerialErrorEvent extends Event {
-  constructor(public readonly error: unknown) {
-    super("serialerror");
-  }
-}
-
-export class FlashEvent extends Event {
-  constructor() {
-    super("flash");
-  }
-}
-
 export class BeforeRequestDevice extends Event {
   constructor() {
     super("beforerequestdevice");
@@ -178,18 +153,13 @@ export class BackgroundErrorEvent extends Event {
 
 export class DeviceConnectionEventMap {
   "status": ConnectionStatusEvent;
-  "serialdata": SerialDataEvent;
-  "serialreset": Event;
-  "serialerror": SerialErrorEvent;
-  "uartdata": UARTDataEvent;
-  "flash": Event;
+  "backgrounderror": BackgroundErrorEvent;
   "beforerequestdevice": Event;
   "afterrequestdevice": Event;
-  "backgrounderror": BackgroundErrorEvent;
 }
 
-export interface DeviceConnection
-  extends TypedEventTarget<DeviceConnectionEventMap> {
+export interface DeviceConnection<M extends ValueIsEvent<M>>
+  extends TypedEventTarget<DeviceConnectionEventMap & M> {
   status: ConnectionStatus;
 
   /**
@@ -212,18 +182,10 @@ export interface DeviceConnection
   /**
    * Get the board version.
    *
-   * @returns the board version or null if there is no connection.
+   * @returns the board version or undefined if there is no connection.
    */
   getBoardVersion(): BoardVersion | undefined;
 
-  /**
-   * Flash the micro:bit.
-   *
-   * @param dataSource The data to use.
-   * @param options Flash options and progress callback.
-   */
-  flash?(dataSource: FlashDataSource, options: {}): Promise<void>;
-
   /**
    * Disconnect from the device.
    */
@@ -232,7 +194,7 @@ export interface DeviceConnection
   /**
    * Write serial data to the device.
    *
-   * Does nothting if there is no connection.
+   * Does nothing if there is no connection.
    *
    * @param data The data to write.
    * @returns A promise that resolves when the write is complete.
@@ -242,5 +204,5 @@ export interface DeviceConnection
   /**
    * Clear device to enable chooseDevice.
    */
-  clearDevice(): void;
+  clearDevice(): Promise<void> | void;
 }

lib/events.ts

@@ -40,7 +40,7 @@ export type TypedEventListenerOrEventListenerObject<M, T extends keyof M> =
   | TypedEventListener<M, T>
   | TypedEventListenerObject<M, T>;
 
-type ValueIsEvent<T> = {
+export type ValueIsEvent<T> = {
   [key in keyof T]: Event;
 };
 

lib/index.ts

@@ -1,5 +1,6 @@
 import { AccelerometerData, AccelerometerDataEvent } from "./accelerometer.js";
 import {
+  createWebBluetoothConnection,
   MicrobitWebBluetoothConnection,
   MicrobitWebBluetoothConnectionOptions,
 } from "./bluetooth.js";
@@ -18,24 +19,29 @@ import {
   DeviceErrorCode,
   FlashDataError,
   FlashDataSource,
-  FlashEvent,
   FlashOptions,
-  SerialDataEvent,
-  SerialErrorEvent,
-  SerialResetEvent,
 } from "./device.js";
 import { TypedEventTarget } from "./events.js";
 import { createUniversalHexFlashDataSource } from "./hex-flash-data-source.js";
 import { LedMatrix } from "./led.js";
 import { Logging, LoggingEvent } from "./logging.js";
 import { MagnetometerData, MagnetometerDataEvent } from "./magnetometer.js";
+import {
+  FlashEvent,
+  SerialConnectionEventMap,
+  SerialDataEvent,
+  SerialErrorEvent,
+  SerialResetEvent,
+} from "./serial-events.js";
 import { ServiceConnectionEventMap } from "./service-events.js";
 import { UARTDataEvent } from "./uart.js";
 import {
+  createRadioBridgeConnection,
   MicrobitRadioBridgeConnection,
   MicrobitRadioBridgeConnectionOptions,
 } from "./usb-radio-bridge.js";
 import {
+  createWebUSBConnection,
   MicrobitWebUSBConnection,
   MicrobitWebUSBConnectionOptions,
 } from "./usb.js";
@@ -47,14 +53,15 @@ export {
   BoardId,
   ConnectionStatus,
   ConnectionStatusEvent,
+  createRadioBridgeConnection,
   createUniversalHexFlashDataSource,
+  createWebBluetoothConnection,
+  createWebUSBConnection,
   DeviceConnectionEventMap,
   DeviceError,
   FlashDataError,
   FlashEvent,
-  MicrobitRadioBridgeConnection,
-  MicrobitWebBluetoothConnection,
-  MicrobitWebUSBConnection,
+  SerialConnectionEventMap,
   SerialDataEvent,
   SerialErrorEvent,
   SerialResetEvent,
@@ -79,7 +86,10 @@ export type {
   LoggingEvent,
   MagnetometerData,
   MagnetometerDataEvent,
+  MicrobitRadioBridgeConnection,
   MicrobitRadioBridgeConnectionOptions,
+  MicrobitWebBluetoothConnection,
   MicrobitWebBluetoothConnectionOptions,
+  MicrobitWebUSBConnection,
   MicrobitWebUSBConnectionOptions,
 };