@aaqu/fromcubes-react 0.2.2 → 0.3.0

package/README.md

@@ -112,7 +112,8 @@ Everything your component needs from the flow lives in one hook:
 
 ```jsx
 const {
-  data,          // last broadcast msg.payload from input wire (reactive)
+  data,          // last msg.payload delivered to this tab from the input wire (reactive)
+  topic,         // msg.topic of that same message, "" when it had none
   send,          // send(payload, topic?) — emit msg on output wire
   user,          // portal user object (when Portal Auth is enabled), or null
   portalClient,  // unique session/tab ID assigned by server on connect
@@ -131,6 +132,36 @@ useEffect(() => { send({}, "init"); }, []);
 
 In the flow, catch `topic === "init"`, look up the state (per-user via `msg._client.userId` if needed) and reply — `msg._client` is already set on the inbound message, so the response returns as a unicast to exactly that tab.
 
+### Every message: `useNodeRedMessages()`
+
+`data` and `topic` are React state: they hold only the **last** message. When two messages arrive before React renders — a flow answering two requests at once, a function node returning several msgs — React renders once and a `useEffect(..., [data])` sees only the last one; the earlier ones are silently lost. The same effect also does not re-fire when the same primitive payload arrives twice in a row.
+
+For events and request → response protocols, use `useNodeRedMessages(handler)`. The handler is called once per incoming message, in order, as `(payload, { topic })`:
+
+```jsx
+function App() {
+  const { send } = useNodeRed();
+  const [photos, setPhotos] = useState([]);
+  const [saving, setSaving] = useState(false);
+
+  useNodeRedMessages((payload, { topic }) => {
+    if (topic === "photos") setPhotos(payload);
+    else if (topic === "saved") setSaving(false);
+  });
+  useEffect(() => { send({}, "init"); }, []);
+  // ...
+}
+```
+
+- It pairs with the `send({}, "init")` pattern above: the hook subscribes in its own effect, which runs before a later `useEffect` in the same component sends the request, so the reply cannot slip past it.
+- No replay: a component mounted later does **not** get an earlier message (unlike `data`, which starts from the last payload this tab received).
+- The latest `handler` is always the one called — no need to memoize it. It unsubscribes on unmount.
+- A handler that throws is logged to the console; other handlers and `useNodeRed()` still get the message.
+
+Rule of thumb: `data` to **show current state**, `useNodeRedMessages` for **events**. (Underneath is the low-level `window.__NR.subscribeMessages(fn)`.)
+
+If a portal already ships its own `fc-portal-utility` named `useNodeRedMessages` (written before the built-in existed), that utility keeps working and shadows the built-in — in every portal that references the name, since utilities are shared.
+
 ## Node configuration
 
 | Field | Purpose |

package/nodes/lib/helpers.js

@@ -141,6 +141,23 @@ function validateSubPath(input) {
   return { ok: true, value: trimmed };
 }
 
+/**
+ * The app's router: `app._router` on Express 4, `app.router` on Express 5.
+ * `_router` is read first because Express 4's `app.router` getter throws.
+ *
+ * @param {Object} app  Express app (e.g. `RED.httpNode`).
+ * @returns {Object|undefined}
+ */
+function getHttpRouter(app) {
+  if (!app) return undefined;
+  if (app._router) return app._router;
+  try {
+    return app.router;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Remove a single route mount-point from an Express router by exact path
  * match. Used at deploy teardown to drop the previous portal's HTTP route
@@ -745,6 +762,8 @@ module.exports.identifierRe = identifierRe;
 module.exports.serveableHash = serveableHash;
 module.exports.hasFreshBuild = hasFreshBuild;
 module.exports.shouldSkipInstall = shouldSkipInstall;
+module.exports.getHttpRouter = getHttpRouter;
+module.exports.removeRoute = removeRoute;
 module.exports.NAME_MAX_LEN = NAME_MAX_LEN;
 
 /**
@@ -969,6 +988,7 @@ function createHelpers(RED) {
     quickCheckSyntax,
     serveableHash,
     hasFreshBuild,
+    getHttpRouter,
     removeRoute,
     isSafeName,
     validateSubPath,

package/nodes/lib/page-builder.js

@@ -205,7 +205,11 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
         window.__NR = {
           _ws: null,
           _listeners: new Set(),
+          // Per-message listeners (useNodeRedMessages). Unlike _listeners they
+          // never get a replay of _lastData: each call is one real frame.
+          _msgListeners: new Set(),
           _lastData: null,
+          _lastTopic: '',
           _authRequired: false,
           _authListeners: new Set(),
           _retries: 0,
@@ -315,8 +319,17 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
                   }
                 }
                 if (m.type === 'data') {
+                  const topic = typeof m.topic === 'string' ? m.topic : '';
                   this._lastData = m.payload;
-                  this._listeners.forEach(fn => fn(m.payload));
+                  this._lastTopic = topic;
+                  // Per-message listeners first, each isolated: React may
+                  // coalesce the state updates below into one render, these
+                  // see every frame.
+                  const meta = { topic };
+                  this._msgListeners.forEach(fn => {
+                    try { fn(m.payload, meta); } catch (err) { console.error('useNodeRedMessages handler', err); }
+                  });
+                  this._listeners.forEach(fn => fn(m.payload, topic));
                 }
               } catch (err) { console.error('WS parse', err); }
             };
@@ -336,10 +349,15 @@ function buildPage(title, transpiledJs, wsPath, customHead, cssHash, user, showW
 
           subscribe(fn) {
             this._listeners.add(fn);
-            if (this._lastData !== null) fn(this._lastData);
+            if (this._lastData !== null) fn(this._lastData, this._lastTopic);
             return () => this._listeners.delete(fn);
           },
 
+          subscribeMessages(fn) {
+            this._msgListeners.add(fn);
+            return () => this._msgListeners.delete(fn);
+          },
+
           subscribeAuth(fn) {
             this._authListeners.add(fn);
             if (this._authRequired) fn(true);
@@ -496,4 +514,40 @@ function buildErrorPage(title, error, wsPath) {
     </html>`;
 }
 
