Abstract

This function implements a cleanup of the message tree Elements with no actual message are deleted

This file includes helper functions to compress history entries of messages

History entry for data with same value and reason coming in regular intervals . These values are counted and not stored separately

This class manages a message store in tree format . yaha home automation uses it to store all communication between its components .

Contents

• Meta
• Type definitions
• Global Functions
  • addToHistory
  • cleanNodeRec
  • createIntervalEntryFromTimeEntry
  • decompress
  • getLastIntervalEntries
  • isIntervalEntry
  • splitTimeEntryIfAppropriate
  • splitTimeValueEntryIfAppropriate
• Class MessageTree
  • Parameters
  • Methods
    • _isRequiredReason
    • addData
    • cleanup
    • getNode
    • getNodes
    • getSection
    • persist
    • readTreeFromPersistedFile

Meta

| | | | --- | --- | | File | cleanup.js | | Abstract | This function implements a cleanup of the message tree Elements with no actual message are deleted | | Author | Volker Böhm | | Copyright | Copyright ( c ) 2020 Volker Böhm | | License | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

| | | | --- | --- | | File | compress.js | | Abstract | This file includes helper functions to compress history entries of messages | | Author | Volker Böhm | | Copyright | Copyright ( c ) 2020 Volker Böhm | | License | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

| | | | --- | --- | | File | intervalentry.js | | Abstract | History entry for data with same value and reason coming in regular intervals . These values are counted and not stored separately | | Author | Volker Böhm | | Copyright | Copyright ( c ) 2020 Volker Böhm | | License | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

| | | | --- | --- | | File | messagetree.js | | Abstract | This class manages a message store in tree format . yaha home automation uses it to store all communication between its components . | | Author | Volker Böhm | | Copyright | Copyright ( c ) 2020 Volker Böhm | | License | This software is licensed under the GNU LESSER GENERAL PUBLIC LICENSE Version 3 . It is furnished "as is" , without any support , and with no warranty , express or implied , as to its usefulness for any purpose . |

Type definitions

Entry {Object}

Entry to add to the history | Name | Type | Description | | ---- | ---- | ------- | | time | timestamp | timestamp of the entry | | | value | Any | message value | | | reason | Array.<Object> | message trace information | |

SingleEntry {Object}

History entry holding a single value | Name | Type | Description | | ---- | ---- | ------- | | type | 'single' | type of the entry | | | time | timestamp | timestamp of the entry | | | value | Any | value of the entry | | | reason | Array.<Object> | reason of the entry | |

TimeValueEntry {Object}

History entry holding several different values with the same reason | Name | Type | Description | | ---- | ---- | ------- | | type | 'timeValue' | type of the entry | | | values | Array.<Object.<time:number, value:Any>> | time/value pairs | | | reason | Array.<Object> | reason of the oldest entry | |

TimeEntry {Object}

History entry holding several identical values with the same reason | Name | Type | Description | | ---- | ---- | ------- | | type | 'time' | type of the entry | | | timestamps | Array.<number> | timestampls of the entries | | | reason | Array.<Object> | reason of the oldest entry | |

HistoryEntry {SingleEntry, TimeValueEntry, TimeEntry, IntervalEntry}

Options {Object}

Options to manage the message tree and its history | Name | Type | Description | | ---- | ---- | ------- | | upperBoundFactor | number | factor to multiply the joined interval for the upper bound | | | upperBoundAddInMilliseconds | integer | constant to add to the joined interval for the upper bound | | | lowerBoundFactor | number | factor to multiply the joined interval for the lower bound | | | lowerBoundSubInMilliseconds | integer | constant to sub from the joined interval for the lower bound | | | maxHistoryLength | integer | maximal amount of entries in the history | | | historyHysterese | integer | amount of entries to delete , if history exeeds max length | | | maxValuesPerHistoryEntry | integer | maximum amount of values per history entry | | | lengthForFurtherCompression | integer | history timeValue length to look for additional compression | |

TimeEntry {Object}

History entry holding several identical values with the same reason | Name | Type | Description | | ---- | ---- | ------- | | type | 'time' | type of the entry | | | timestamps | Array.<number> | timestampls of the entries | | | reason | Array.<Object> | reason of the oldest entry | |

Reason {Array.}

