Send previous status in connection events (#74)

This is trivial for the connections and saves apps from additional state
management as they often need to understand which transition happened.

Author: microbit-matt-hillsdon

lib/bluetooth.test.ts

@@ -0,0 +1,101 @@
+/**
+ * (c) 2021, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ConnectionStatus, ConnectionStatusEvent } from "./device.js";
+import { createWebBluetoothConnection } from "./bluetooth.js";
+import { expect, vi, describe, it } from "vitest";
+
+// Mock Capacitor
+vi.mock("@capacitor/core", () => ({
+  Capacitor: {
+    isNativePlatform: () => false,
+    getPlatform: () => "web",
+  },
+}));
+
+// Mock BleClient
+vi.mock("@capacitor-community/bluetooth-le", () => ({
+  BleClient: {
+    initialize: vi.fn().mockResolvedValue(undefined),
+    isEnabled: vi.fn().mockResolvedValue(true),
+    requestDevice: vi.fn(),
+    connect: vi.fn(),
+    disconnect: vi.fn().mockResolvedValue(undefined),
+    getServices: vi.fn().mockResolvedValue([]),
+  },
+}));
+
+// Mock flashing modules
+vi.mock("./flashing/flashing-partial.js", () => ({
+  default: vi.fn(),
+  PartialFlashResult: { AttemptFullFlash: "AttemptFullFlash" },
+}));
+
+vi.mock("./flashing/flashing-full.js", () => ({
+  fullFlash: vi.fn(),
+}));
+
+const setupNavigatorMock = () => {
+  Object.defineProperty(globalThis, "navigator", {
+    value: {
+      bluetooth: {
+        getAvailability: vi.fn().mockResolvedValue(true),
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        requestDevice: vi.fn(),
+      },
+    },
+    writable: true,
+    configurable: true,
+  });
+};
+
+describe("Bluetooth connection status events", () => {
+  it("emits status events with correct previousStatus", async () => {
+    setupNavigatorMock();
+    const connection = createWebBluetoothConnection();
+    await connection.initialize();
+
+    expect(connection.status).toBe(ConnectionStatus.NO_AUTHORIZED_DEVICE);
+
+    const events: ConnectionStatusEvent[] = [];
+    connection.addEventListener("status", (e) => {
+      events.push(e);
+    });
+
+    await connection.disconnect();
+
+    expect(events).toHaveLength(1);
+    expect(events[0].status).toBe(ConnectionStatus.DISCONNECTED);
+    expect(events[0].previousStatus).toBe(
+      ConnectionStatus.NO_AUTHORIZED_DEVICE,
+    );
+  });
+
+  it("defers status updates during flash, emitting single catch-up event", async () => {
+    setupNavigatorMock();
+    const connection = createWebBluetoothConnection();
+    await connection.initialize();
+
+    const statusBeforeFlash = connection.status;
+    expect(statusBeforeFlash).toBe(ConnectionStatus.NO_AUTHORIZED_DEVICE);
+
+    const events: ConnectionStatusEvent[] = [];
+    connection.addEventListener("status", (e) => {
+      events.push(e);
+    });
+
+    // flash() will fail but the finally block still emits a catch-up event
+    try {
+      await connection.flash(async () => "mock-hex-data", {});
+    } catch {
+      // Expected to fail
+    }
+
+    // Should have exactly one catch-up event with correct previousStatus
+    expect(events).toHaveLength(1);
+    expect(events[0].previousStatus).toBe(statusBeforeFlash);
+  });
+});

lib/bluetooth.ts

@@ -196,7 +196,7 @@ class MicrobitWebBluetoothConnectionImpl
   private connection: BluetoothDeviceWrapper | undefined;
 
   private nameFilter: string | undefined;
-  private deferStatusUpdates: boolean = false;
+  private deferredUpdatesPreviousStatus: ConnectionStatus | undefined;
 
   constructor(options: MicrobitWebBluetoothConnectionOptions = {}) {
     super();
@@ -345,10 +345,14 @@ class MicrobitWebBluetoothConnectionImpl
   }
 
   private setStatus(newStatus: ConnectionStatus) {
+    const previousStatus = this.status;
     this.status = newStatus;
     this.log("Bluetooth connection status " + newStatus);
-    if (!this.deferStatusUpdates) {
-      this.dispatchTypedEvent("status", new ConnectionStatusEvent(newStatus));
+    if (this.deferredUpdatesPreviousStatus === undefined) {
+      this.dispatchTypedEvent(
+        "status",
+        new ConnectionStatusEvent(newStatus, previousStatus),
+      );
     }
   }
 
@@ -470,7 +474,7 @@ class MicrobitWebBluetoothConnectionImpl
     const progress: ProgressCallback = options.progress ?? (() => {});
     try {
       // We'll disconnect/reconnect multiple times due to device resets, but reporting this is unhelpful.
-      this.deferStatusUpdates = true;
+      this.deferredUpdatesPreviousStatus = this.status;
 
       if (this.status !== ConnectionStatus.CONNECTED) {
         await this.connect({ progress });
@@ -516,8 +520,12 @@ class MicrobitWebBluetoothConnectionImpl
         await this.disconnect();
       }
     } finally {
-      this.deferStatusUpdates = false;
-      this.dispatchTypedEvent("status", new ConnectionStatusEvent(this.status));
+      const previousStatus = this.deferredUpdatesPreviousStatus!;
+      this.deferredUpdatesPreviousStatus = undefined;
+      this.dispatchTypedEvent(
+        "status",
+        new ConnectionStatusEvent(this.status, previousStatus),
+      );
     }
   }
 

lib/device.ts

@@ -213,7 +213,10 @@ export type FlashDataSource = (
 export type BoardVersion = "V1" | "V2";
 
 export class ConnectionStatusEvent extends Event {
-  constructor(public readonly status: ConnectionStatus) {
+  constructor(
+    public readonly status: ConnectionStatus,
+    public readonly previousStatus: ConnectionStatus,
+  ) {
     super("status");
   }
 }

lib/usb-radio-bridge.ts

@@ -234,10 +234,14 @@ class MicrobitRadioBridgeConnectionImpl
     this.logging.log(v);
   }
 
-  private setStatus(status: ConnectionStatus) {
-    this.status = status;
-    this.log("Radio connection status " + status);
-    this.dispatchTypedEvent("status", new ConnectionStatusEvent(status));
+  private setStatus(newStatus: ConnectionStatus) {
+    const previousStatus = this.status;
+    this.status = newStatus;
+    this.log("Radio connection status " + newStatus);
+    this.dispatchTypedEvent(
+      "status",
+      new ConnectionStatusEvent(newStatus, previousStatus),
+    );
   }
 
   private statusFromDelegate(): ConnectionStatus {

lib/usb.ts

@@ -422,9 +422,13 @@ class MicrobitWebUSBConnectionImpl
   }
 
   private setStatus(newStatus: ConnectionStatus) {
+    const previousStatus = this.status;
     this.status = newStatus;
     this.log("USB connection status " + newStatus);
-    this.dispatchTypedEvent("status", new ConnectionStatusEvent(newStatus));
+    this.dispatchTypedEvent(
+      "status",
+      new ConnectionStatusEvent(newStatus, previousStatus),
+    );
   }
 
   private async withEnrichedErrors<T>(f: () => Promise<T>): Promise<T> {