Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[items] ItemHistory: Add new methods #196

Merged
merged 4 commits into from
Dec 19, 2022
Merged

[items] ItemHistory: Add new methods #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
47804d1
[items] ItemHistory: Fix typos in JSDoc
florian-h05 Dec 16, 2022
416438e
[items] ItemHistory: Add `count****` methods
florian-h05 Dec 16, 2022
594c870
[items] ItemHistory: Fix param JSDoc
florian-h05 Dec 16, 2022
d4a7a84
Update CHANGELOG
florian-h05 Dec 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
| Type | Namespace | Description | Reference | Breaking |
|-------------|------------|----------------------------------------------------------|--------------------------------------------------------|----------|
| Enhancement | `triggers` | Add support for `Item` as argument & Add arg type checks | [#194](https://github.com/openhab/openhab-js/pull/194) | No |
| Enhancement | `items` | ItemHistory: Add new persistence methods | [#196](https://github.com/openhab/openhab-js/pull/196) | No |

Also see the [Release Milestone](https://github.com/openhab/openhab-js/milestone/10).

Expand Down
164 changes: 105 additions & 59 deletions items/item-history.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ class ItemHistory {
/**
* Gets the average value of the state of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
averageBetween (begin, end, serviceId) {
Expand All @@ -36,8 +36,8 @@ class ItemHistory {
* var item = items.getItem('KitchenDimmer');
* console.log('KitchenDimmer average since yesterday', item.history.averageSince(yesterday));
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
averageSince (timestamp, serviceId) {
Expand All @@ -47,9 +47,9 @@ class ItemHistory {
/**
* Checks if the state of a given Item has changed between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {boolean}
*/
changedBetween (begin, end, serviceId) {
Expand All @@ -59,20 +59,66 @@ class ItemHistory {
/**
* Checks if the state of a given Item has changed since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {boolean}
*/
changedSince (timestamp, serviceId) {
return PersistenceExtensions.changedSince(this.rawItem, ...arguments);
}

/**
* Gets the number of available historic data points of a given Item between two certain points in time.
*
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {number}
*/
countBetween (begin, end, serviceId) {
return PersistenceExtensions.countBetween(this.rawItem, ...arguments);
}

/**
* Gets the number of available historic data points of a given Item since a certain point in time.
*
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {number}
*/
countSince (timestamp, serviceId) {
return PersistenceExtensions.countSince(this.rawItem, ...arguments);
}

/**
* Gets the number of changes in historic data points of a given Item between two certain points in time.
*
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {number}
*/
countStateChangesBetween (begin, end, serviceId) {
return PersistenceExtensions.countStateChangesBetween(this.rawItem, ...arguments);
}

/**
* Gets the number of changes in historic data points of a given Item since a certain point in time.
*
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {number}
*/
countStateChangesSince (timestamp, serviceId) {
return PersistenceExtensions.countStateChangesSince(this.rawItem, ...arguments);
}

/**
* Gets the difference value of the state of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
deltaBetween (begin, end, serviceId) {
Expand All @@ -82,8 +128,8 @@ class ItemHistory {
/**
* Gets the difference value of the state of a given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
deltaSince (timestamp, serviceId) {
Expand All @@ -93,9 +139,9 @@ class ItemHistory {
/**
* Gets the standard deviation of the state of the given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
deviationBetween (begin, end, serviceId) {
Expand All @@ -105,8 +151,8 @@ class ItemHistory {
/**
* Gets the standard deviation of the state of the given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
deviationSince (timestamp, serviceId) {
Expand All @@ -117,8 +163,8 @@ class ItemHistory {
* Gets the evolution rate of the state of a given Item since a certain point in time.
*
* @deprecated Replaced by evolutionRateSince and evolutionRateBetween.
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
evolutionRate (timestamp, serviceId) {
Expand All @@ -129,9 +175,9 @@ class ItemHistory {
/**
* Gets the evolution rate of the state of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
evolutionRateBetween (begin, end, serviceId) {
Expand All @@ -141,8 +187,8 @@ class ItemHistory {
/**
* Gets the evolution rate of the state of a given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
evolutionRateSince (timestamp, serviceId) {
Expand All @@ -152,8 +198,8 @@ class ItemHistory {
/**
* Retrieves the historic state for a given Item at a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(string | null)} state
*/
historicState (timestamp, serviceId) {
Expand All @@ -163,8 +209,8 @@ class ItemHistory {
/**
* Query the last update time of a given Item.
*
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @returns {(ZonedDateTime | null)}
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(time.ZonedDateTime | null)}
*/
lastUpdate (serviceId) {
return this._dateOrNull(PersistenceExtensions.lastUpdate(this.rawItem, ...arguments));
Expand All @@ -173,7 +219,7 @@ class ItemHistory {
/**
* Retrieves the historic item state for a given Item at the current point in time.
*
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(string | null)} state
*/
latestState (serviceId) {
Expand All @@ -183,9 +229,9 @@ class ItemHistory {
/**
* Gets the state with the maximum value of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)} state or null
*/
maximumBetween (begin, end, serviceId) {
Expand All @@ -197,8 +243,8 @@ class ItemHistory {
/**
* Gets the state with the maximum value of a given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)} state or null
*/
maximumSince (timestamp, serviceId) {
Expand All @@ -210,9 +256,9 @@ class ItemHistory {
/**
* Gets the state with the minimum value of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)} state or null
*/
minimumBetween (begin, end, serviceId) {
Expand All @@ -224,8 +270,8 @@ class ItemHistory {
/**
* Gets the state with the minimum value of a given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)} state or null
*/
minimumSince (timestamp, serviceId) {
Expand All @@ -237,7 +283,7 @@ class ItemHistory {
/**
* Persists the state of a given Item.
*
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
*/
persist (serviceId) {
PersistenceExtensions.persist(this.rawItem, ...arguments);
Expand All @@ -247,7 +293,7 @@ class ItemHistory {
* Returns the previous state of a given Item.
*
* @param {boolean} [skipEqual] optional, if true, skips equal state values and searches the first state not equal the current state
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(string | null)} state or null
*/
previousState (skipEqual, serviceId) {
Expand All @@ -257,9 +303,9 @@ class ItemHistory {
/**
* Gets the sum of the states of a given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
sumBetween (begin, end, serviceId) {
Expand All @@ -269,8 +315,8 @@ class ItemHistory {
/**
* Gets the sum of the states of a given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
sumSince (timestamp, serviceId) {
Expand All @@ -280,9 +326,9 @@ class ItemHistory {
/**
* Checks if the state of a given Item has been updated between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {boolean}
*/
updatedBetween (begin, end, serviceId) {
Expand All @@ -292,8 +338,8 @@ class ItemHistory {
/**
* Checks if the state of a given Item has been updated since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {boolean}
*/
updatedSince (timestamp, serviceId) {
Expand All @@ -303,9 +349,9 @@ class ItemHistory {
/**
* Gets the variance of the state of the given Item between two certain points in time.
*
* @param {(ZonedDateTime | Date)} begin begin
* @param {(ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} begin begin
* @param {(time.ZonedDateTime | Date)} end end
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
varianceBetween (begin, end, serviceId) {
Expand All @@ -315,8 +361,8 @@ class ItemHistory {
/**
* Gets the variance of the state of the given Item since a certain point in time.
*
* @param {(ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistance service ID, if omitted, the default persistance service will be used.
* @param {(time.ZonedDateTime | Date)} timestamp
* @param {string} [serviceId] Optional persistence service ID, if omitted, the default persistence service will be used.
* @returns {(number | null)}
*/
varianceSince (timestamp, serviceId) {
Expand Down
Loading