| Name | Type | Description | | ---- | ---- | ------- | | message | string | description of the event reason | | | time | string | timestamp the event happened in ISO-Format | |

Decompressed {Object}

| Name | Type | Description | | ---- | ---- | ------- | | value | number | | value of the entry | | | time | string | | time the value was received ( ISO-Format ) | | | reason | Reason | optional | array of reason information | |

IntervalEntry {Object}

History entry holding several identical values with the same reason and regular updates | Name | Type | Description | | ---- | ---- | ------- | | type | 'interval' | type of the entry | | | amount | number | amount of entries | | | value | number | value of the entry | | | reason | Array.<Object> | reason of the oldest entry | | | firstTime | timestamp | timestamp of the oldes entry | | | lastTime | timestamp | timestamp of the newest entry | |

MessageNode {Object}

| Name | Type | Description | | ---- | ---- | ------- | | time | number | timestamp of last entry in the node | | | value | number | node value | | | reason | Reason | node reason | | | history | History | node history | | | childs | Map | map of child names to child . | |

Global functions

addToHistory

addToHistory (history, entryToAdd, options) => {Array.<HistoryEntry>}

Adds an entry to the history and possible add it or join it with the latest history entry

addToHistory Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | history | Array.<HistoryEntry> | history list | | | entryToAdd | Entry | entry to add to history | | | options | Options | options to calculate the bounds | |

addToHistory returns

| Type | Description | | ---- | ----------- | | Array.<HistoryEntry> | updated history |

cleanNodeRec

cleanNodeRec (tree, three, daysWithoutUpdateToBeRemoved)

Removes all outdated nodes . An outdated node is a node with no update in the last days and without any child with an update in the last days

cleanNodeRec Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | tree | Node | message treee | | | three | `` | | | | daysWithoutUpdateToBeRemoved | number | amount of days the last change is entered before a node is old | |

tree properties

| Name | Type | Description | | ---------- | ------------ | ----------------- | | time | number | timestamp of the last change | |

three properties

| Name | Type | Description | | ---------- | ------------ | ----------------- | | childs | Object | object with a list of all direct childs of the tree | |

createIntervalEntryFromTimeEntry

createIntervalEntryFromTimeEntry (timeEntry)

Creates an History entry holding several identical values with same reason and regular updates by a time entry .

createIntervalEntryFromTimeEntry Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | timeEntry | TimeEntry | entry of type 'time' | |

decompress

decompress (history) => {Array.<Decompressed>}

Decomresses a history entry to an external format

decompress Parameters

| Name | Type | Attribute | Description | | ---------- | ------------ | ------------ | ----------------- | | history | number | optional | [ ] . lastTime ] timestamp the value was encoutered last ( only type 'interval' ) | |

decompress returns

| Type | Description | | ---- | ----------- | | Array.<Decompressed> | array of decompressed history entries |

getLastIntervalEntries

getLastIntervalEntries (timeEntry, options) => {IntervalEntry}

Checks , if last entries in a timeEntry can be converted to an interval entry

getLastIntervalEntries Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | timeEntry | TimeEntry | | | | options | Options | options to calculate the bounds | |

getLastIntervalEntries returns

| Type | Description | | ---- | ----------- | | IntervalEntry | amount of last entries that can be converted |

isIntervalEntry

isIntervalEntry (timeEntry, options) => {boolean}

Checks , if a time entry can be converted to a interval entry

isIntervalEntry Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | timeEntry | TimeEntry | | | | options | Object | options to calculate the bounds | |

options properties

| Name | Type | Description | | ---------- | ------------ | ----------------- | | upperBoundFactor | number | factor to multiply the joined interval for the upper bound | | | upperBoundAddInMilliseconds | number | constant to add to the joined interval for the upper bound | | | lowerBoundFactor | number | factor to multiply the joined interval for the lower bound | | | lowerBoundSubInMilliseconds | number | constant to sub from the joined interval for the lower bound | |

isIntervalEntry returns

| Type | Description | | ---- | ----------- | | boolean | true , if converting is possible |

splitTimeEntryIfAppropriate

splitTimeEntryIfAppropriate (history, options) => {Array.<HistoryEntry>}

Checks to split the last history time entry

splitTimeEntryIfAppropriate Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | history | Array.<HistoryEntry> | history list | | | options | Options | options to calculate the bounds | |

