@webqit/node-live-response 0.1.0

package/.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+github: ox-harris # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: webqit # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Determine npm tag
+        id: tag
+        run: |
+          # Extract tag name without "refs/tags/"
+          TAG_REF=${GITHUB_REF#refs/tags/}
+          echo "Detected Git tag: $TAG_REF"
+
+          # Determine npm tag
+          if [[ "$TAG_REF" == *-* ]]; then
+            # prerelease (contains a hyphen)
+            NPM_TAG=$(echo "$TAG_REF" | sed -E 's/^v[0-9]+\.[0-9]+\.[0-9]+-([a-zA-Z0-9]+).*/\1/')
+          else
+            NPM_TAG="latest"
+          fi
+          echo "npm publish will use tag: $NPM_TAG"
+          echo "tag=$NPM_TAG" >> $GITHUB_OUTPUT
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --tag ${{ steps.tag.outputs.tag }}

package/.gitignore

@@ -0,0 +1,6 @@
+.*
+
+!/.github
+!.vitepress
+!/.gitignore
+node_modules

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebQit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# LiveResponse for Node.js & Express
+
+This package brings **LiveResponse** to traditional Node.js and Express backends.
+
+LiveResponse is a new response model that extends the HTTP request/response model with interactivity. It allows you to send a response and keep it open for interaction. You want to see the [LiveResponse docs](https://github.com/webqit/fetch-plus?tab=readme-ov-file#section-1-liveresponse) for more details.
+
+The definitive way to get full, always‑on interactivity as a core architectural primitive is **[Webflo](https://github.com/webqit/webflo)**. Live responses are native and automatic there. This package exists for cases where you want LiveResponse inside an otherwise conventional Node.js or Express backend.
+
+---
+
+## Installation
+
+```bash
+npm install @webqit/node-live-response
+```
+
+---
+
+## One-Time Setup
+
+The first thing you do is enable live mode against your server instance. This sets up the transport and request bookkeeping required for LiveResponse.
+
+### Node.js HTTP server
+
+```js
+import http from 'http';
+import { enableLive } from '@webqit/node-live-response';
+
+const server = http.createServer(handler);
+const liveMode = enableLive(server);
+
+server.listen(3000);
+```
+
+### Express
+
+```js
+import express from 'express';
+import { enableLive } from '@webqit/node-live-response';
+
+const app = express();
+const server = app.listen(3000);
+
+const liveMode = enableLive(server);
+```
+
+---
+
+## Usage
+
+The returned `liveMode` function is your per-route live mode switch. Call it on a route where you want live mode enabled.
+
+This function works as both a direct function and an Express middleware.
+
+### Node.js HTTP server
+
+```js
+async function handler(req, res) {
+    liveMode(req, res);
+
+    const liveRes = new LiveResponse('Hello world');
+    await res.send(liveRes); // resolves when live mode is established
+
+    // ------- interactive phase -------
+
+    setTimeout(() => {
+        res.die();
+    }, 5000);
+}
+```
+
+### Express
+
+```js
+app.get('/counter', liveMode(), async (req, res) => {
+    const liveRes = new LiveResponse('Hello world');
+    await res.send(liveRes); // resolves when live mode is established
+    
+    // ------- interactive phase -------
+    
+    setTimeout(() => {
+        res.die();
+    }, 5000);
+});
+```
+
+---
+
+## Live interaction patterns
+
+LiveResponse supports three core interaction patterns.
+
+### 1. Live state projection
+
+A live object can be sent as the response body.
+
+Mutating that object on the server automatically reflects on the client. (More in the [LiveResponse docs](https://github.com/webqit/fetch-plus#1-live-state-projection-via-mutable-response-bodies))
+
+```js
+import { Observer } from '@webqit/observer';
+
+app.get('/counter', liveMode(), async (req, res) => {
+    const state = { count: 0 };
+
+    const liveRes = new LiveResponse(state);
+    await res.send(liveRes); // resolves when live mode is established
+
+    const interval = setInterval(() => {
+        Observer.set(state, 'count', state.count + 1);
+    }, 1000);
+
+    setTimeout(() => {
+        clearInterval(interval);
+        res.die();
+    }, 10000);
+});
+```
+
+Then on the client:
+
+```html
+<!doctype html>
+<head>
+  <title>Live Counter</title>
+  <script src="https://unpkg.com/@webqit/fetch-plus/dist/main.js"></script>
+</head>
+<body>
+
+  <h1></h1>
+  
+  <script type="module">
+    const { LiveResponse, Observer } = window.webqit;
+    
+    const { body: state } = await LiveResponse.from(fetch('/counter')).now();
+
+    Observer.observe(state, () => {
+        document.querySelector('h1').textContent = 'Count: ' + state.count;
+    });
+  </script>
+</body>
+</html>
+```
+
+### 2. Response swapping
+
+A live response can be replaced with a new one – without opening a new request. It gives you a multi-response architecture. (More in the [LiveResponse docs](https://github.com/webqit/fetch-plus?tab=readme-ov-file#2-a-multi-response-architecture-via-response-swaps))
+
+```js
+app.get('/news', liveMode(), async (req, res) => {
+    const liveRes = new LiveResponse({ headline: 'Breaking: Hello World' });
+    await res.send(liveRes); // resolves when live mode is established
+
+    setTimeout(() => {
+        liveRes.replaceWith({ headline: 'Update: Still Hello World' });
+    }, 3000);
+
+    setTimeout(() => {
+        liveRes.replaceWith({ headline: 'Final: Goodbye' });
+        res.die();
+    }, 6000);
+});
+```
+
+Then on the client:
+
+```html
+<!doctype html>
+<head>
+  <title>Live News</title>
+  <script src="https://unpkg.com/@webqit/fetch-plus/dist/main.js"></script>
+</head>
+<body>
+  <h1></h1>
+  <script type="module">
+    const { LiveResponse } = window.webqit;
+    
+    const liveRes = LiveResponse.from(fetch('/news'));
+    liveRes.addEventListener('response', (e) => {
+        document.querySelector('h1').textContent = e.body.headline;
+    });
+  </script>
+</body>
+```
+
+### 3. Bidirectional messaging
+
+Live responses can exchange messages bidirectionally. (More in the [LiveResponse docs](https://github.com/webqit/fetch-plus?tab=readme-ov-file#3-bidirectional-messaging-via-message-ports))
+
+```js
+app.get('/chat', liveMode(), async (req, res) => {
+    const liveRes = new LiveResponse({ title: 'Chat' });
+    await res.send(liveRes); // resolves when live mode is established
+
+    req.port.addEventListener('message', (e) => {
+        req.port.postMessage(e.data);
+    });
+});
+```
+
+Then on the client:
+
+```html
+<!doctype html>
+<head>
+  <title>Live Chat</title>
+  <script src="https://unpkg.com/@webqit/fetch-plus/dist/main.js"></script>
+</head>
+<body>
+
+  <h1>Chat</h1>
+  <ul id="log"></ul>
+  <input id="msg" placeholder="Type and press enter" />
+
+  <script type="module">
+    const { LiveResponse } = window.webqit;
+    
+    const liveRes = LiveResponse.from(fetch('/chat'));
+    liveRes.port.addEventListener('message', (e) => {
+        const li = document.createElement('li');
+        li.textContent = e.data;
+        log.appendChild(li);
+    });
+
+    const msg = document.querySelector('#msg');
+    msg.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') {
+            liveRes.port.postMessage(msg.value);
+            msg.value = '';
+        }
+    });
+  </script>
+</body>
+```
+
+---
+
+## What `node-live-response` does
+
+The library:
+
+* attaches `req.port` and `req.signal` to the request object.
+* patches `res.send()` / `res.end()` to accept `LiveResponse`. Note that calling res.send() with a LiveResponse gives you back a promise that resolves when the connection is live. This promise is to be awaited before interacting with the live response.
+* adds `res.die()` to the response object. This must be called to end interactivity.
+
+---
+
+## Lifecycle contract
+
+### When interactivity starts
+
+Interactivity begins **after** the server sends a `LiveResponse`:
+
+```js
+res.send(liveRes);
+```
+
+That is the moment the client learns that the response is interactive and joins the live channel.
+
+* Live state projection and `replaceWith()` are only meaningful *after* this moment
+* Messages sent on `req.port` *before* this moment are queued
+
+(Contrast this with Webflo, where interaction is implicit and automatic.)
+
+### When interactivity ends
+
+Live mode ends only when you explicitly call `res.die()`. This must be called to end interactivity:
+
+```js
+res.die();
+```
+
+Ending the HTTP response does **not** end live interaction. The request lifecycle and the live lifecycle are not coupled.
+
+---
+
+## Learn more
+
+* [LiveResponse docs](https://github.com/webqit/fetch-plus#1-live-state-projection-via-mutable-response-bodies)
+* [Webflo](https://github.com/webqit/webflo)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@webqit/node-live-response",
+  "publishConfig": {
+    "access": "public"
+  },
+  "title": "LiveResponse for Node.js & Express",
+  "description": "LiveResponse for Node.js & Express",
+  "keywords": [
+    "liveresponse",
+    "live-response",
+    "http",
+    "express",
+    "node",
+    "websocket",
+    "realtime",
+    "webqit"
+  ],
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webqit/node-live-response.git"
+  },
+  "bugs": {
+    "url": "https://github.com/webqit/node-live-response/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "mocha --extension .test.js --recursive --timeout 5000 --exit",
+    "preversion": "npm run test",
+    "postversion": "git push && git push --tags",
+    "version:next": "npm version prerelease --preid=next"
+  },
+  "dependencies": {
+    "@webqit/fetch-plus": "file:../fetch-plus",
+    "@webqit/port-plus": "^0.1.12"
+  },
+  "devDependencies": {
+    "chai": "^4.3.4",
+    "chai-as-promised": "^7.1.1",
+    "esbuild": "^0.20.2",
+    "mocha": "^10.3.0"
+  },
+  "author": "Oxford Harrison <oxharris.dev@gmail.com>",
+  "maintainers": [
+    "Oxford Harrison <oxharris.dev@gmail.com>"
+  ],
+  "contributors": []
+}

package/src/index.js

@@ -0,0 +1,132 @@
+import crypto from 'crypto';
+import { WebSocketServer } from 'ws';
+import { StarPort, WebSocketPort } from '@webqit/port-plus';
+import { LiveResponse, Observer } from '@webqit/fetch-plus';
+
+export { LiveResponse, Observer }
+
+export function enableLive(server) {
+    // One-time WS setup
+    handleUpgrade(server);
+
+    function live(req, res, next) {
+        // Node-style usage: live(req, res)
+        if (req && res) {
+            setupLiveRoute(req, res);
+            return;
+        }
+
+        // Express-style usage: live()
+        return (req, res, next) => {
+            setupLiveRoute(req, res);
+            next();
+        };
+    }
+
+    return live;
+}
+
+export const portRegistry = new Map();
+
+export function setupLiveRoute(req, res) {
+    const port = new StarPort();
+    const portId = crypto.randomUUID();
+
+    portRegistry.set(portId, port);
+
+    const abortController = new AbortController();
+    let hasLiveResponse = false;
+
+    const die = () => {
+        if (abortController.signal.aborted) return;
+        abortController.abort();
+        port.close();
+        portRegistry.delete(portId);
+    };
+
+    // ---- request-scoped capabilities ----
+    req.port = port;
+    req.signal = abortController.signal;
+
+    // ---- response-scoped lifecycle ----
+    res.die = die;
+
+    const originalSend = res.send?.bind(res);
+    const originalEnd = res.end.bind(res);
+
+    async function commitLiveResponse(liveResponse) {
+        if (hasLiveResponse) return;
+        hasLiveResponse = true;
+
+        const response = liveResponse.toResponse({
+            port,
+            signal: abortController.signal,
+        });
+
+        response.headers.set(
+            'X-Message-Port',
+            `socket:///?port_id=${portId}`
+        );
+
+        for (const [name, value] of response.headers) {
+            res.setHeader(name, value);
+        }
+
+        if (response.body) {
+            await response.body.pipeTo(
+                new WritableStream({
+                    write(chunk) {
+                        res.write(chunk);
+                    },
+                    close() {
+                        res.end();
+                    },
+                    abort(err) {
+                        res.destroy(err);
+                    },
+                })
+            );
+        } else {
+            res.end();
+        }
+    }
+
+    // ---- intercept Express-style response exits ----
+    if (originalSend) {
+        res.send = (value) => {
+            if (value instanceof LiveResponse) {
+                commitLiveResponse(value);
+                return req.port.readyStateChange('open').then(() => res);
+            }
+            return originalSend(value);
+        };
+    }
+
+    res.end = (...args) => {
+        // Only end live mode if no LiveResponse was ever committed
+        if (!hasLiveResponse) {
+            die();
+        }
+        return originalEnd(...args);
+    };
+}
+
+export function handleUpgrade(server) {
+    const wss = new WebSocketServer({ noServer: true });
+
+    server.on('upgrade', (req, socket, head) => {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        const portId = url.searchParams.get('port_id');
+
+        if (!portId || !portRegistry.has(portId)) {
+            socket.destroy();
+            return;
+        }
+
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            const wsPort = new WebSocketPort(ws);
+            portRegistry.get(portId).addPort(wsPort);
+        });
+    });
+}
+

package/test/server.js

@@ -0,0 +1,10 @@
+import { enableLive } from '../src/index.js';
+import { LiveResponse } from '@webqit/fetch-plus';
+
+const server = http.createServer((req, res) => {
+    live(req, res);
+    res.send(new LiveResponse('Hello world'));
+});
+
+const live = enableLive(server);
+server.listen(3000);