feat: change the API of findDevice to return null if no device is f…

…ound, rather than throwing an error

BREAKING CHANGE: This refactors the API of the `findDevice`
function to return `null` rather than throwing an error if a
Logitech Litra Glow device cannot be found attached to the
computer. If you're using this function, you should update any
call sites so they don't assume that a device has been returned -
for example with an `if (device)` `null` check.

README.md

@@ -34,15 +34,21 @@ npm install --save litra-glow
 
 The `findDevice` function checks your computer to find whether a Logitech Litra Glow is plugged in. 
 
-If it is, an object representing the device is returned, which you can pass into other function. If it isn't, an error is thrown.
+If it is, it returns an object representing the device, which you can pass into other function. If it isn't, it returns `null`.
 
 ```js
 import { findDevice } from 'litra-glow';
 
 const device = findDevice();
+
+if (device) {
+  // Do something
+} else {
+  // Blow up
+}
 ```
 
-If you're a *huge* fan of the Litra Glow and you have multipled plugged in at the same time, it'll return whatever one it happens to find first.
+If you're a *huge* fan of the Litra Glow and you have multiple plugged in at the same time, it'll return whatever one it happens to find first.
 
 #### Turning your Litra Glow on or off
 
@@ -54,8 +60,10 @@ import { findDevice, turnOff, turnOn } from 'litra-glow';
 const device = findDevice();
 
 // Turn your light on, then turn it off again after 5 seconds
-turnOn(device);
-setTimeout(() => turnOff(device), 5000));
+if (device) {
+  turnOn(device);
+  setTimeout(() => turnOff(device), 5000));
+}
 ```
 
 #### Setting the brightness of your Litra Glow
@@ -67,7 +75,9 @@ import { findDevice, setBrightnessInLumen } from 'litra-glow';
 
 const device = findDevice();
 
-setBrightnessInLumen(device, 150);
+if (device) {
+  setBrightnessInLumen(device, 150);
+}
 ```
 
 You can also set brightness level to a percentage with `setBrightnessPercentage` if you don't want to think in Lumen:
@@ -77,7 +87,9 @@ import { findDevice, setBrightnessPercentage } from 'litra-glow';
 
 const device = findDevice();
 
-setBrightnessPercentage(device, 75);
+if (device) {
+  setBrightnessPercentage(device, 75);
+}
 ```
 
 #### Setting the temperature of your Litra Glow
@@ -89,7 +101,9 @@ import { findDevice, setTemperatureInKelvin } from 'litra-glow';
 
 const device = findDevice();
 
-setTemperatureInKelvin(device, 4500);
+if (device) {
+  setTemperatureInKelvin(device, 4500);
+}
 ```
 
 You can also set brightness level to a percentage with `setTemperaturePercentage` if you don't want to think in Lumen:
@@ -99,5 +113,7 @@ import { findDevice, setTemperaturePercentage } from 'litra-glow';
 
 const device = findDevice();
 
