item persistence median

Signed-off-by: Mark Herwege <[email protected]>

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.

src/items/item-persistence.js

@@ -603,6 +603,45 @@ class ItemPersistence {
   }
 
   /**
+   * Gets the median 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 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.
    *
    * @param {(time.ZonedDateTime | Date)} timestamp the point in time from which to start the summation

types/items/item-persistence.d.ts

@@ -306,12 +306,42 @@ declare class ItemPersistence {
      */
     averageBetween(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.
+     * Gets the median value of the state of a given Item since a certain point in time.
      *
-     * @param {(time.ZonedDateTime | Date)} timestamp the point in time from which to start the summation
+     * @example
+     * var yesterday = new Date(new Date().getTime() - (24 * 60 * 60 * 1000));
+     * 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 sum of the state values since <code>timestamp</code> as {@link items.PersistedState}, or null if <code>timestamp</code> is in the future
+     * @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.
+      *
+      * @param {(time.ZonedDateTime | Date)} timestamp the point in time from which to start the summation
+      * @param {string} [serviceId] optional persistence service ID, if omitted, the default persistence service will be used
+      * @returns {(PersistedState | null)} the sum of the state values since <code>timestamp</code> as {@link items.PersistedState}, or null if <code>timestamp</code> is in the future
+      */
     sumSince(timestamp: (time.ZonedDateTime | Date), serviceId?: string, ...args: any[]): (PersistedState | null);
     /**
      * Gets the sum of the states of a given Item until a certain point in time.