[items] ItemPersistence: Add medianSince, medianUntil and medianBetwe…

…en methods (#376) Closes #375. Signed-off-by: Mark Herwege <[email protected]>
openhab · Aug 26, 2024 · d3898b8 · d3898b8
1 parent fbe0f08
commit d3898b8
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -526,6 +526,9 @@ Calling `Item.persistence` returns an `ItemPersistence` object with the followin
   - .minimumSince(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .minimumUntil(timestamp, serviceId) ⇒ `PersistedItem | null`
   - .minimumBetween(begin, end, serviceId) ⇒ `PersistedItem | null`
+  - .medianSince(timestamp, serviceId) ⇒ `PersistedState | null`
+  - .medianUntil(timestamp, serviceId) ⇒ `PersistedState | null`
+  - .medianBetween(begin, end, serviceId) ⇒ `PersistedState | null`
   - .persist(serviceId): Tells the persistence service to store the current Item state, which is then done asynchronously.
     **Warning:** This has the side effect, that if the Item state changes shortly after `.persist` has been called, the new Item state will be persisted. See [JSDoc](https://openhab.github.io/openhab-js/items.ItemPersistence.html#persist) for a possible work-around.
   - .persist(timestamp, state, serviceId): Tells the persistence service to store the given state at the given timestamp, which is then done asynchronously.

diff --git a/src/items/item-persistence.js b/src/items/item-persistence.js
@@ -567,7 +567,7 @@ class ItemPersistence {
    * Gets the average value of the state of a given Item since a certain point in time.
    *
    * @example
-   * var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+   * var yesterday = time.toZDT().minusDays(1);
    * var item = items.getItem('KitchenDimmer');
    * console.log('KitchenDimmer average since yesterday', item.persistence.averageSince(yesterday));
    *
@@ -602,6 +602,45 @@ class ItemPersistence {
     return _stateOrNull(PersistenceExtensions.averageBetween(this.rawItem, ...arguments));
   }
 
+  /**
+   * Gets the median value of the state of a given Item since a certain point in time.
+   *
+   * @example
+   * var yesterday = time.toZDT().minusDays(1);
+   * var item = items.getItem('KitchenDimmer');
+   * console.log('KitchenDimmer median since yesterday', item.persistence.medianSince(yesterday));
+   *
+   * @param {(time.ZonedDateTime | Date)} timestamp the point in time from which to search for the median value
+   * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+   * @returns {(PersistedState | null)} the median value since <code>timestamp</code> as {@link items.PersistedState} or <code>null</code> if no previous states could be found
+   */
+  medianSince (timestamp, serviceId) {
+    return _stateOrNull(PersistenceExtensions.medianSince(this.rawItem, ...arguments));
+  }
+
+  /**
+   * Gets the median value of the state of a given Item until a certain point in time.
+   *
+   * @param {(time.ZonedDateTime | Date)} timestamp the point in time to which to search for the median value
+   * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+   * @returns {(PersistedState | null)} the median value until <code>timestamp</code> as {@link items.PersistedState} or <code>null</code> if no future states could be found
+   */
+  medianUntil (timestamp, serviceId) {
+    return _stateOrNull(PersistenceExtensions.medianUntil(this.rawItem, ...arguments));
+  }
+
+  /**
+   * Gets the median value of the state of a given Item between two certain points in time.
+   *
+   * @param {(time.ZonedDateTime | Date)} begin the point in time from which to start the median
+   * @param {(time.ZonedDateTime | Date)} end the point in time to which to start the median
+   * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+   * @returns {(PersistedState | null)} the median value between <code>begin</code> and <code>end</code> as {@link items.PersistedState} or <code>null</code> if no states could be found
+   */
+  medianBetween (begin, end, serviceId) {
+    return _stateOrNull(PersistenceExtensions.medianBetween(this.rawItem, ...arguments));
+  }
+
   /**
    * Gets the sum of the states of a given Item since a certain point in time.
    *

diff --git a/types/items/item-persistence.d.ts b/types/items/item-persistence.d.ts
@@ -279,7 +279,7 @@ declare class ItemPersistence {
      * Gets the average value of the state of a given Item since a certain point in time.
      *
      * @example
-     * var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+     * var yesterday = time.toZDT().minusDays(1);
      * var item = items.getItem('KitchenDimmer');
      * console.log('KitchenDimmer average since yesterday', item.persistence.averageSince(yesterday));
      *
@@ -305,6 +305,36 @@ declare class ItemPersistence {
      * @returns {(PersistedState | null)} the average value between <code>begin</code> and <code>end</code> as {@link items.PersistedState} or <code>null</code> if no states could be found
      */
     averageBetween(begin: (time.ZonedDateTime | Date), end: (time.ZonedDateTime | Date), serviceId?: string, ...args: any[]): (PersistedState | null);
+    /**
+     * Gets the median value of the state of a given Item since a certain point in time.
+     *
+     * @example
+     * var yesterday = time.toZDT().minusDays(1);
+     * var item = items.getItem('KitchenDimmer');
+     * console.log('KitchenDimmer median since yesterday', item.persistence.medianSince(yesterday));
+     *
+     * @param {(time.ZonedDateTime | Date)} timestamp the point in time from which to search for the median value
+     * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+     * @returns {(PersistedState | null)} the median value since <code>timestamp</code> as {@link items.PersistedState} or <code>null</code> if no previous states could be found
+     */
+    medianSince(timestamp: (time.ZonedDateTime | Date), serviceId?: string, ...args: any[]): (PersistedState | null);
+    /**
+     * Gets the median value of the state of a given Item until a certain point in time.
+     *
+     * @param {(time.ZonedDateTime | Date)} timestamp the point in time to which to search for the median value
+     * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+     * @returns {(PersistedState | null)} the median value until <code>timestamp</code> as {@link items.PersistedState} or <code>null</code> if no future states could be found
+     */
+    medianUntil(timestamp: (time.ZonedDateTime | Date), serviceId?: string, ...args: any[]): (PersistedState | null);
+    /**
+     * Gets the median value of the state of a given Item between two certain points in time.
+     *
+     * @param {(time.ZonedDateTime | Date)} begin the point in time from which to start the median
+     * @param {(time.ZonedDateTime | Date)} end the point in time to which to start the median
+     * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+     * @returns {(PersistedState | null)} the median value between <code>begin</code> and <code>end</code> as {@link items.PersistedState} or <code>null</code> if no states could be found
+     */
+    medianBetween(begin: (time.ZonedDateTime | Date), end: (time.ZonedDateTime | Date), serviceId?: string, ...args: any[]): (PersistedState | null);
     /**
      * Gets the sum of the states of a given Item since a certain point in time.
      *

diff --git a/types/items/item-persistence.d.ts.map b/types/items/item-persistence.d.ts.map