[items] ItemHistory: Add previousStateTimestamp method

CHANGELOG.md

@@ -9,6 +9,7 @@
 | Enhancement | `rules`    | Display `execute` code of `JSRule` in MainUI                             | [#199](https://github.com/openhab/openhab-js/pull/199) | No       |
 | Enhancement | `time`     | Support ISO8601 string parsing in `toZDT`                                | [#202](https://github.com/openhab/openhab-js/pull/202) | No       |
 | Enhancement | `time`     | Add `isBetweenDates` & `isBetweenDateTimes` polyfills to `ZonedDateTime` | [#203](https://github.com/openhab/openhab-js/pull/203) | No       |
+| Enhancement | `items`    | ItemHistory: ItemHistory: Add `previousStateTimestamp` method            | [#205](https://github.com/openhab/openhab-js/pull/205) | No       |
 
 Also see the [Release Milestone](https://github.com/openhab/openhab-js/milestone/10).
 

README.md

@@ -473,6 +473,7 @@ Calling `Item.history` returns a `ItemHistory` object with the following functio
   - .minimumSince(timestamp, serviceId) ⇒ `string | null`
   - .persist(serviceId)
   - .previousState(skipEqual, serviceId) ⇒ `string | null`
+  - .previousStateTimestamp(skipEqual, serviceId) ⇒ `time.ZonedDateTime | null`
   - .sumBetween(begin, end, serviceId) ⇒ `number | null`
   - .sumSince(timestamp, serviceId) ⇒ `number | null`
   - .updatedBetween(begin, end, serviceId) ⇒ `boolean`

items/item-history.js

@@ -1,7 +1,6 @@
-// const { ZonedDateTime } = require('@js-joda/core');
+/** @typedef {import('@js-joda/core')} time */
 const time = require('../time');
 const PersistenceExtensions = Java.type('org.openhab.core.persistence.extensions.PersistenceExtensions');
-const DateTime = Java.type('java.time.ZonedDateTime');
 
 /**
  * Class representing the historic state of an openHAB Item.
@@ -223,7 +222,7 @@ class ItemHistory {
    * @returns {(string | null)} state
    */
   latestState (serviceId) {
-    return this.historicState(DateTime.now(), ...arguments);
+    return this.historicState(time.ZonedDateTime.now(), ...arguments);
   }
 
   /**
@@ -300,6 +299,17 @@ class ItemHistory {
     return this._stateOrNull(PersistenceExtensions.previousState(this.rawItem, ...arguments));
   }
 
+  /**
+   * Returns the time when the previous state of a given Item was persisted.
+   *
+   * @param {boolean} [skipEqual] optional, if true, skips equal state values and searches the first state not equal the current state
+   * @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
+   * @returns {(time.ZonedDateTime | null)} {@link time.ZonedDateTime} or null
+   */
+  previousStateTimestamp (skipEqual, serviceId) {
+    return this._timestampOrNull(PersistenceExtensions.previousState(this.rawItem, ...arguments));
+  }
+
   /**
    * Gets the sum of the states of a given Item between two certain points in time.
    *
@@ -373,7 +383,14 @@ class ItemHistory {
    * @private
    */
   _stateOrNull (result) {
-    return result === null ? null : result.state.toString();
+    return result === null ? null : result.getState().toString();
+  }
+
+  /**
+   * @private
+   */
+  _timestampOrNull (result) {
+    return result === null ? null : time.ZonedDateTime.parse(result.getTimestamp().toString());
   }
 
   /**

docs_config.json → jsdoc.conf.json

@@ -15,7 +15,8 @@
         "excludePattern": "(node_modules/|docs|dist)"
     },
     "plugins": [
-        "plugins/markdown"
+        "plugins/markdown",
+        "node_modules/jsdoc-tsimport-plugin/index.js"
     ],
     "templates": {
         "cleverLinks": false,
@@ -47,4 +48,4 @@
         "nameInOutputPath": false,
         "versionInOutputPath": false
     }
-}
+}

package.json

@@ -20,7 +20,7 @@
         "test:mocha": "mocha test/**/*.test.js",
         "test:jest": "jest",
         "test": "npm run lint && npm run test:mocha && npm run test:jest",
-        "docs": "rm -Rf ./docs/* && jsdoc --configure docs_config.json && mv ./docs/$npm_package_name/$npm_package_version/* ./docs/ && rm -Rf ./docs/$npm_package_name/$npm_package_version",
+        "docs": "rm -Rf ./docs/* && jsdoc --configure jsdoc.conf.json && mv ./docs/$npm_package_name/$npm_package_version/* ./docs/ && rm -Rf ./docs/$npm_package_name/$npm_package_version",
         "deploy": "npm test && npm run docs && npm run webpack",
         "lint": "npx standardx | snazzy",
         "lint:fix": "npx standardx --fix",
@@ -33,6 +33,7 @@
         "docdash": "^1.2.0",
         "jest": "^28.1.3",
         "jsdoc": "^4.0.0",
+        "jsdoc-tsimport-plugin": "^1.0.5",
         "mocha": "^6.2.2",
         "proxyquire": "^2.1.3",
         "rewiremock": "^3.13.9",

types/items/item-history.d.ts

@@ -213,6 +213,14 @@ declare class ItemHistory {
      * @returns {(string | null)} state or null
      */
     previousState(skipEqual?: boolean, serviceId?: string, ...args: any[]): (string | null);
+    /**
+     * Returns the time when the previous state of a given Item was persisted.
+     *
+     * @param {boolean} [skipEqual] optional, if true, skips equal state values and searches the first state not equal the current state
+     * @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
+     * @returns {(time.ZonedDateTime | null)} {@link time.ZonedDateTime} or null
+     */
+    previousStateTimestamp(skipEqual?: boolean, serviceId?: string, ...args: any[]): (time.ZonedDateTime | null);
     /**
      * Gets the sum of the states of a given Item between two certain points in time.
      *
@@ -268,6 +276,10 @@ declare class ItemHistory {
      * @private
      */
     private _stateOrNull;
+    /**
+     * @private
+     */
+    private _timestampOrNull;
     /**
      * @private
      */
@@ -277,4 +289,8 @@ declare class ItemHistory {
      */
     private _decimalOrNull;
 }
+declare namespace ItemHistory {
+    export { time };
+}
+type time = typeof JSJoda;
 //# sourceMappingURL=item-history.d.ts.map