-module.exports = { buildPage, buildErrorPage };
+/**
+ * The hooks every portal bundle gets, inserted after the React shorthand and
+ * before utilities (so a utility may call them). Browser code, kept here next
+ * to the `window.__NR` bridge it talks to.
+ *
+ * - `useNodeRed()` — `data`/`topic` are STATE: the last frame (one object,
+ *   so the two never come from different frames). Two frames arriving
+ *   before React renders collapse into one render, and an effect on `[data]`
+ *   sees only the second.
+ * - `useNodeRedMessages(handler)` — one call per frame, `(payload, {topic})`,
+ *   no replay of an earlier frame on mount. Assigned to `window` rather than
+ *   declared: a portal that ships its own utility of that name (written before
+ *   this existed) shadows it instead of colliding with it at bundle time.
+ */
+const NR_HOOKS_SRC = [
+  "function useNodeRed() {",
+  "  const [last, setLast] = React.useState(() => ({ data: window.__NR._lastData, topic: window.__NR._lastTopic }));",
+  "  React.useEffect(() => window.__NR.subscribe((data, topic) => setLast({ data, topic: topic || '' })), []);",
+  "  const [authRequired, setAuthRequired] = React.useState(window.__NR._authRequired);",
+  "  React.useEffect(() => window.__NR.subscribeAuth(setAuthRequired), []);",
+  "  const send = React.useCallback((payload, topic) => {",
+  "    window.__NR.send(payload, topic);",
+  "  }, []);",
+  "  const user = window.__NR._user || null;",
+  "  const portalClient = window.__NR._portalClient;",
+  "  return { data: last.data, topic: last.topic, send, user, portalClient, authRequired };",
+  "}",
+  "window.useNodeRedMessages = function useNodeRedMessages(handler) {",
+  "  const ref = React.useRef(handler);",
+  "  React.useLayoutEffect(() => { ref.current = handler; });",
+  "  React.useEffect(() => window.__NR.subscribeMessages((payload, meta) => {",
+  "    if (typeof ref.current === 'function') ref.current(payload, meta);",
+  "  }), []);",
+  "};",
+].join("\n");
+
+module.exports = { buildPage, buildErrorPage, NR_HOOKS_SRC };

package/nodes/lib/router.js

