@mangar2/messagetree

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
time	string
reason	Reason	optional

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