@nrutils/node-red-utils 0.0.0-stage → 0.1.0

package/node-red-base/README.md

@@ -0,0 +1,215 @@
+# node-red-base
+
+`NodeRedNodeBase` turns a list of mixins and a setup function into a Node-RED node module.
+
+## Usage
+
+```js
+const { NodeRedNodeBase } = require('@nrutils/node-red-utils');
+
+module.exports = NodeRedNodeBase.createNode('upper-case', [], (RED, thisNode, config) => {
+    thisNode.on('input', (msg, send, done) => {
+        msg.payload = String(msg.payload).toUpperCase();
+        send(msg);
+        done();
+    });
+});
+```
+
+Put mixins in the array to add features. With an empty array you get a plain node with less code than the usual `registerType` wrapper.
+
+## Example: one node with two mixins
+
+A vibration sensor node. Its [worker](../node-red-worker/README.md) computes the RMS of each block of samples, off the Node-RED event loop. The node shows the result in its status, on its output and, through [editor comms](../node-red-editorcomms/README.md), in its open edit dialog. The Reset button goes from the dialog to the runtime to the worker, and the answer comes back to the dialog.
+
+`vibration.js`:
+
+```js
+const path = require('path');
+const { NodeRedNodeBase, nodeRedWorker, nodeRedEditorComms } = require('@nrutils/node-red-utils');
+
+module.exports = NodeRedNodeBase.createNode('vibration', [nodeRedWorker, nodeRedEditorComms], (RED, thisNode, config) => {
+    const worker = thisNode.nodeRedWorker.init(path.join(__dirname, 'vibration-worker.js'), { rate: 1000 });
+    const comms = thisNode.nodeRedEditorComms;
+
+    // Each second from the worker: to the status, to an open edit dialog, and to the flow
+    worker.subscribe('rms', ({ rms, peak }) => {
+        thisNode.status({ fill: rms > 1 ? 'red' : 'green', shape: 'dot', text: `rms ${rms.toFixed(2)}` });
+        comms.publish('rms', { rms, peak });
+        thisNode.send({ payload: rms, peak });
+    });
+
+    // The Reset button in the dialog: editor to runtime to worker, and the answer back
+    comms.subscribe('reset-peak', () => worker.request('reset-peak', null, [], { timeout: 2000 }));
+});
+```
+
+`vibration-worker.js`:
+
+```js
+// Stand-in for a driver that reads a block of samples from an ADC
+const readSamples = (n) => Float64Array.from({ length: n }, (_, i) => Math.sin(i / 5) + Math.random() * 0.1);
+
+module.exports = function (worker, data) {
+    let peak = 0;
+    const timer = setInterval(() => {
+        let sum = 0;
+        for (const v of readSamples(data.rate)) {
+            sum += v * v;
+            peak = Math.max(peak, Math.abs(v));
+        }
+        worker.parentPorts.publish('rms', { rms: Math.sqrt(sum / data.rate), peak });
+    }, 1000);
+
+    // The answer to request('reset-peak'): the peak before the reset
+    worker.handle('reset-peak', () => { const before = peak; peak = 0; return before; });
+    worker.parentPorts.subscribe('close', () => clearInterval(timer));
+};
+```
+
+`vibration.html`:
+
+```html
+<script type="text/javascript" src="node-red-resourceendpoint/node-red-editorcomms/EditorCommsFrontend.js"></script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('vibration', {
+        category: 'input',
+        defaults: {},
+        outputs: 1,
+        label: function () { return 'vibration'; },
+        // Only the open dialog of this node has the data-node attribute
+        nodeRedEditorComms_subscriptions: {
+            rms: function (v) { $('#vibration-live[data-node="' + this.id + '"]').text('rms ' + v.rms.toFixed(2) + ', peak ' + v.peak.toFixed(2)); }
+        },
+        oneditprepare: function () {
+            const node = this;
+            $('#vibration-live').attr('data-node', node.id);
+            $('#vibration-reset').on('click', () => node.nodeRedEditorComms.publish('reset-peak')
+                .then((before) => RED.notify('Peak before the reset: ' + before.toFixed(2)))
+                .catch((err) => RED.notify(err.status === 404 ? 'Deploy the node first' : err.message, 'warning')));
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="vibration">
+    <div class="form-row">
+        <span id="vibration-live">waiting for data</span>
+        <button type="button" id="vibration-reset" class="red-ui-button">Reset peak</button>
+    </div>
+</script>
+```
+
+## API
+
+### `NodeRedNodeBase.createNode(nodeType, mixins, setup, [options])`
+
+Returns `function (RED)` for `module.exports`. That function calls `onRegisterType(RED)` on the composed class one time, then registers `nodeType` with `RED.nodes.registerType(nodeType, constructor, options)`. For each node instance it:
+
+1. calls `RED.nodes.createNode(this, config)`,
+2. applies the mixins left to right,
+3. calls `setup(RED, thisNode, config)`, where `thisNode` is the Node-RED node.
+
+Register your `input` and `close` handlers, and call mixin methods such as `nodeRedWorker.init()`, before the first `await` in `setup`. `createNode` does not await `setup`; an error after an `await` is only logged with `node.error` as `setup of <type> failed: <message>`.
+
+`options` is optional. It is the third argument of `RED.nodes.registerType`, for example `{ credentials }` or `{ settings }`. See [Credentials and settings](#credentials-and-settings). One more key, `resources`, is for the [`nodeRedResourceEndpoint`](../node-red-resourceendpoint/README.md) mixin: an array of file and directory paths that it serves from when Node-RED loads the node. `createNode` does not pass `resources` on to `registerType`. Without the mixin in `mixins`, `resources` does nothing.
+
+`mixins` is always an array; use `[]` for none. `createNode()` and `with()` check their arguments and throw one `TypeError` that names the function and the bad argument, for example `createNode(type, mixins, setup): mixins must be an array of mixin functions; got function (anonymous)`. A common mistake is to pass a class, such as `NodeRedWorker`, instead of the mixin `nodeRedWorker`.
+
+### `NodeRedNodeBase.with(...mixins)`
+
+Returns a class that extends `NodeRedNodeBase` with the mixins applied. `createNode` uses it. You only need it to compose classes yourself, for example in a node that cannot use `createNode` (see [Adding the library to an existing node](#adding-the-library-to-an-existing-node)). If you do, call `MyClass.onRegisterType(RED)` one time before `RED.nodes.registerType`. Without that call, the editor scripts of `nodeRedEditorComms`, `nodeRedPopup` and `nodeRedSingleton` are not served until a node starts.
+
+### `static onRegisterType(RED)`
+
+`createNode` calls this one time, before any node instance exists. `nodeRedEditorComms`, `nodeRedPopup` and `nodeRedSingleton` override it to serve their editor scripts before the first deploy. `nodeRedResourceEndpoint`, `nodeRedPubsubBus` and `nodeRedWorker` override it too, for their own one-time work. A mixin that needs one-time work can override it too; call `super.onRegisterType(RED)` first.
+
+## Credentials and settings
+
+The fourth argument of `createNode` goes to `registerType` as its options, for example `{ credentials: { token: { type: 'password' } } }`. Node-RED then stores the credentials outside the flow file and puts them on `thisNode.credentials`. The HTML file needs the same `credentials` definition and an input with the id `node-input-<name>`. Use the credential inside the node. Do not copy it onto `msg`.
+
+## Config nodes
+
+A config node holds settings that several nodes share, such as a server address. Make it with `createNode` and give it the category `config` in the HTML file; the ids in its template start with `node-config-input-`. A consumer node stores the config node's id and reads it with `RED.nodes.getNode(id)`, which returns `null` when no config node is selected. Both types can go in one file:
+
+```js
+const server = NodeRedNodeBase.createNode('my-server', [], (RED, thisNode, config) => {
+    thisNode.host = config.host;
+}, { credentials: { password: { type: 'password' } } });
+
+const query = NodeRedNodeBase.createNode('my-query', [], (RED, thisNode, config) => {
+    const serverNode = RED.nodes.getNode(config.server);
+    thisNode.on('input', (msg, send, done) => {
+        if (!serverNode) return done(new Error('no server configured'));
+        // use serverNode.host and serverNode.credentials.password here
+        send(msg);
+        done();
+    });
+});
+
+module.exports = function (RED) {
+    server(RED);
+    query(RED);
+};
+```
+
+In the HTML file, `server: { value: '', type: 'my-server' }` in the consumer's `defaults` gives a config node picker. `package.json` lists the file one time; the HTML of both types goes in the `.html` file with the same name.
+
+## Adding the library to an existing node
+
+A node that you already have, or that must keep its own constructor, does not need `createNode`. Compose the class with `with()` and create it in your constructor:
+
+```js
+const { NodeRedNodeBase, nodeRedWorker } = require('@nrutils/node-red-utils');
+
+module.exports = function (RED) {
+    const Base = NodeRedNodeBase.with(nodeRedWorker);
+    Base.onRegisterType(RED);                 // one time, before registerType
+
+    function MyNode(config) {
+        RED.nodes.createNode(this, config);   // as before
+        new Base(RED, this, config);          // adds thisNode.nodeRedWorker and so on
+        // your existing code
+    }
+
+    RED.nodes.registerType('my-node', MyNode, { credentials: { token: { type: 'password' } } });
+};
+```
+
+Steps: pick the mixins, call `with()` and `onRegisterType(RED)` once in the module function, call `new Base(RED, this, config)` after `RED.nodes.createNode` in the node constructor. The rest of the node stays as it is. The mixins add their API to `this` (the node) as `this.nodeRedWorker`, `this.nodeRedEditorComms` and so on. For editor mixins, also add the script tag to the HTML file (see the README of each mixin).
+
+## Write a mixin
+
+A mixin is a function that takes a class and returns a subclass. Its constructor gets `(RED, thisNode, config)`.
+
+```js
+const { NodeRedNodeBase } = require('@nrutils/node-red-utils');
+
+const heartbeat = (superclass) => class extends superclass {
+    constructor(RED, thisNode, config) {
+        super(RED, thisNode, config);
+        let timer = null;
+
+        thisNode.heartbeat = {
+            start(ms) {
+                clearInterval(timer);
+                timer = setInterval(() => thisNode.send({ payload: Date.now() }), ms);
+            }
+        };
+
+        thisNode.on('close', () => clearInterval(timer));
+    }
+};
+
+module.exports = NodeRedNodeBase.createNode('heartbeat', [heartbeat], (RED, thisNode, config) => {
+    thisNode.heartbeat.start(Number(config.interval) || 1000);
+});
+```
+
+Follow the same rules as the built-in mixins:
+
+- Put the API on `thisNode` under one name. `setup` receives `thisNode`, not the mixin instance.
+- Release timers, handlers and workers in `thisNode.on('close')`. Node-RED closes a node when a deploy replaces or removes it.
+- `with()` and `createNode()` call each mixin with a dummy class to check it, so a mixin function may be called more than once. Do no work in the arrow function itself; do it in the constructor.
+
+[Back to node-red-utils](../README.md)

package/node-red-editorcomms/EditorCommsBackend.js

@@ -0,0 +1,155 @@
+/**
+ * Copyright 2024 Contributors
+ * Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { NodeRedResourceEndpoint } = require('../node-red-resourceendpoint/NodeRedResourceEndpoint.js');
+
+// All copies of this library in one process share this state.
+// Thus one POST route serves the handlers of every copy.
+const shared = globalThis[Symbol.for('node-red-utils.editorcomms')] ??= {};
+shared.handlers ??= new Map();      // nodeId.messageType -> callback
+
+/** Serve EditorCommsFrontend.js and add the POST route. Safe to call more than one time. */
+function setup(RED) {
+    new NodeRedResourceEndpoint(RED).registerResources('node-red-editorcomms', path.join(__dirname, 'EditorCommsFrontend.js'));
+    if (shared.routeRegistered) return;
+    shared.routeRegistered = true;
+    // Single endpoint for all communication
+    RED.httpAdmin.post('/node_red_editorcomms', RED.auth.needsPermission('write'), async (req, res) => {
+        const { messageType, nodeId, payload } = req.body || {};
+        const handler = shared.handlers.get(nodeId + '.' + messageType);
+        if (!handler) {
+            // For example a node that is not deployed yet
+            res.status(404).json({ status: 'no handler' });
+            return;
+        }
+        let result;
+        try {
+            result = await handler(payload);
+        } catch (error) {
+            const message = (error && error.message) || String(error);
+            const node = RED.nodes.getNode(nodeId);
+            if (node) node.error(`Editor message '${messageType}' failed: ${message}`);
+            res.status(500).json({ error: message });
+            return;
+        }
+        res.json({ status: 'ok', result });
+    });
+}
+
+/**
+ * NodeRedEditorComms - Class for managing communication between the Node-RED editor and runtime
+ * Allows nodes to publish and subscribe to messages between the editor and backend
+ */
+class NodeRedEditorComms {
+
+    /**
+     * Create a new editor communications handler
+     * @param {object} RED - The Node-RED runtime instance
+     * @param {object} node - The node instance
+     */
+    constructor(RED, node) {
+        this.RED = RED;
+        this.node = node;
+        this.STATIC_TOPIC = 'node_red_editorcomms';
+
+        setup(RED);
+
+        // Remove the handlers of this node when the node closes
+        this.ownedKeys = new Map();
+        node.on('close', () => {
+            for (const [key, callback] of this.ownedKeys) {
+                if (shared.handlers.get(key) === callback) shared.handlers.delete(key);
+            }
+            this.ownedKeys.clear();
+        });
+    }
+
+    /**
+     * Subscribe to messages of a specific type
+     * @param {string} messageType - The type of message to subscribe to
+     * @param {Function} callback - Called with the payload. Its return value (or the value of its Promise) goes back to the editor.
+     */
+    subscribe(messageType, callback) {
+        const key = this.node.id + '.' + messageType;
+        shared.handlers.set(key, callback);
+        this.ownedKeys.set(key, callback);
+    }
+
+    /**
+     * Publish a message to subscribers
+     * @param {string} messageType - The type of message to publish
+     * @param {any} payload - The payload to send with the message
+     */
+    publish(messageType, payload) {
+        const message = {
+            id: this.STATIC_TOPIC,
+            retain: false,
+            payload: {
+                messageType,
+                nodeId: this.node.id,
+                payload
+            }
+        };
+        this.RED.events.emit('runtime-event', message);
+    }
+}
+
+/**
+ * Mixin that adds editor communication capabilities to Node-RED nodes
+ * 
+ * Allows nodes to communicate between the editor frontend and the runtime backend
+ * 
+ * @param {class} superclass - The class to extend with editor comms capabilities
+ * @returns {class} A new class that extends the superclass with editor comms functionality
+ */
+const nodeRedEditorComms = (superclass) => class extends superclass {
+    // Serve the frontend script and the POST route before the first deploy
+    static onRegisterType(RED) {
+        super.onRegisterType?.(RED);
+        setup(RED);
+    }
+
+    constructor(RED, thisNode, config) {
+        super(RED, thisNode, config);
+
+        // Create the editor comms handler for this node
+        const editorComms = new NodeRedEditorComms(RED, thisNode);
+
+        const commsInterface = {
+            /**
+             * Subscribe to messages of a specific type
+             * @param {string} messageType - The type of message to subscribe to
+             * @param {Function} callback - The callback function to invoke when messages are received
+             */
+            subscribe: function(messageType, callback) {
+                editorComms.subscribe(messageType, callback);
+                return this;
+            },
+
+            /**
+             * Publish a message to subscribers
+             * @param {string} messageType - The type of message to publish
+             * @param {any} payload - The payload to send with the message
+             */
+            publish: function(messageType, payload) {
+                editorComms.publish(messageType, payload);
+                return this;
+            }
+        };
+
+        // Make available on both
+        this.nodeRedEditorComms = commsInterface;
+        thisNode.nodeRedEditorComms = commsInterface;
+
+    }
+};
+
+// Export both the class and the mixin
+module.exports.nodeRedEditorComms = nodeRedEditorComms;
+module.exports.NodeRedEditorComms = NodeRedEditorComms;

package/node-red-editorcomms/EditorCommsFrontend.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright 2024 Contributors
+ * Licensed under the Apache License, Version 2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+//
+//  Begin EditorCommsFrontend.js
+//
+//      Frontend communication handler for Node-RED editor.
+//      Manages pub/sub messaging between frontend and backend components.
+//
+
+if (!window.EditorCommsFrontend) {
+
+    window.EditorCommsFrontend = class EditorCommsFrontend {
+
+        static #handlers = new Map();
+
+        constructor() {
+            this.nodeId = null;
+            this.STATIC_TOPIC = 'node_red_editorcomms';
+            return this;
+        }
+
+        static getHandlers() { return this.#handlers }
+        static clearHandlers() { this.#handlers.clear() }
+        static setHandler(key, handler) { this.#handlers.set(key, handler) }
+
+        // subscribe(type, callback) listens to this node; subscribe(type, nodeId, callback) to another node
+        subscribe(messageType, nodeId, callback) {
+            if (typeof nodeId === 'function') { callback = nodeId; nodeId = this.nodeId; }
+            const key = nodeId + "." + messageType;
+            EditorCommsFrontend.#handlers.set(key, callback);
+        }
+
+        // Returns a Promise that resolves with the return value of the runtime handler.
+        // It rejects with an Error that has a status: 404 (no handler, for example
+        // the node is not deployed), 500 (the handler threw) or 0 (no connection).
+        publish(messageType, payload) {
+
+            const message = {
+                messageType,
+                payload,
+                nodeId: this.nodeId
+            };
+
+            return new Promise((resolve, reject) => {
+                $.ajax({
+                    url: this.STATIC_TOPIC,      // relative: works with httpAdminRoot and proxy paths
+                    type: 'POST',
+                    data: JSON.stringify(message),
+                    contentType: 'application/json'
+                }).then((body) => resolve(body && body.result), (jqXHR, textStatus, errorThrown) => {
+                    const body = jqXHR.responseJSON || {};
+                    const text = jqXHR.status === 404 ? 'no handler for ' + messageType + ': deploy the node first'
+                        : body.error || errorThrown || textStatus;
+                    console.error('Failed to publish:', messageType, text);
+                    reject(Object.assign(new Error(text), { status: jqXHR.status }));
+                });
+            });
+        }
+    }
+
+    // Hold messages until the editor has drawn the flows. Handlers that
+    // touch the view or the DOM fail before that.
+    let flowsLoaded = !!RED.workspaces.active();
+    const pending = [];
+    const dispatch = ({ messageType, nodeId, payload }) => {
+        const handler = window.EditorCommsFrontend.getHandlers().get(nodeId + "." + messageType);
+        if (handler) handler(payload);
+    };
+    RED.events.on('flows:loaded', () => {
+        flowsLoaded = true;
+        pending.splice(0).forEach(dispatch);
+    });
+    RED.comms.subscribe('notification/node_red_editorcomms', (topic, data) => {
+        if (flowsLoaded) dispatch(data);
+        else pending.push(data);
+    });
+
+    // Remove the handlers of a node that is deleted in the editor
+    RED.events.on('nodes:remove', (node) => {
+        const handlers = window.EditorCommsFrontend.getHandlers();
+        for (const key of handlers.keys()) {
+            if (key.startsWith(node.id + '.')) handlers.delete(key);
+        }
+    });
+
+    // add nodeRedEditorComms to every node
+    RED.events.on('nodes:add', async (node) => {
+
+        // Give every node its own comms instance
+        node.nodeRedEditorComms = new window.EditorCommsFrontend();
+        node.nodeRedEditorComms.nodeId = node.id;
+        
+        // Add developer subscriptions if defined
+        if (node?._def?.nodeRedEditorComms_subscriptions) {
+            Object.entries(node._def.nodeRedEditorComms_subscriptions).forEach(([type, handler]) => 
+                window.EditorCommsFrontend.getHandlers().set(`${node.id}.${type}`, handler.bind(node))
+            );
+        }
+    });
+
+}

package/node-red-editorcomms/README.md

@@ -0,0 +1,164 @@
+# node-red-editorcomms
+
+Send messages between a runtime node and the same node in the editor.
+
+## Usage
+
+A node that draws a live chart of its numeric payloads in its edit dialog. When the dialog opens, it asks the runtime for the last 100 values. While the dialog is open, the runtime pushes each new value.
+
+`live-chart.js`:
+
+```js
+const { NodeRedNodeBase, nodeRedEditorComms } = require('@nrutils/node-red-utils');
+
+module.exports = NodeRedNodeBase.createNode('live-chart', [nodeRedEditorComms], (RED, thisNode, config) => {
+    const comms = thisNode.nodeRedEditorComms;
+    const history = [];     // the last 100 numbers
+
+    // The edit dialog asks for the history when it opens. The return value is the answer.
+    comms.subscribe('history', () => history);
+
+    thisNode.on('input', (msg, send, done) => {
+        const value = Number(msg.payload);
+        if (Number.isFinite(value)) {
+            history.push(value);
+            if (history.length > 100) history.shift();
+            comms.publish('value', value);      // to every open editor, at once
+        }
+        send(msg);
+        done();
+    });
+});
+```
+
+`live-chart.html`:
+
+```html
+<script type="text/javascript" src="node-red-resourceendpoint/node-red-editorcomms/EditorCommsFrontend.js"></script>
+
+<script type="text/javascript">
+(function () {
+    let open = null;    // { id, points } of the live-chart node whose edit dialog is open
+
+    function draw() {
+        const canvas = document.getElementById('live-chart-canvas');
+        const min = Math.min(...open.points);
+        const span = Math.max(...open.points) - min || 1;
+        const ctx = canvas.getContext('2d');
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        ctx.beginPath();
+        open.points.forEach((v, i) => ctx.lineTo(i * canvas.width / 99, canvas.height * (1 - (v - min) / span)));
+        ctx.stroke();
+    }
+
+    RED.nodes.registerType('live-chart', {
+        category: 'function',
+        color: '#c7e9c0',
+        defaults: { name: { value: '' } },
+        inputs: 1,
+        outputs: 1,
+        label: function () { return this.name || 'live-chart'; },
+
+        // From the runtime on each message. "this" is the editor node.
+        nodeRedEditorComms_subscriptions: {
+            value: function (v) {
+                if (!open || open.id !== this.id || !open.points) return;
+                open.points.push(v);
+                if (open.points.length > 100) open.points.shift();
+                draw();
+            }
+        },
+
+        oneditprepare: function () {
+            const state = open = { id: this.id, points: null };
+            this.nodeRedEditorComms.publish('history')
+                .then((points) => { if (open === state) { state.points = points; draw(); } })
+                .catch((err) => $('#live-chart-info').text(err.status === 404 ? 'Deploy the node first' : err.message));
+        },
+        oneditsave: function () { open = null; },
+        oneditcancel: function () { open = null; }
+    });
+})();
+</script>
+
+<script type="text/html" data-template-name="live-chart">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <canvas id="live-chart-canvas" width="460" height="120"></canvas>
+    <div id="live-chart-info"></div>
+</script>
+```
+
+The runtime mixin must be in the `createNode` list: its `onRegisterType` serves the editor script, so without it the `<script>` tag in the HTML file gets a 404 and `nodeRedEditorComms` is missing in the editor.
+
+Open the edit dialog and the chart shows the values so far. While the dialog is open, each new message adds a point. A node that is not deployed answers 404, and the dialog says so.
+
+Runtime data shown in the editor must be set with `.text()` or `textContent`, never with `.html()` or `innerHTML`: a message payload can hold HTML that would run as script in the editor.
+
+The first `<script>` tag loads the editor half of this module. The library serves its editor files through [node-red-resourceendpoint](../node-red-resourceendpoint/README.md), at `node-red-resourceendpoint/<name>/<file>` under the editor URL. Here `<name>` is `node-red-editorcomms`. The URL has no leading `/`, so it also works when the editor is not at the root of the server. Load the script one time in each node's HTML file; a second load does nothing.
+
+## API
+
+| Side | `publish(type, data)` | `subscribe(type, ...)` |
+| --- | --- | --- |
+| Runtime | goes to this node in every open editor; no answer | `subscribe(type, handler)`: the handler's return value answers the editor's `publish` |
+| Editor | goes to the runtime node with the same id; returns a Promise for the handler's return value | `subscribe(type, [nodeId], cb)`: gets the runtime's `publish` |
+
+The runtime does not keep a published message: an editor that opens later does not get it. Publish when the value changes, and let a new editor ask for the current value, as `history` does in the example.
+
+### Runtime: `thisNode.nodeRedEditorComms`
+
+- `subscribe(messageType, callback)`: call `callback(payload)` when the editor publishes `messageType` for this node. The return value of `callback` (or the value of its Promise) goes back to the editor as the result of the editor's `publish`. A second `subscribe` with the same type replaces the first.
+- `publish(messageType, [payload])`: send `payload` to this node in every open editor.
+
+Both return the API object, so you can chain calls (`thisNode.nodeRedEditorComms.publish('a', 1).publish('b', 2)`).
+
+### Editor: `node.nodeRedEditorComms`
+
+The frontend script adds this object to every node in the editor.
+
+- `publish(messageType, [payload])`: send to the runtime node with the same id. Returns a native `Promise` that resolves with the return value of the runtime handler (`undefined` if it returns nothing). It rejects with an `Error` that has a `status`; see [Errors](#errors).
+- `subscribe(messageType, callback)`: call `callback(payload)` when the runtime node with the same id publishes `messageType`.
+- `subscribe(messageType, nodeId, callback)`: the same for the runtime node `nodeId`. You need this form only to listen to another node. A second `subscribe` for the same node and type replaces the first. It returns nothing.
+
+`nodeRedEditorComms_subscriptions` in the node definition is the short form of `subscribe`. The script registers each entry when a node is added, with `this` bound to the node. Prefer it to `subscribe()`, for the reasons in the next section.
+
+### Limits of editor `subscribe()`
+
+- There is no `unsubscribe`. To stop a handler, replace it with a new `subscribe` for the same type, for example with `() => {}`.
+- When you delete a node in the editor, the script removes all of its handlers. If you undo the delete, the entries of `nodeRedEditorComms_subscriptions` come back, but handlers that you added with `subscribe()` do not.
+
+## Errors
+
+The Promise of the editor's `publish` rejects with an `Error` that has a `status`:
+
+- 404, body `{"status":"no handler"}`: the runtime has no handler for this node and type. The usual cause is a node that is not deployed yet. A node inside a subflow also gets 404: each subflow instance gives its inner nodes new runtime ids that the editor does not know.
+- 500, body `{"error":"<message>"}`: the handler threw or its Promise rejected. `err.message` is the handler's error message. The runtime node also logs `Editor message '<type>' failed: <message>` with `node.error`. It is not a flow message, so a Catch node does not get it.
+- 0: the runtime cannot be reached.
+
+Add a `.catch` to each `publish`, also when you ignore the error, so the browser does not report an unhandled rejection.
+
+## Preview or Test button
+
+A button in the edit dialog that tries the settings before the user clicks Done:
+
+- Read the values from the form fields (`$('#node-input-url').val()`), not from `this`, and send them in the payload. Until Done, `this` holds the saved values.
+- For an expected user error, such as a bad URL, return `{ error: 'text' }` and show it in the dialog. The request resolves, and the Node-RED log stays quiet.
+- A node that is not deployed answers 404. Show "deploy first" for `err.status === 404`.
+
+```js
+// Runtime
+thisNode.nodeRedEditorComms.subscribe('test-url', async ({ url }) => {
+    if (!/^https?:\/\//.test(url)) return { error: 'The URL must start with http:// or https://' };
+    const res = await fetch(url);           // a network failure throws: 500 and a log line
+    return { status: res.status };
+});
+```
+
+## Security
+
+Any editor user with the `write` permission can POST any message type with any payload to any node id. Thus treat the payload in a runtime handler as user input: check its type and range before you use it, and do not pass it to a shell, a file path or `eval`. Users with read-only access cannot POST, but they get all messages that the runtime publishes to the editor.
+
+[Back to node-red-utils](../README.md)

package/node-red-gpu/GpuBuffer.js

@@ -0,0 +1,29 @@
+'use strict';
+
+class GpuBuffer {
+    constructor(bufferHandle, backend) {
+        this._handle = bufferHandle;
+        this._backend = backend;
+        this._destroyed = false;
+    }
+
+    get view() { return this._handle.view; }
+    get count() { return this._handle.count; }
+    get dtype() { return this._handle.dtype; }
+    get byteLength() { return this._handle.byteLength; }
+
+    destroy() {
+        if (this._destroyed) return;
+        this._destroyed = true;
+        this._backend.destroyBuffer(this._handle);
+    }
+
+    detach() {
+        const ab = this._handle.view.buffer;
+        this._handle.view = null;
+        this.destroy();
+        return ab;
+    }
+}
+
+module.exports = { GpuBuffer };