Adding warning regarding imports and updated to the latest beta for improved usage of const enums

accessory-example-typescript/package-lock.json

@@ -237,9 +237,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -273,14 +273,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

accessory-example-typescript/package.json

@@ -33,6 +33,6 @@
     "@types/node": "10.17.19",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

accessory-example-typescript/src/accessory.ts

@@ -2,6 +2,7 @@ import {
   AccessoryConfig,
   AccessoryPlugin,
   API,
+  CharacteristicEventTypes,
   CharacteristicGetCallback,
   CharacteristicSetCallback,
   CharacteristicValue,
@@ -10,8 +11,27 @@ import {
   Service
 } from "homebridge";
 
-/**
- * TODO explain
+/*
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 
@@ -38,11 +58,11 @@ class ExampleSwitch implements AccessoryPlugin {
 
     this.switchService = new hap.Service.Switch(this.name);
     this.switchService.getCharacteristic(hap.Characteristic.On)
-      .on(hap.CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
+      .on(CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
         log.info("Current state of the switch was returned: " + (this.switchOn? "ON": "OFF"));
         callback(undefined, this.switchOn);
       })
-      .on(hap.CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
+      .on(CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
         this.switchOn = value as boolean;
         log.info("Switch state was set to: " + (this.switchOn? "ON": "OFF"));
         callback();