splitTimeEntryIfAppropriate returns

| Type | Description | | ---- | ----------- | | Array.<HistoryEntry> | updated history |

splitTimeValueEntryIfAppropriate

splitTimeValueEntryIfAppropriate (history, options) => {Array.<HistoryEntry>}

Checks to split the last history timeValue entry

splitTimeValueEntryIfAppropriate Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | history | Array.<HistoryEntry> | history list | | | options | Options | options to calculate the bounds | |

splitTimeValueEntryIfAppropriate returns

| Type | Description | | ---- | ----------- | | Array.<HistoryEntry> | updated history |

Class MessageTree

new MessageTree(options)

Data structure holding a large amount of messages with topic , value and reason in a tree organized according the topic . Each tree node containing data provides a "history" including recent messages . It includes several methods to "compress" the history of messages of each topic

MessageTree Parameters

| Name | Type | Attribute | Default | Description | | ---------- | ------------ | ------------ | ------------ | ----------------- | | options | Options | optional | { } | options for the tree | |

MessageTree Methods

_isRequiredReason

_isRequiredReason (reason1, reason2) => {boolan}

Compares two reason objects

_isRequiredReason Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | reason1 | Object, undefined | first reason to compare | | | reason2 | Object, undefined | second reason to compare | |

_isRequiredReason returns

| Type | Description | | ---- | ----------- | | boolan | true , if reasons are identical or ANY reason is undefined , else false |

addData

addData (message, cur)

Adds data to the three node matching to the topic path . It will store the current time , data and descrition to the node and the former time and data entry is copied to the history array property .

addData Parameters

| Name | Type | Attribute | Default | Description | | ---------- | ------------ | ------------ | ------------ | ----------------- | | message | Message | | | { topic , value , reason } | | | cur | Date | optional | new Date ( ) | current time | |

message properties

| Name | Type | Description | | ---------- | ------------ | ----------------- | | topic | string | topic string | | | value | objecObjectt | value of the topic | | | reason | Array.<Object> | list of reasons | |

cleanup

cleanup (daysWithoutUpdateToBeRemoved)

Removes all outdated nodes . An outdated node is a node with no update in the last days and without any child with an update in the last days

cleanup Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | daysWithoutUpdateToBeRemoved | number | amount of days the last change is entered before a node is old | |

getNode

getNode (topic) => {Object}

Searches a node in the message tree corresponding to the topic .

getNode Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | topic | string | topic to store the data | |

getNode returns

| Type | Description | | ---- | ----------- | | Object | data to store |

getNodes

getNodes (requiredNodes, addHistory, addReason)

Gets a list of nodes - if different ( in value or reason ) than the provided nodes

getNodes Parameters

| Name | Type | Attribute | Default | Description | | ---------- | ------------ | ------------ | ------------ | ----------------- | | requiredNodes | Array.<Object> | | | list of nodes required . If empty , all nodes are required | | | addHistory | boolean | optional | true | true , if the history property will be added | | | addReason | boolean | optional | true | true , if the reason property of the messages will be added | |

getSection

getSection (topic, levelAmount, nodes, addHistory, addReason) => {Object.<payload:Object[]>}

Gets several levels of child nodes in an array of nodes

getSection Parameters

| Name | Type | Attribute | Default | Description | | ---------- | ------------ | ------------ | ------------ | ----------------- | | topic | string | | | start topic of the section | | | levelAmount | number | | | amount of levels to get | | | nodes | Array.<Object> | | | list of nodes required . If empty , all nodes are required | | | addHistory | boolean | optional | true | true , if the history property will be added | | | addReason | boolean | optional | true | true , if the reason property of the messages will be added | |

getSection returns

| Type | Description | | ---- | ----------- | | Object.<payload:Object[]> | Object with topics and payloads of all nodes in output format for these ( sub ) topics |

persist

async persist (directory, filenameBasis)

Persists all connections

persist Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | directory | string | directory of the files | | | filenameBasis | string | basis filename , a timestamp is added | |

readTreeFromPersistedFile

readTreeFromPersistedFile (directory, filenameBasis)

Reads the tree from a persisted file

readTreeFromPersistedFile Parameters

| Name | Type | Description | | ---------- | ------------ | ----------------- | | directory | string | directory of the files | | | filenameBasis | string | basis filename , a timestamp is added | |