-setTemperaturePercentage(device, 75);
+if (device) {
+  setTemperaturePercentage(device, 75);
+}
 ```

dist/commonjs/cli/litra-off.js

@@ -4,7 +4,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const driver_1 = require("./../driver");
 try {
     const device = (0, driver_1.findDevice)();
-    (0, driver_1.turnOff)(device);
+    if (device) {
+        (0, driver_1.turnOff)(device);
+    }
+    else {
+        throw 'Device not found';
+    }
     process.exit(0);
 }
 catch (e) {

dist/commonjs/cli/litra-on.js

@@ -4,7 +4,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const driver_1 = require("./../driver");
 try {
     const device = (0, driver_1.findDevice)();
-    (0, driver_1.turnOn)(device);
+    if (device) {
+        (0, driver_1.turnOn)(device);
+    }
+    else {
+        throw 'Device not found';
+    }
     process.exit(0);
 }
 catch (e) {

dist/commonjs/driver.d.ts

@@ -3,15 +3,15 @@ export interface Device {
     write: (values: number[] | Buffer) => number;
 }
 /**
- * Finds your Logitech Litra Glow device and returns it. Throws an
- * error if a matching device cannot be found connected to your
- * computer.
+ * Finds your Logitech Litra Glow device and returns it. Returns `null`
+ * if a matching device cannot be found connected to your computer.
  *
- * @returns {Device} An object representing your Logitech Litra Glow
- * device, passed into other functions like `turnOn` and
- * `setTemperatureInKelvin`
+ * @returns {Device, null} An object representing your Logitech Litra
+ * Glow device, passed into other functions like `turnOn` and
+ * `setTemperatureInKelvin` - or `null` if a matching device cannot be
+ * found connected to your computer.
  */
-export declare const findDevice: () => Device;
+export declare const findDevice: () => Device | null;
 /**
  * Turns your Logitech Litra Glow device on.
  *

dist/commonjs/driver.js

@@ -10,13 +10,13 @@ const VENDOR_ID = 0x046d;
 const PRODUCT_ID = 0xc900;
 const USAGE_PAGE = 0xff43;
 /**
- * Finds your Logitech Litra Glow device and returns it. Throws an
- * error if a matching device cannot be found connected to your
- * computer.
+ * Finds your Logitech Litra Glow device and returns it. Returns `null`
+ * if a matching device cannot be found connected to your computer.
  *
- * @returns {Device} An object representing your Logitech Litra Glow
- * device, passed into other functions like `turnOn` and
- * `setTemperatureInKelvin`
+ * @returns {Device, null} An object representing your Logitech Litra
+ * Glow device, passed into other functions like `turnOn` and
+ * `setTemperatureInKelvin` - or `null` if a matching device cannot be
+ * found connected to your computer.
  */
 const findDevice = () => {
     const matchingDevice = node_hid_1.default.devices().find((device) => device.vendorId === VENDOR_ID &&
@@ -26,7 +26,7 @@ const findDevice = () => {
         return new node_hid_1.default.HID(matchingDevice.path);
     }
     else {
-        throw 'Device not found';
+        return null;
     }
 };
 exports.findDevice = findDevice;

dist/esm/cli/litra-off.js

@@ -2,7 +2,12 @@
 import { findDevice, turnOff } from './../driver';
 try {
     const device = findDevice();
-    turnOff(device);
+    if (device) {
+        turnOff(device);
+    }
+    else {
+        throw 'Device not found';
+    }
     process.exit(0);
 }
 catch (e) {

dist/esm/cli/litra-on.js

@@ -2,7 +2,12 @@
 import { findDevice, turnOn } from './../driver';
 try {
     const device = findDevice();
-    turnOn(device);
+    if (device) {
+        turnOn(device);
+    }
+    else {
+        throw 'Device not found';
+    }
     process.exit(0);
 }
 catch (e) {

dist/esm/driver.d.ts

@@ -3,15 +3,15 @@ export interface Device {
     write: (values: number[] | Buffer) => number;
 }
 /**
- * Finds your Logitech Litra Glow device and returns it. Throws an
- * error if a matching device cannot be found connected to your
- * computer.
+ * Finds your Logitech Litra Glow device and returns it. Returns `null`
+ * if a matching device cannot be found connected to your computer.
  *
- * @returns {Device} An object representing your Logitech Litra Glow
- * device, passed into other functions like `turnOn` and
- * `setTemperatureInKelvin`
+ * @returns {Device, null} An object representing your Logitech Litra
+ * Glow device, passed into other functions like `turnOn` and
+ * `setTemperatureInKelvin` - or `null` if a matching device cannot be
+ * found connected to your computer.
  */
-export declare const findDevice: () => Device;
+export declare const findDevice: () => Device | null;
 /**
  * Turns your Logitech Litra Glow device on.
  *

dist/esm/driver.js

@@ -4,13 +4,13 @@ const VENDOR_ID = 0x046d;
 const PRODUCT_ID = 0xc900;
 const USAGE_PAGE = 0xff43;
 /**
- * Finds your Logitech Litra Glow device and returns it. Throws an
- * error if a matching device cannot be found connected to your
- * computer.
+ * Finds your Logitech Litra Glow device and returns it. Returns `null`
+ * if a matching device cannot be found connected to your computer.
  *
- * @returns {Device} An object representing your Logitech Litra Glow
- * device, passed into other functions like `turnOn` and
- * `setTemperatureInKelvin`
+ * @returns {Device, null} An object representing your Logitech Litra
+ * Glow device, passed into other functions like `turnOn` and
+ * `setTemperatureInKelvin` - or `null` if a matching device cannot be
+ * found connected to your computer.
  */
 export const findDevice = () => {
     const matchingDevice = HID.devices().find((device) => device.vendorId === VENDOR_ID &&
@@ -20,7 +20,7 @@ export const findDevice = () => {
         return new HID.HID(matchingDevice.path);
     }
     else {
-        throw 'Device not found';
+        return null;
     }
 };
 /**

src/cli/litra-off.ts

@@ -4,7 +4,13 @@ import { findDevice, turnOff } from './../driver';
 
 try {
   const device = findDevice();
-  turnOff(device);
+
+  if (device) {
+    turnOff(device);
+  } else {
+    throw 'Device not found';
+  }
+
   process.exit(0);
 } catch (e) {
   console.log(e);

src/cli/litra-on.ts

@@ -4,7 +4,13 @@ import { findDevice, turnOn } from './../driver';
 
 try {
   const device = findDevice();
-  turnOn(device);
+
+  if (device) {
+    turnOn(device);
+  } else {
+    throw 'Device not found';
+  }
+
   process.exit(0);
 } catch (e) {
   console.log(e);

src/driver.ts

@@ -12,15 +12,15 @@ export interface Device {
 }
 
 /**
- * Finds your Logitech Litra Glow device and returns it. Throws an
- * error if a matching device cannot be found connected to your
- * computer.
+ * Finds your Logitech Litra Glow device and returns it. Returns `null`
+ * if a matching device cannot be found connected to your computer.
  *
- * @returns {Device} An object representing your Logitech Litra Glow
- * device, passed into other functions like `turnOn` and
- * `setTemperatureInKelvin`
+ * @returns {Device, null} An object representing your Logitech Litra
+ * Glow device, passed into other functions like `turnOn` and
+ * `setTemperatureInKelvin` - or `null` if a matching device cannot be
+ * found connected to your computer.
  */
-export const findDevice = (): Device => {
+export const findDevice = (): Device | null => {
   const matchingDevice = HID.devices().find(
     (device) =>
       device.vendorId === VENDOR_ID &&
@@ -31,7 +31,7 @@ export const findDevice = (): Device => {
   if (matchingDevice) {
     return new HID.HID(matchingDevice.path as string);
   } else {
-    throw 'Device not found';
+    return null;
   }
 };