@@ -44,7 +44,10 @@
 function route(msg, ctx) {
   const { clients, userIndex, sendTo } = ctx;
   const target = msg && msg._client;
-  const frame = JSON.stringify({ type: "data", payload: msg.payload });
+  // topic rides along only when it is a non-empty string — useNodeRed()
+  // ignores it, useNodeRedMessages() hands it to the handler.
+  const topic = msg && typeof msg.topic === "string" && msg.topic ? msg.topic : undefined;
+  const frame = JSON.stringify({ type: "data", payload: msg.payload, topic });
 
   let delivered = 0;
 

package/nodes/portal-react.html

@@ -130,7 +130,8 @@
       const libContent = [
         "declare const React: any;",
         "declare const ReactDOM: any;",
-        "declare function useNodeRed(): { data: any; send: (payload: any, topic?: string) => void; user: { userId: string; login?: string; displayName?: string; email?: string; role?: string; groups: string[] } | null; portalClient: string | null; authRequired: boolean };",
+        "declare function useNodeRed(): { data: any; topic: string; send: (payload: any, topic?: string) => void; user: { userId: string; login?: string; displayName?: string; email?: string; role?: string; groups: string[] } | null; portalClient: string | null; authRequired: boolean };",
+        "declare function useNodeRedMessages(handler: (payload: any, meta: { topic: string }) => void): void;",
       ].join("\n");
       console.log(PREFIX, "addExtraLib globals.d.ts");
       jsDef.addExtraLib(libContent, "file:///globals.d.ts");
@@ -2071,9 +2072,10 @@
     let headEditorInstance = null;
 
     const STARTER = [
-      "// useNodeRed() \u2192 { data, send, portalClient }",
-      "//   data  = last msg.payload from input wire",
+      "// useNodeRed() \u2192 { data, topic, send, portalClient }",
+      "//   data  = last msg.payload from input wire (topic = its msg.topic)",
       "//   send(payload, topic?) = push msg to output wire",
+      "// useNodeRedMessages((payload, { topic }) => ...) = every msg, in order",
       "// Components from fc-portal-component nodes are available by name.",
       "",
       "function App() {",
@@ -2719,6 +2721,8 @@
   <dl class="message-properties">
     <dt>payload <span class="property-type">any</span></dt>
     <dd>Sent to the open pages; read it with <code>useNodeRed().data</code>.</dd>
+    <dt class="optional">topic <span class="property-type">string</span></dt>
+    <dd>Sent along with the payload; read it with <code>useNodeRed().topic</code>.</dd>
     <dt class="optional">_client <span class="property-type">object</span></dt>
     <dd>
       Who gets it: <code>{ portalClient }</code> one browser tab,
@@ -2747,10 +2751,22 @@
 }</pre>
   <p>
     <code>useNodeRed()</code> gives <code>data</code> (the last payload,
-    <code>null</code> until one arrives), <code>send</code>, <code>user</code>
+    <code>null</code> until one arrives), <code>topic</code> (that message's
+    topic, <code>""</code> if none), <code>send</code>, <code>user</code>
     (the visitor, or <code>null</code>) and <code>portalClient</code> (this
     tab's id).
   </p>
+  <p>
+    <code>data</code> holds only the latest payload: messages that arrive
+    faster than React renders are merged into one render. To handle every
+    message (events, replies to a request), use
+    <code>useNodeRedMessages</code> — it calls your function once per
+    message, in order:
+  </p>
+  <pre>useNodeRedMessages((payload, { topic }) =&gt; {
+  if (topic === "photos") setPhotos(payload);
+  else if (topic === "saved") setSaving(false);
+});</pre>
   <p>
     <b>React Component</b> and <b>React Utility</b> nodes can be used here by
     name, without imports.

package/nodes/portal-react.js

@@ -381,6 +381,7 @@ module.exports = function (RED) {
     quickCheckSyntax,
     serveableHash,
     hasFreshBuild,
+    getHttpRouter,
     removeRoute,
     isSafeName,
     validateSubPath,
@@ -425,7 +426,7 @@ module.exports = function (RED) {
       for (const nodeId of Object.keys(rebuildCallbacks)) scheduleRebuildSelf(nodeId);
     }
   }
-  const { buildPage, buildErrorPage } = require("./lib/page-builder");
+  const { buildPage, buildErrorPage, NR_HOOKS_SRC } = require("./lib/page-builder");
   const { createPortalPageHandler } = require("./lib/portal-page-route");
   const {
     extractUtilitySymbols,
@@ -539,7 +540,7 @@ module.exports = function (RED) {
         deleteCacheFiles(oldSt.jsxHash);
       }
       delete pageState[prevEndpoint];
-      removeRoute(RED.httpNode._router, prevEndpoint);
+      removeRoute(getHttpRouter(RED.httpNode), prevEndpoint);
       delete registeredRoutes[prevEndpoint];
       if (endpointOwners[prevEndpoint] === nodeId) {
         delete endpointOwners[prevEndpoint];
@@ -878,21 +879,8 @@ module.exports = function (RED) {
           "Object.keys(React).filter(k => /^use[A-Z]/.test(k)).forEach(k => { window[k] = React[k]; });",
           "const { createContext, memo, forwardRef, Fragment } = React;",
           "",
-          "// ── useNodeRed hook ──",
-          [
-            "function useNodeRed() {",
-            "  const [data, setData] = React.useState(window.__NR._lastData);",
-            "  React.useEffect(() => window.__NR.subscribe(setData), []);",
-            "  const [authRequired, setAuthRequired] = React.useState(window.__NR._authRequired);",
-            "  React.useEffect(() => window.__NR.subscribeAuth(setAuthRequired), []);",
-            "  const send = React.useCallback((payload, topic) => {",
-            "    window.__NR.send(payload, topic);",
-            "  }, []);",
-            "  const user = window.__NR._user || null;",
-            "  const portalClient = window.__NR._portalClient;",
-            "  return { data, send, user, portalClient, authRequired };",
-            "}",
-          ].join("\n"),
+          "// ── useNodeRed hooks ──",
+          NR_HOOKS_SRC,
           "",
           "// ── Utilities (helpers / hooks / constants) ──",
           cleanUtilJsx,
@@ -1596,7 +1584,7 @@ module.exports = function (RED) {
               deleteCacheFiles(lastJsxHash);
             }
             delete pageState[endpoint];
-            removeRoute(RED.httpNode._router, endpoint);
+            removeRoute(getHttpRouter(RED.httpNode), endpoint);
             delete registeredRoutes[endpoint];
           }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaqu/fromcubes-react",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Fromcubes React - React portals for Node-RED, built at deploy, with live WebSocket data binding",
   "type": "commonjs",
   "keywords": [