@hangtime/grip-connect 0.5.8 → 0.5.9

package/src/models/device.model.ts

@@ -187,6 +187,11 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {number} [options.duration=1000] - The duration (in milliseconds) to monitor the input for activity.
    * @returns {void}
    * @public
+   *
+   * @example
+   * device.active((isActive) => {
+   *   console.log(`Device is ${isActive ? 'active' : 'inactive'}`);
+   * }, { threshold: 3.0, duration: 1500 });
    */
   active = (callback: ActiveCallback, options?: { threshold?: number; duration?: number }): void => {
     this.activeCallback = callback
@@ -207,21 +212,35 @@ export abstract class Device extends BaseModel implements IDevice {
    *
    * @param {number} input - The dynamic value to check for activity status.
    * @returns {Promise<void>} A promise that resolves once the activity check is complete.
+   *
+   * @example
+   * await device.activityCheck(5.0);
    */
   protected activityCheck = (input: number): Promise<void> => {
     return new Promise((resolve) => {
-      // Check the activity status after the specified duration
-      setTimeout(() => {
-        // Determine the activity status based on the stored threshold in the config
-        const activeNow = input > this.activeConfig.threshold
-        if (this.isActive !== activeNow) {
-          this.isActive = activeNow
-          if (this.activeCallback) {
-            this.activeCallback(activeNow)
+      const startTime = Date.now()
+      const checkActivity = () => {
+        const currentTime = Date.now()
+        const elapsedTime = currentTime - startTime
+
+        if (elapsedTime >= this.activeConfig.duration) {
+          // Determine the activity status based on the most recent input
+          const activeNow = input > this.activeConfig.threshold
+          if (this.isActive !== activeNow) {
+            this.isActive = activeNow
+            if (this.activeCallback) {
+              this.activeCallback(activeNow)
+            }
           }
+          resolve()
+        } else {
+          // Continue checking until the duration is met
+          requestAnimationFrame(checkActivity)
         }
-        resolve()
-      }, this.activeConfig.duration)
+      }
+
+      // Start the activity check
+      checkActivity()
     })
   }
 
@@ -230,6 +249,12 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {Function} [onSuccess] - Optional callback function to execute on successful connection. Default logs success.
    * @param {Function} [onError] - Optional callback function to execute on error. Default logs the error.
    * @public
+   *
+   * @example
+   * device.connect(
+   *   () => console.log("Connected successfully"),
+   *   (error) => console.error("Connection failed:", error)
+   * );
    */
   connect = async (
     onSuccess: () => void = () => console.log("Connected successfully"),
@@ -264,15 +289,40 @@ export abstract class Device extends BaseModel implements IDevice {
 
   /**
    * Disconnects the device if it is currently connected.
-   * - Checks if the device is connected via it's GATT server.
-   * - If the device is connected, it attempts to gracefully disconnect.
+   * - Removes all notification listeners from the device's characteristics.
+   * - Removes the 'gattserverdisconnected' event listener.
+   * - Attempts to gracefully disconnect the device's GATT server.
+   * - Resets relevant properties to their initial states.
+   * @returns {void}
    * @public
+   *
+   * @example
+   * device.disconnect();
    */
   disconnect = (): void => {
-    // Verify that the device is connected using the provided helper function
     if (this.isConnected()) {
+      // Remove all notification listeners
+      this.services.forEach((service) => {
+        service.characteristics.forEach((char) => {
+          if (char.characteristic && char.id === "rx") {
+            char.characteristic.stopNotifications()
+            char.characteristic.removeEventListener("characteristicvaluechanged", (event: Event) => {
+              const target = event.target as BluetoothRemoteGATTCharacteristic
+              if (target && target.value) {
+                this.handleNotifications(target)
+              }
+            })
+          }
+        })
+      })
+      // Remove disconnect listener
+      this.bluetooth?.removeEventListener("gattserverdisconnected", this.onDisconnected)
       // Safely attempt to disconnect the device's GATT server, if available
       this.bluetooth?.gatt?.disconnect()
+      // Reset properties
+      this.server = undefined
+      this.writeLast = null
+      this.isActive = false
     }
   }
 
@@ -280,9 +330,17 @@ export abstract class Device extends BaseModel implements IDevice {
    * Converts the `downloadPackets` array into a CSV formatted string.
    * @returns {string} A CSV string representation of the `downloadPackets` data, with each packet on a new line.
    * @private
+   *
+   * @example
+   * const csvData = device.downloadToCSV();
+   * console.log(csvData);
    */
   private downloadToCSV = (): string => {
-    return this.downloadPackets
+    const packets = [...this.downloadPackets]
+    if (packets.length === 0) {
+      return ""
+    }
+    return packets
       .map((packet) =>
         [
           packet.received.toString(),
@@ -302,6 +360,10 @@ export abstract class Device extends BaseModel implements IDevice {
    * Converts an array of DownloadPacket objects to a JSON string.
    * @returns {string} JSON string representation of the data.
    * @private
+   *
+   * @example
+   * const jsonData = device.downloadToJSON();
+   * console.log(jsonData);
    */
   private downloadToJSON = (): string => {
     // Pretty print JSON with 2-space indentation
@@ -312,6 +374,10 @@ export abstract class Device extends BaseModel implements IDevice {
    * Converts an array of DownloadPacket objects to an XML string.
    * @returns {string}  XML string representation of the data.
    * @private
+   *
+   * @example
+   * const xmlData = device.downloadToXML();
+   * console.log(xmlData);
    */
   private downloadToXML = (): string => {
     const xmlPackets = this.downloadPackets
@@ -341,6 +407,9 @@ export abstract class Device extends BaseModel implements IDevice {
    *
    * @returns {void} Initiates a download of the data in the specified format.
    * @private
+   *
+   * @example
+   * device.download('json');
    */
   download = (format: "csv" | "json" | "xml" = "csv"): void => {
     let content = ""
@@ -394,9 +463,13 @@ export abstract class Device extends BaseModel implements IDevice {
    * Returns UUIDs of all services associated with the device.
    * @returns {string[]} Array of service UUIDs.
    * @protected
+   *
+   * @example
+   * const serviceUUIDs = device.getAllServiceUUIDs();
+   * console.log(serviceUUIDs);
    */
   protected getAllServiceUUIDs = (): string[] => {
-    return this.services.map((service) => service.uuid)
+    return this.services.filter((service) => service?.uuid).map((service) => service.uuid)
   }
 
   /**
@@ -405,6 +478,12 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {string} characteristicId - The UUID of the characteristic.
    * @returns {BluetoothRemoteGATTCharacteristic | undefined} The characteristic, if found.
    * @protected
+   *
+   * @example
+   * const characteristic = device.getCharacteristic('battery', 'level');
+   * if (characteristic) {
+   *   console.log('Characteristic found');
+   * }
    */
   protected getCharacteristic = (
     serviceId: string,
@@ -428,19 +507,22 @@ export abstract class Device extends BaseModel implements IDevice {
 
   /**
    * Handles notifications received from a characteristic.
-   * @param {Event} event - The notification event.
-   * @protected
+   * @param {BluetoothRemoteGATTCharacteristic} characteristic - The notification event.
+   *
+   * @example
+   * device.handleNotifications(someCharacteristic);
    */
-  protected handleNotifications = (event: Event): void => {
-    const characteristic: BluetoothRemoteGATTCharacteristic = event.target as BluetoothRemoteGATTCharacteristic
-    const value: DataView | undefined = characteristic.value
+  protected handleNotifications = (characteristic: BluetoothRemoteGATTCharacteristic): void => {
+    const value = characteristic.value
 
-    if (value) {
-      if (value.buffer) {
-        console.log(value)
-      } else {
-        console.log(value)
-      }
+    if (!value) {
+      return
+    }
+
+    if (value.buffer) {
+      console.log(value)
+    } else {
+      console.log(value)
     }
   }
 
@@ -448,6 +530,13 @@ export abstract class Device extends BaseModel implements IDevice {
    * Checks if a Bluetooth device is connected.
    * @returns {boolean} A boolean indicating whether the device is connected.
    * @public
+   *
+   * @example
+   * if (device.isConnected()) {
+   *   console.log('Device is connected');
+   * } else {
+   *   console.log('Device is not connected');
+   * }
    */
   isConnected = (): boolean => {
     // Check if the device is defined and available
@@ -463,6 +552,11 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {NotifyCallback} callback - The callback function to be set.
    * @returns {void}
    * @public
+   *
+   * @example
+   * device.notify((data) => {
+   *   console.log('Received notification:', data);
+   * });
    */
   notify = (callback: NotifyCallback): void => {
     this.notifyCallback = callback
@@ -472,10 +566,18 @@ export abstract class Device extends BaseModel implements IDevice {
    * Handles the 'connected' event.
    * @param {Function} onSuccess - Callback function to execute on successful connection.
    * @public
+   *
+   * @example
+   * device.onConnected(() => {
+   *   console.log('Device connected successfully');
+   * });
    */
   protected onConnected = async (onSuccess: () => void): Promise<void> => {
+    if (!this.server) {
+      throw new Error("GATT server is not available")
+    }
     // Connect to GATT server and set up characteristics
-    const services: BluetoothRemoteGATTService[] | undefined = await this.server?.getPrimaryServices()
+    const services: BluetoothRemoteGATTService[] | undefined = await this.server.getPrimaryServices()
 
     if (!services || services.length === 0) {
       throw new Error("No services found")
@@ -502,7 +604,10 @@ export abstract class Device extends BaseModel implements IDevice {
               if (element.id === "rx") {
                 matchingCharacteristic.startNotifications()
                 matchingCharacteristic.addEventListener("characteristicvaluechanged", (event: Event) => {
-                  this.handleNotifications(event)
+                  const target = event.target as BluetoothRemoteGATTCharacteristic
+                  if (target && target.value) {
+                    this.handleNotifications(target)
+                  }
                 })
               }
             }
@@ -521,11 +626,14 @@ export abstract class Device extends BaseModel implements IDevice {
    * Handles the 'disconnected' event.
    * @param {Event} event - The 'disconnected' event.
    * @public
+   *
+   * @example
+   * device.onDisconnected(event);
    */
   protected onDisconnected = (event: Event): void => {
     this.bluetooth = undefined
     const device = event.target as BluetoothDevice
-    throw new Error(`Device ${device.name} is disconnected.`)
+    console.warn(`Device ${device.name} is disconnected.`)
   }
 
   /**
@@ -535,6 +643,10 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {number} [duration=0] - The duration to wait before resolving the promise, in milliseconds.
    * @returns {Promise<string | undefined>} A promise that resolves when the read operation is completed.
    * @public
+   *
+   * @example
+   * const value = await device.read('battery', 'level', 1000);
+   * console.log('Battery level:', value);
    */
   read = async (serviceId: string, characteristicId: string, duration = 0): Promise<string | undefined> => {
     if (!this.isConnected()) {
@@ -572,14 +684,24 @@ export abstract class Device extends BaseModel implements IDevice {
   /**
    * Initiates the tare calibration process.
    * @param {number} duration - The duration time for tare calibration.
-   * @returns {void}
+   * @returns {boolean} A boolean indicating whether the tare calibration was successful.
    * @public
-   */
-  tare(duration = 5000): void {
+   *
+   * @example
+   * const success = device.tare(5000);
+   * if (success) {
+   *   console.log('Tare calibration started');
+   * } else {
+   *   console.log('Tare calibration failed to start');
+   * }
+   */
+  tare(duration = 5000): boolean {
+    if (this.tareActive) return false
     this.tareActive = true
     this.tareDuration = duration
     this.tareSamples = []
     this.tareStartTime = Date.now()
+    return true
   }
 
   /**
@@ -587,6 +709,10 @@ export abstract class Device extends BaseModel implements IDevice {
    * @param {number} sample - The sample to calibrate.
    * @returns {number} The calibrated tare value.
    * @protected
+   *
+   * @example
+   * const calibratedSample = device.applyTare(rawSample);
+   * console.log('Calibrated sample:', calibratedSample);
    */
   protected applyTare(sample: number): number {
     if (this.tareActive && this.tareStartTime) {
@@ -635,7 +761,7 @@ export abstract class Device extends BaseModel implements IDevice {
   ): Promise<void> => {
     // Check if not connected or no message is provided
     if (!this.isConnected() || message === undefined) {
-      return undefined
+      return Promise.resolve()
     }
     // Get the characteristic from the service
     const characteristic = this.getCharacteristic(serviceId, characteristicId)