[items] Allow Item lookup by name directly on the items namespace

CHANGELOG.md

@@ -12,6 +12,7 @@
 | Enhancement | `time`                 | Add isBefore(Date/Time/DateTime) and isAfter(Date/Time/DateTime)                                  | [#227](https://github.com/openhab/openhab-js/pull/227)                                                  | No       |
 | Enhancement | `items`                | ItemHistory: return an object with state and timestamp instead of just state where applicable     | [#228](https://github.com/openhab/openhab-js/pull/228)                                                  | **Yes**  |
 | Enhancement | `items`                | Metadata: Accept Item as param in addition to Item name                                           | [#230](https://github.com/openhab/openhab-js/pull/230)                                                  | No       |
+| Enhancement | `items`                | Allow Item lookup by name directly on the `items` namespace                                       | [#233](https://github.com/openhab/openhab-js/pull/233)                                                  | No       |
 
 Also see the [Release Milestone](https://github.com/openhab/openhab-js/milestone/11).
 

README.md

@@ -110,8 +110,8 @@ You can now write rules using standard ES6 JavaScript along with the included op
 For example, turning a light on:
 
 ```javascript
-items.getItem("KitchenLight").sendCommand("ON");
-console.log("Kitchen Light State", items.getItem("KitchenLight").state);
+items.KitchenLight.sendCommand("ON");
+console.log("Kitchen Light State", items.KitchenLight.state);
 ```
 
 Sending a notification
@@ -339,6 +339,7 @@ The Items namespace allows interactions with openHAB items.
 See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for full API documentation.
 
 - items : `object`
+  - .NAME ⇒ `Item`
   - .getItem(name, nullIfMissing) ⇒ `Item`
   - .getItems() ⇒ `Array[Item]`
   - .getItemsByTag(...tagNames) ⇒ `Array[Item]`
@@ -348,13 +349,13 @@ See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for fu
   - .safeItemName(s) ⇒ `string`
 
 ```javascript
-var item = items.getItem("KitchenLight");
+var item = items.KitchenLight;
 console.log("Kitchen Light State", item.state);
 ```
 
 #### `getItem(name, nullIfMissing)`
 
-Calling `getItem(...)` returns an `Item` object with the following properties:
+Calling `getItem(...)` or `...` returns an `Item` object with the following properties:
 
 - Item : `object`
   - .rawItem ⇒ `HostItem`
@@ -382,6 +383,7 @@ Calling `getItem(...)` returns an `Item` object with the following properties:
   - .removeTags(...tagNames)
 
 ```javascript
+// Equivalent to items.KitchenLight
 var item = items.getItem("KitchenLight");
 // Send an ON command
 item.sendCommand("ON");
@@ -490,7 +492,7 @@ Note: `serviceId` is optional, if omitted, the default persistence service will
 
 ```javascript
 var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
-var item = items.getItem('KitchenDimmer');
+var item = items.KitchenDimmer;
 console.log('KitchenDimmer averageSince', item.history.averageSince(yesterday));
 ```
 
@@ -503,7 +505,7 @@ The `HistoricItem` object contains the following properties, representing Item s
 
 ```javascript
 var midnight = time.toZDT('00:00');
-var historic = items.getItem('KitchenDimmer').history.maximumSince(midnight);
+var historic = items.KitchenDimmer.history.maximumSince(midnight);
 console.log('KitchenDimmer maximum was ', historic.state, ' at ', historic.timestamp);
 ```
 
@@ -763,7 +765,7 @@ Examples:
 ```javascript
 var now = time.ZonedDateTime.now();
 var yesterday = time.ZonedDateTime.now().minusHours(24);
-var item = items.getItem("Kitchen");
+var item = items.Kitchen;
 console.log("averageSince", item.history.averageSince(yesterday));
 ```
 
@@ -803,7 +805,7 @@ When you have a `time.ZonedDateTime`, a new `toToday()` method was added which w
 For example, if the time was 13:45 and today was a DST changeover, the time will still be 13:45 instead of one hour off.
 
 ```javascript
-var alarm = items.getItem('Alarm');
+var alarm = items.Alarm;
 alarm.postUpdate(time.toZDT(alarm).toToday());
 ```
 
@@ -835,6 +837,7 @@ Tests whether this `time.ZonedDateTime` is after the time passed in `timestamp`,
 `timestamp` can be anything supported by `time.toZDT()`.
 
 ```javascript
+// Equivalent to items.Sunset
 time.toZDT().isAfterTime(items.getItem('Sunset')) // is now after sunset?
 time.toZDT().isAfterDateTime('2022-12-01T12:00Z') // is now after 2022-12-01 noon?
 ```
@@ -850,7 +853,9 @@ Examples:
 
 ```javascript
 time.toZDT().isBetweenTimes('22:00', '05:00') // currently between 11:00 pm and 5:00 am
+// Equivalent to items.Sunset
 time.toZDT().isBetweenTimes(items.getItem('Sunset'), '11:30 PM') // is now between sunset and 11:30 PM?
+// Equivalent to items.StartTime
 time.toZDT(items.getItem('StartTime')).isBetweenTimes(time.toZDT(), 'PT1H'); // is the state of StartTime between now and one hour from now
 ```
 
@@ -1020,6 +1025,7 @@ rules.JSRule({
   description: "Light will turn on when it's 5:00pm",
   triggers: [triggers.GenericCronTrigger("0 0 17 * * ?")],
   execute: (event) => {
+    // Equivalent to items.BalconyLights.sendCommand("ON")
     items.getItem("BalconyLights").sendCommand("ON");
     actions.NotificationAction.sendNotification(email, "Balcony lights are ON");
   },

items/items.js

@@ -558,7 +558,7 @@ const safeItemName = s => s
   .replace(/["']/g, '') // delete
   .replace(/[^a-zA-Z0-9]/g, '_'); // replace with underscore
 
-module.exports = {
+const itemProperties = {
   safeItemName,
   getItem,
   getItems,
@@ -568,21 +568,26 @@ module.exports = {
   createItem,
   removeItem,
   Item,
-  /**
-   * Custom indexer, to allow static Item lookup.
-   * @example
-   * let { my_object_name } = require('openhab').items.objects;
-   * ...
-   * let my_state = my_object_name.state; //my_object_name is an Item
-   *
-   * @returns {object} a collection of items allowing indexing by Item name
-   */
-  objects: () => new Proxy({}, {
-    get: function (target, name) {
-      if (typeof name === 'string' && /^-?\d+$/.test(name)) { return getItem(name); }
-
-      throw Error('unsupported function call: ' + name);
-    }
-  }),
   metadata
 };
+
+/**
+ * Gets an openHAB Item by name directly on the {@link items} namespace.
+ * Equivalent to {@link items.getItem}
+ *
+ * @example
+ * // retrieve item by name directly on the items namespace
+ * console.log(items.KitchenLight.state) // returns 'ON'
+ * // equivalent to
+ * console.log(items.getItem('KitchenLight').state) // returns 'ON'
+ *
+ * @name NAME
+ * @memberof items
+ * @function
+ * @returns {Item|null} {@link items.Item} Item or `null` if Item is missing
+ */
+module.exports = new Proxy(itemProperties, {
+  get: function (target, prop) {
+    return target[prop] || target.getItem(prop, true);
+  }
+});

types/items/items.d.ts

@@ -331,6 +331,5 @@ declare namespace time {
     type ZonedDateTime = import('@js-joda/core').ZonedDateTime;
 }
 import time = require("../time");
-export declare function objects(): any;
 export { metadata };
 //# sourceMappingURL=items.d.ts.map