npm package: @ralphwetzel/node-red-context-monitor
Description: A Node-RED node to monitor a context.
Author: Ralph Wetzel
Latest version: 2.0.0

# @ralphwetzel/node-red-context-monitor

<img alt="flow" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/preview.png"
    style="min-width: 212px; width: 212px; align: center; border: 1px solid lightgray;"/>

A [Node-RED](https://www.nodered.org) node to monitor a [context](https://nodered.org/docs/user-guide/context).

### What it does

This node allows to setup the reference to a context, then sends a message when this context is written to.

It sends a dedicated message on a separate port in case it detects that the value of the context was changed.

The message sent will carry the current value of the context as `msg.payload`, the context key as `msg.topic`.

Monitoring details will be provided as `msg.monitoring`:
* The monitoring setup: `scope` & `key` always, `flow` (id) / `node` (id) if applicable.
* The id of the node that wrote to the context as `source`.

The message sent off the change port carries an additional property in `msg.monitoring`:
* The value overwritten as `previous`.

It is possible to monitor an infinite number of contexts with each instance of this node.

This node supports the three [context scope levels](https://nodered.org/docs/user-guide/context#context-scopes) `Global`, `Flow` & `Node`.

### Installation

Use the Node-RED palette manager to install this node.

### Details

To monitor a `Global` scope context, set the scope to `Global` and provide the context key.

<img alt="global" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/global.png"
    style="min-width: 474px; width: 474px; align: center; border: 1px solid lightgray;"/>

To monitor a `Flow` scope context, set the scope to `Flow`, then select the owning flow and provide the context key.

<img alt="flow" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/flow.png"
    style="min-width: 474px; width: 474px; align: center; border: 1px solid lightgray;"/>

To monitor a `Node` scope context, set the scope to `Node`, then select flow & node and provide the context key.

<img alt="node" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/node.png"
    style="min-width: 474px; width: 474px; align: center; border: 1px solid lightgray;"/>

> Hint: This node doesn't create a context. It just tries to reference to those already existing. If you're referencing a non-existing context, no harm will happen.

### Monitoring objects stored in context
You may of course define a setup that monitors objects stored in context.

If you create a reference to this object (stored in context) and write to its properties, this node issues its messages accordingly.

> Disclaimer: Monitoring changes to elements of an `Array` currently is not supported.

#### Example:
Monitoring context definition:

<img alt="flow" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/object_monitor.png"
    style="min-width: 474px; width: 474px; align: center; border: 1px solid lightgray;"/>

Code in a `function` node:

``` javascript
    // suppose, test_flow = { prop: "value" }
    let obj = flow.get("test_flow");
    obj.prop = "new";
```

Message sent by the node:

<img alt="flow" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/object_msg.png"
    style="min-width: 310px; width: 310px; align: center; border: 1px solid lightgray;"/>

#### Object property monitoring
You may define a setup that doesn't monitor the (whole) object, but only one of its properties:

<img alt="flow" src="https://raw.githubusercontent.com/ralphwetzel/node-red-context-monitor/main/resources/object_prop.png"
    style="min-width: 474px; width: 474px; align: center; border: 1px solid lightgray;"/>

Such a monitor will react _only_, when this property and - if it's an object - its child properties are written to.

### Subflow considerations
You may use this node in [subflows](https://nodered.org/docs/user-guide/editor/workspace/subflows).

Monitoring a `Node` scope context of a node within a subflow is only supported if both nodes (the context monitor and the node to be monitored) belong to the same subflow. Please select `Current Flow` when defining the monitoring context reference.

Please be aware that all instances of a subflow commonly share a single `Flow` scope context. According to the [Node-RED documentation](https://nodered.org/docs/user-guide/context#context-scopes), you can reference the context of the superior flow by prepending `$parent` to the context key.

### Handling of context definition issues
If you edit this node's properties, it ensures that the context reference defined is always valid.
By _copy/paste_-ing a node already configured its configuration yet might become invalid. Same applies if you delete flows or nodes that were referenced earlier.
To ensure the setup, the node does a lazy validation of the context reference definition - when editing its properties and when it is (re)launched. You yet won't get a "red triangle" even if the reference became invalid - to allow a smooth flow editing experience.