talkdom 0.3.1 → 0.4.0

package/README.md

@@ -223,6 +223,100 @@ talkDOM.methods["show:"] = function (el, message) {
 };
 ```
 
+## WebSocket plugin
+
+The optional `websocket.js` plugin adds server-push via WebSocket as an alternative to polling. Load it after the core library:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/talkdom/dist/talkdom.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/talkdom/dist/talkdom-ws.min.js"></script>
+```
+
+### Receiving
+
+Add `ws:` as the last keyword on a receiver with a WebSocket URL as its argument. The server pushes content — no client-side method keywords needed.
+
+```html
+<div receiver="feed ws: ws://localhost:3000/updates"></div>
+```
+
+The server sends JSON messages to control what gets applied:
+
+```json
+{"receiver": "feed", "content": "<p>New post</p>", "op": "append"}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `receiver` | yes | Target receiver name |
+| `content` | no | HTML or text content |
+| `op` | no | `inner` (default), `text`, `append`, `outer` |
+
+Omitting `receiver` broadcasts to all receivers on that connection.
+
+The server can also send raw talkDOM message syntax instead of JSON:
+
+```
+feed apply: Updated! text
+```
+
+This dispatches through the same path as sender clicks and server triggers.
+
+### Sending
+
+The plugin registers a `ws:send:` method. The receiver element's value (for inputs/textareas/selects) or text content is sent over the WebSocket connection.
+
+```html
+<input receiver="chatbox" type="text">
+<button sender="chatbox ws:send: ws://localhost:3000/chat">Send</button>
+```
+
+### Shared connections
+
+Multiple receivers pointing to the same URL share a single WebSocket connection. The server routes messages by the `receiver` field in JSON.
+
+```html
+<div receiver="messages ws: ws://localhost:3000/live"></div>
+<div receiver="presence ws: ws://localhost:3000/live"></div>
+```
+
+### Reconnection
+
+Connections automatically reconnect with exponential backoff (1s initial, 30s max, ±25% jitter). Backoff resets on successful connection. Reconnection stops when all receivers for a URL are removed from the DOM.
+
+### Lifecycle events
+
+| Event | Detail |
+|---|---|
+| `talkdom:ws:open` | `{ url }` |
+| `talkdom:ws:close` | `{ url, code, reason }` |
+| `talkdom:ws:error` | `{ url }` |
+
+Events fire on all receiver elements subscribed to the URL and bubble.
+
+```js
+document.addEventListener("talkdom:ws:open", function (e) {
+  console.log("connected to", e.detail.url);
+});
+```
+
+Incoming messages also fire the standard `talkdom:done` event on the target receiver after applying content.
+
+### Programmatic API
+
+```js
+talkDOM.ws.connect("ws://localhost:3000/live");
+talkDOM.ws.send("ws://localhost:3000/live", { action: "subscribe", channel: "news" });
+talkDOM.ws.send("ws://localhost:3000/live", "plain string");
+talkDOM.ws.disconnect("ws://localhost:3000/live");
+
+talkDOM.ws.connections;      // { "ws://...": { state: 1, receivers: 2 } }
+talkDOM.ws.maxConnections;   // default 16
+talkDOM.ws.maxConnections = 32;
+```
+
+`talkDOM.ws.send` returns `true` if sent, `false` if the connection is not open.
+
 ## Security
 
 talkDOM does **not** sanitize HTML. Content from `get:apply:`, `post:apply:`, server triggers, and piped `apply:` is inserted via `innerHTML` / `insertAdjacentHTML` / `outerHTML` as-is. You are responsible for ensuring that server responses do not contain untrusted markup.

package/dist/talkdom-ws.min.js

@@ -0,0 +1 @@
+!function(){if(window.talkDOM){var e=talkDOM.methods,n=Object.create(null),t=16,r=1e3,o=/\s+/;new MutationObserver(function(e){for(var n=0;n<e.length;n++)for(var t=e[n].addedNodes,r=0;r<t.length;r++){var o=t[r];1===o.nodeType&&(o.hasAttribute&&o.hasAttribute("receiver")&&u(o),o.querySelectorAll&&o.querySelectorAll("[receiver]").forEach(u))}}).observe(document,{childList:!0,subtree:!0}),e["ws:send:"]=function(e,t){var r=n[t];if(!r||!r.ws||r.ws.readyState!==WebSocket.OPEN)return console.error("talkdom-ws: no open connection to "+t),Promise.reject("not connected");var o="value"in e?e.value:e.textContent;r.ws.send(o)},document.querySelectorAll("[receiver]").forEach(u),talkDOM.ws={connect:function(e){if(!n[e]){if(Object.keys(n).length>=t)return void console.warn("talkdom-ws: max connections ("+t+") reached");n[e]={ws:null,receivers:new Set,backoff:r,timer:null,checkTimer:null},n[e].checkTimer=setInterval(function(){c(n[e])||s(e)},5e3)}l(e)},disconnect:function(e){s(e)},send:function(e,t){var r=n[e];return!(!r||!r.ws||r.ws.readyState!==WebSocket.OPEN)&&(r.ws.send("string"==typeof t?t:JSON.stringify(t)),!0)},get connections(){var e=Object.create(null);for(var t in n)e[t]={state:n[t].ws?n[t].ws.readyState:-1,receivers:n[t].receivers.size};return e},get maxConnections(){return t},set maxConnections(e){t=e}}}else console.error("talkdom-ws: load index.js before websocket.js");function c(e){return e.receivers.forEach(function(n){n.isConnected||e.receivers.delete(n)}),e.receivers.size>0}function i(e,n,t){e.receivers.forEach(function(e){e.isConnected&&e.dispatchEvent(new CustomEvent(n,{bubbles:!0,detail:t}))})}function a(t,r){var o=n[t];if(o){c(o);var i=r.data;if("string"==typeof i)if("{"===i.charAt(0))try{!function(n,t){var r,o=t.receiver,c=t.op||"inner",i=t.content||"";r=o?document.querySelectorAll('[receiver~="'+o+'"]'):Array.from(n.receivers);for(var a={receiver:o||"",selector:"apply:",args:[i,c]},s=0;s<r.length;s++){var l=r[s];e["apply:"](l,i,c),l.dispatchEvent(new CustomEvent("talkdom:done",{bubbles:!0,detail:a}))}}(o,JSON.parse(i))}catch(e){console.error("talkdom-ws: invalid JSON from "+t,e)}else talkDOM.send(i).catch(function(e){console.warn("talkdom-ws:",e)})}}function s(e){var t=n[e];t&&(t.timer&&clearTimeout(t.timer),t.checkTimer&&clearInterval(t.checkTimer),t.ws&&(t.ws.onclose=null,t.ws.close()),delete n[e])}function l(e){var t=n[e];if(t&&(!t.ws||t.ws.readyState!==WebSocket.OPEN&&t.ws.readyState!==WebSocket.CONNECTING)){var o=new WebSocket(e);o.onopen=function(){t.backoff=r,i(t,"talkdom:ws:open",{url:e})},o.onmessage=function(n){a(e,n)},o.onclose=function(r){i(t,"talkdom:ws:close",{url:e,code:r.code,reason:r.reason}),function(e){var t=n[e];if(t)if(c(t)){var r=Math.min(t.backoff,3e4);r*=.75+.5*Math.random(),t.timer=setTimeout(function(){t.backoff=Math.min(2*t.backoff,3e4),l(e)},r)}else s(e)}(e)},o.onerror=function(){i(t,"talkdom:ws:error",{url:e})},t.ws=o}}function u(e){var i=e.getAttribute("receiver");if(i){var a=function(e){for(var n=e.trim().split(o),t=1;t<n.length;t++)if("ws:"===n[t]&&n[t+1])return n[t+1];return null}(i);a&&function(e,o){var i=n[o];if(!i){if(Object.keys(n).length>=t)return void console.warn("talkdom-ws: max connections ("+t+") reached, ignoring "+o);i={ws:null,receivers:new Set,backoff:r,timer:null,checkTimer:null},n[o]=i,i.checkTimer=setInterval(function(){c(i)||s(o)},5e3)}i.receivers.add(e),l(o)}(e,a)}}}();

package/dist/talkdom-ws.min.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["window","talkDOM","methods","connections","Object","create","maxConnections","BASE_DELAY","WS","MutationObserver","mutations","i","length","added","addedNodes","j","node","nodeType","hasAttribute","initElement","querySelectorAll","forEach","observe","document","childList","subtree","el","url","conn","ws","readyState","WebSocket","OPEN","console","error","Promise","reject","payload","value","textContent","send","connect","keys","warn","receivers","Set","backoff","timer","checkTimer","setInterval","pruneReceivers","cleanup","connectWs","disconnect","data","JSON","stringify","out","state","size","n","isConnected","delete","fireEvent","name","detail","dispatchEvent","CustomEvent","bubbles","onMessage","event","charAt","msg","targets","receiver","op","content","Array","from","selector","args","routeJson","parse","e","catch","err","clearTimeout","clearInterval","onclose","close","CONNECTING","onopen","onmessage","code","reason","delay","Math","min","random","setTimeout","scheduleReconnect","onerror","attr","getAttribute","tokens","trim","split","parseWsUrl","add","subscribe"],"sources":["websocket.js"],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "talkdom",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Smalltalk-inspired message passing for the DOM",
   "main": "index.js",
   "jsdelivr": "dist/talkdom.min.js",
   "unpkg": "dist/talkdom.min.js",
   "files": [
     "index.js",
+    "websocket.js",
     "dist/"
   ],
   "scripts": {
-    "build": "node -e \"require('fs').mkdirSync('dist',{recursive:true})\" && terser index.js -o dist/talkdom.min.js -c -m --source-map",
+    "build": "node -e \"require('fs').mkdirSync('dist',{recursive:true})\" && terser index.js -o dist/talkdom.min.js -c -m --source-map && terser websocket.js -o dist/talkdom-ws.min.js -c -m --source-map",
     "test": "node test-runner.js",
     "lint": "eslint index.js",
     "prepublishOnly": "npm run build"

package/websocket.js

@@ -0,0 +1,234 @@
+(function () {
+
+  if (!window.talkDOM) {
+    console.error("talkdom-ws: load index.js before websocket.js");
+    return;
+  }
+
+  var methods = talkDOM.methods;
+  var connections = Object.create(null);
+  var maxConnections = 16;
+  var BASE_DELAY = 1000;
+  var MAX_DELAY = 30000;
+  var CLEANUP_INTERVAL = 5000;
+  var WS = /\s+/;
+
+  // Parse receiver attribute to extract ws: URL.
+  // Returns the URL string or null if no ws: keyword found.
+  function parseWsUrl(attr) {
+    var tokens = attr.trim().split(WS);
+    for (var i = 1; i < tokens.length; i++) {
+      if (tokens[i] === "ws:" && tokens[i + 1]) return tokens[i + 1];
+    }
+    return null;
+  }
+
+  // Remove disconnected elements from a connection's receiver set.
+  // Returns true if any receivers remain.
+  function pruneReceivers(conn) {
+    conn.receivers.forEach(function (el) {
+      if (!el.isConnected) conn.receivers.delete(el);
+    });
+    return conn.receivers.size > 0;
+  }
+
+  // Fire a custom event on all connected receivers for a URL.
+  function fireEvent(conn, name, detail) {
+    conn.receivers.forEach(function (el) {
+      if (el.isConnected) {
+        el.dispatchEvent(new CustomEvent(name, { bubbles: true, detail: detail }));
+      }
+    });
+  }
+
+  // Route a parsed JSON message to matching receiver elements.
+  function routeJson(conn, msg) {
+    var name = msg.receiver;
+    var op = msg.op || "inner";
+    var content = msg.content || "";
+    var targets;
+    if (name) {
+      targets = document.querySelectorAll('[receiver~="' + name + '"]');
+    } else {
+      // Broadcast to all receivers on this connection.
+      targets = Array.from(conn.receivers);
+    }
+    var detail = { receiver: name || "", selector: "apply:", args: [content, op] };
+    for (var i = 0; i < targets.length; i++) {
+      var el = targets[i];
+      methods["apply:"](el, content, op);
+      el.dispatchEvent(new CustomEvent("talkdom:done", { bubbles: true, detail: detail }));
+    }
+  }
+
+  // Handle an incoming WebSocket message.
+  function onMessage(url, event) {
+    var conn = connections[url];
+    if (!conn) return;
+    pruneReceivers(conn);
+    var data = event.data;
+    if (typeof data !== "string") return; // ignore binary
+    if (data.charAt(0) === "{") {
+      try {
+        var msg = JSON.parse(data);
+        routeJson(conn, msg);
+      } catch (e) {
+        console.error("talkdom-ws: invalid JSON from " + url, e);
+      }
+    } else {
+      // Raw talkDOM message syntax, dispatch through core.
+      talkDOM.send(data).catch(function (err) {
+        console.warn("talkdom-ws:", err);
+      });
+    }
+  }
+
+  function scheduleReconnect(url) {
+    var conn = connections[url];
+    if (!conn) return;
+    if (!pruneReceivers(conn)) { cleanup(url); return; }
+    var delay = Math.min(conn.backoff, MAX_DELAY);
+    delay = delay * (0.75 + Math.random() * 0.5);
+    conn.timer = setTimeout(function () {
+      conn.backoff = Math.min(conn.backoff * 2, MAX_DELAY);
+      connectWs(url);
+    }, delay);
+  }
+
+  function cleanup(url) {
+    var conn = connections[url];
+    if (!conn) return;
+    if (conn.timer) clearTimeout(conn.timer);
+    if (conn.checkTimer) clearInterval(conn.checkTimer);
+    if (conn.ws) {
+      conn.ws.onclose = null; // prevent reconnect on intentional close
+      conn.ws.close();
+    }
+    delete connections[url];
+  }
+
+  function connectWs(url) {
+    var conn = connections[url];
+    if (!conn) return;
+    // Already open or connecting — skip.
+    if (conn.ws && (conn.ws.readyState === WebSocket.OPEN || conn.ws.readyState === WebSocket.CONNECTING)) return;
+
+    var ws = new WebSocket(url);
+
+    ws.onopen = function () {
+      conn.backoff = BASE_DELAY;
+      fireEvent(conn, "talkdom:ws:open", { url: url });
+    };
+
+    ws.onmessage = function (e) {
+      onMessage(url, e);
+    };
+
+    ws.onclose = function (e) {
+      fireEvent(conn, "talkdom:ws:close", { url: url, code: e.code, reason: e.reason });
+      scheduleReconnect(url);
+    };
+
+    ws.onerror = function () {
+      fireEvent(conn, "talkdom:ws:error", { url: url });
+    };
+
+    conn.ws = ws;
+  }
+
+  // Subscribe an element to a WebSocket URL.
+  function subscribe(el, url) {
+    var conn = connections[url];
+    if (!conn) {
+      var count = Object.keys(connections).length;
+      if (count >= maxConnections) {
+        console.warn("talkdom-ws: max connections (" + maxConnections + ") reached, ignoring " + url);
+        return;
+      }
+      conn = { ws: null, receivers: new Set(), backoff: BASE_DELAY, timer: null, checkTimer: null };
+      connections[url] = conn;
+      // Periodic cleanup check for this connection.
+      conn.checkTimer = setInterval(function () {
+        if (!pruneReceivers(conn)) cleanup(url);
+      }, CLEANUP_INTERVAL);
+    }
+    conn.receivers.add(el);
+    connectWs(url);
+  }
+
+  // Scan a single element for ws: keyword and subscribe.
+  function initElement(el) {
+    var attr = el.getAttribute("receiver");
+    if (!attr) return;
+    var url = parseWsUrl(attr);
+    if (!url) return;
+    subscribe(el, url);
+  }
+
+  // Scan all existing receiver elements.
+  function initWsReceivers() {
+    document.querySelectorAll("[receiver]").forEach(initElement);
+  }
+
+  // Watch for dynamically added ws: receivers.
+  new MutationObserver(function (mutations) {
+    for (var i = 0; i < mutations.length; i++) {
+      var added = mutations[i].addedNodes;
+      for (var j = 0; j < added.length; j++) {
+        var node = added[j];
+        if (node.nodeType !== 1) continue;
+        if (node.hasAttribute && node.hasAttribute("receiver")) initElement(node);
+        if (node.querySelectorAll) {
+          node.querySelectorAll("[receiver]").forEach(initElement);
+        }
+      }
+    }
+  }).observe(document, { childList: true, subtree: true });
+
+  // ws:send: method — send element value over an existing WebSocket connection.
+  methods["ws:send:"] = function (el, url) {
+    var conn = connections[url];
+    if (!conn || !conn.ws || conn.ws.readyState !== WebSocket.OPEN) {
+      console.error("talkdom-ws: no open connection to " + url);
+      return Promise.reject("not connected");
+    }
+    var payload = ("value" in el) ? el.value : el.textContent;
+    conn.ws.send(payload);
+  };
+
+  initWsReceivers();
+
+  talkDOM.ws = {
+    connect: function (url) {
+      if (!connections[url]) {
+        var count = Object.keys(connections).length;
+        if (count >= maxConnections) {
+          console.warn("talkdom-ws: max connections (" + maxConnections + ") reached");
+          return;
+        }
+        connections[url] = { ws: null, receivers: new Set(), backoff: BASE_DELAY, timer: null, checkTimer: null };
+        connections[url].checkTimer = setInterval(function () {
+          if (!pruneReceivers(connections[url])) cleanup(url);
+        }, CLEANUP_INTERVAL);
+      }
+      connectWs(url);
+    },
+    disconnect: function (url) { cleanup(url); },
+    send: function (url, data) {
+      var conn = connections[url];
+      if (!conn || !conn.ws || conn.ws.readyState !== WebSocket.OPEN) return false;
+      conn.ws.send(typeof data === "string" ? data : JSON.stringify(data));
+      return true;
+    },
+    get connections() {
+      var out = Object.create(null);
+      for (var url in connections) {
+        out[url] = { state: connections[url].ws ? connections[url].ws.readyState : -1, receivers: connections[url].receivers.size };
+      }
+      return out;
+    },
+    get maxConnections() { return maxConnections; },
+    set maxConnections(n) { maxConnections = n; },
+  };
+
+}());