npm - datastar-ssegen - Versions diffs - 0.0.1 - Mend

datastar-ssegen 0.0.1

Files changed (8) hide show

package/.github/workflows/publish.yml +24 -0
package/README.md +89 -0
package/examples/commonHandlers.js +91 -0
package/examples/express.example.js +38 -0
package/examples/hyper-express.example.js +42 -0
package/examples/node.example.js +71 -0
package/index.js +273 -0
package/package.json +31 -0

package/.github/workflows/publish.yml ADDED Viewed

@@ -0,0 +1,24 @@
+# publish to npm
+name: Publish Package
+on:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - created
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org/'
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md ADDED Viewed

@@ -0,0 +1,89 @@
+![Version](https://img.shields.io/github/package-json/v/jmcudd/datastar-ssegen?filename=package.json)
+![Stars](https://img.shields.io/github/stars/jmcudd/datastar-ssegen?style=flat)
+# datastar-ssegen
+## Overview
+The `datastar-ssegen` is a backend JavaScript module designed to generate Server-Sent Events (SSE) for connected [Datastar](https://data-star.dev/) clients. It supports popular server frameworks such as Express.js, Node.js, and Hyper Express.js.
+This package is engineered to integrate tightly with request and response objects of these backend frameworks, enabling efficient and reactive web application development.
+### Key Features
+- Real-time updates with Server-Sent Events tailored for Datastar clients
+- Seamless integration with Express.js, Hyper Express.js, and Node HTTP
+### Installation
+Install the package via npm:
+```bash
+npm install datastar-ssegen
+```
+### Quick Start Example with Express.js
+Here's a straightforward example of setting up an Express.js server with the datastar-ssegen:
+```javascript
+import express from 'express';
+import { ServerSentEventGenerator } from 'datastar-ssegen';
+const app = express();
+app.use(express.json());
+// Define event handlers here
+app.get('/messages', handleMessages);
+app.get('/clock', handleClock);
+const PORT = 3101;
+app.listen(PORT, () => {
+  console.log(`Server running at http://localhost:${PORT}`);
+});
+```
+### Client Interaction Example
+Here's a simple HTML page to interact with the server:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar/bundles/datastar.js"></script>
+  <title>SSE Example</title>
+</head>
+<body>
+  <h1>SSE Demo</h1>
+  <div id="greeting-area">Greeting: <button onclick="sse('/messages')">Get Greeting</button></div>
+  <div id="clock-area">Current Time: <button onclick="sse('/clock')">Start Clock</button></div>
+</body>
+</html>
+```
+### Available Functions
+The `ServerSentEventGenerator` provides several functions to facilitate communication with connected Datastar clients using Server-Sent Events:
+- **`init(request, response)`**: Initializes SSE communication with the specified request and response.
+- **`_send(eventType, dataLines, sendOptions)`**: Sends a server-sent event (SSE) to the client. Options include setting an `eventId` and defining `retryDuration`.
+- **`ReadSignals(signals)`**: Reads and merges signals based on HTTP methods with predefined signals, useful for parsing query or body data sent to the server.
+- **`MergeFragments(fragments, options)`**: Sends a merge fragments event to update HTML content on the client. Options include `selector`, `mergeMode`, `settleDuration`, and `useViewTransition`.
+- **`RemoveFragments(selector, options)`**: Dispatches events to remove HTML elements based on a CSS selector. Options can set a `settleDuration` or `useViewTransition`.
+- **`MergeSignals(signals, options)`**: Sends a merge signals event to update or add client-side signals. Options may include `onlyIfMissing`.
+- **`RemoveSignals(paths, options)`**: Sends an event to remove specific client-side signals identified by paths.
+- **`ExecuteScript(script, options)`**: Directs the client to execute specified JavaScript code. Options can enable `autoRemove` of the script after execution.
+This expanded set provides comprehensive functionality to build interactive web applications with real-time updates and dynamic HTML and signal management.

package/examples/commonHandlers.js ADDED Viewed

@@ -0,0 +1,91 @@
+import { ServerSentEventGenerator } from "../index.js";
+export let backendStore = {
+  someBackendValue: "This is something",
+};
+export const homepage = (name = "") => {
+  return `<html>
+  <head>
+    <title>${name} Datastar Test</title>
+    <script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@develop/bundles/datastar.js"></script>
+  </head>
+  <body>
+    <h3>${name} Datastar Test</h3>
+    <div data-signals="{theme: 'light', lastUpdate:'Never', xyz:'some signal'}">
+      <h3>Long Lived SSE:</h3>
+      <div id="clock" data-on-load="sse('/clock')">...Loading Clock</div>
+      <h3>MergeSignals:</h3>
+      <div>Last User Interaction:<span data-text="lastUpdate.value"></span></div>
+      <h3>Merge Fragments</h3>
+      <div id="quote">No Quote</div>
+      <button data-on-click="sse('/quote')">MergeFragments</button>
+      <h3>RemoveFragments</h3>
+      <div id="trash">
+        Remove me please!
+        <button data-on-click="sse('/removeTrash')">RemoveFragments</button>
+      </div>
+      <h3>ExecuteScript</h3>
+      <div>Print to Console</div>
+      <button data-on-click="sse('/printToConsole')">ExecuteScript</button>
+      <h3>ReadSignals</h3>
+      <button data-on-click="sse('/readSignals')">ReadSignals</button>
+      <h3>ReadSignals (post)</h3>
+      <button data-on-click="sse('/readSignals', {method: 'post'})">ReadSignals (post)</button>
+      <h3>RemoveSignals</h3>
+      <div>Signal xyz:<span data-text="xyz.value"></span></div>
+      <button data-on-click="sse('/removeSignal')">Test RemoveSignals: xyz</button>
+    </div>
+  </body>
+  </html>`;
+};
+export const handleQuote = async (req, res) => {
+  const sse = ServerSentEventGenerator.init(req, res);
+  const qoutes = [
+    "Any app that can be written in JavaScript, will eventually be written in JavaScript. - Jeff Atwood",
+    "JavaScript is the world's most misunderstood programming language. - Douglas Crockford",
+    "The strength of JavaScript is that you can do anything. The weakness is that you will. - Reg Braithwaite",
+  ];
+  const randomQuote = (arr) => arr[Math.floor(Math.random() * arr.length)];
+  await sse.MergeFragments(`<div id="quote">${randomQuote(qoutes)}</div>`);
+  await sse.MergeSignals({ lastUpdate: Date.now() });
+  res.end();
+};
+export const handleReadSignals = async (req, res) => {
+  const sse = ServerSentEventGenerator.init(req, res);
+  backendStore = await sse.ReadSignals(backendStore);
+  console.log("backendStore updated", backendStore);
+  res.end();
+};
+export const handleRemoveTrash = async (req, res) => {
+  const sse = ServerSentEventGenerator.init(req, res);
+  await sse.RemoveFragments("#trash");
+  await sse.MergeSignals({ lastUpdate: Date.now() });
+  res.end();
+};
+export const handleExecuteScript = async (req, res) => {
+  const sse = ServerSentEventGenerator.init(req, res);
+  await sse.ExecuteScript(`console.log("Hello from the backend!")`);
+  await sse.MergeSignals({ lastUpdate: Date.now() });
+  res.end();
+};
+export const handleClock = async function (req, res) {
+  const sse = ServerSentEventGenerator.init(req, res);
+  setInterval(async () => {
+    await sse.MergeFragments(`<div id="clock">${new Date()}</div>`);
+  }, 1000);
+};
+export const handleRemoveSignal = async (req, res) => {
+  const sse = ServerSentEventGenerator.init(req, res);
+  await sse.RemoveSignals(["xyz"]);
+};

package/examples/express.example.js ADDED Viewed

@@ -0,0 +1,38 @@
+import express from "express";
+import { ServerSentEventGenerator } from "../index.js";
+import {
+  homepage,
+  handleQuote,
+  handleReadSignals,
+  handleRemoveTrash,
+  handleExecuteScript,
+  handleClock,
+  handleRemoveSignal,
+} from "./commonHandlers.js";
+const app = express();
+const PORT = 3101;
+// Middleware to parse incoming JSON bodies if needed
+app.use(express.json());
+app.get("/", (req, res) => {
+  res.send(homepage("Express.js"));
+});
+app.get("/quote", handleQuote);
+app.get("/readSignals", handleReadSignals);
+app.get("/removeTrash", handleRemoveTrash);
+app.get("/printToConsole", handleExecuteScript);
+app.get("/clock", handleClock);
+app.get("/removeSignal", handleRemoveSignal);
+app.listen(PORT, () => {
+  console.log(`Express.js server http://localhost:${PORT}`);
+});

package/examples/hyper-express.example.js ADDED Viewed

@@ -0,0 +1,42 @@
+import HyperExpress from "hyper-express";
+import {
+  homepage,
+  handleQuote,
+  handleReadSignals,
+  handleRemoveTrash,
+  handleExecuteScript,
+  handleClock,
+  handleRemoveSignal,
+} from "./commonHandlers.js";
+// Initialize HyperExpress server
+const server = new HyperExpress.Server();
+const PORT = 3102;
+// Configure routes
+server.get("/", (req, res) => {
+  res.html(homepage("hyper-express"));
+});
+server.get("/quote", handleQuote);
+server.get("/readSignals", handleReadSignals);
+server.get("/removeTrash", handleRemoveTrash);
+server.get("/printToConsole", handleExecuteScript);
+server.get("/clock", handleClock);
+server.get("/removeSignal", handleRemoveSignal);
+// Start the server
+server
+  .listen(PORT)
+  .then(() => {
+    console.log(`HyperExpress server http://localhost:${PORT}`);
+  })
+  .catch((error) => {
+    console.error("Error starting server:", error);
+  });

package/examples/node.example.js ADDED Viewed

@@ -0,0 +1,71 @@
+import http from "http";
+import {
+  homepage,
+  handleQuote,
+  handleReadSignals,
+  handleRemoveTrash,
+  handleExecuteScript,
+  handleClock,
+  handleRemoveSignal,
+} from "./commonHandlers.js";
+import url from "url";
+// Initialize an HTTP server
+const PORT = 3100;
+const server = http.createServer((req, res) => {
+  if (req.method === "GET") {
+    const parsedUrl = url.parse(req.url);
+    switch (parsedUrl.pathname) {
+      case "/":
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(homepage("node.js"));
+        break;
+      case "/quote":
+        handleQuote(req, res);
+        break;
+      case "/readSignals":
+        handleReadSignals(req, res);
+        break;
+      case "/removeTrash":
+        handleRemoveTrash(req, res);
+        break;
+      case "/printToConsole":
+        handleExecuteScript(req, res);
+        break;
+      case "/clock":
+        handleClock(req, res);
+        break;
+      case "/removeSignal":
+        handleRemoveSignal(req, res);
+        break;
+      default:
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("404 Not Found");
+    }
+  } else if (req.method === "POST") {
+    const parsedUrl = url.parse(req.url);
+    switch (parsedUrl.pathname) {
+      case "/readSignals":
+        console.log("post readsignals");
+        handleReadSignals(req, res);
+        break;
+    }
+  } else {
+    res.writeHead(405, { "Content-Type": "text/plain" });
+    res.end("Method Not Allowed");
+  }
+});
+// Start the server
+server.listen(PORT, () => {
+  console.log(`Node.js server http://localhost:${PORT}`);
+});

package/index.js ADDED Viewed

@@ -0,0 +1,273 @@
+import url from "url";
+import querystring from "querystring";
+/**
+ * ServerSentEventGenerator is responsible for initializing and handling
+ * server-sent events (SSE) for different web frameworks.
+ */
+export const ServerSentEventGenerator = {
+  /**
+   * Initializes the server-sent event generator.
+   *
+   * @param {object} res - The response object from the framework.
+   * @returns {Object} Methods for manipulating server-sent events.
+   */
+  init: function (request, response) {
+    return {
+      headersSent: false,
+      req: request,
+      res: response,
+      /**
+       * @typedef {Object} SendOptions
+       * @property {?string} [eventId=null] - Event ID to attach.
+       * @property {number} [retryDuration=1000] - Retry duration in milliseconds.
+       */
+      /**
+       * Sends a server-sent event (SSE) to the client.
+       *
+       * @param {string} eventType - The type of the event.
+       * @param {string[]} dataLines - Lines of data to send.
+       * @param {SendOptions} [sendOptions] - Additional options for sending events.
+       */
+      _send: function (
+        eventType,
+        dataLines,
+        sendOptions = {
+          eventId: null,
+          retryDuration: 1000,
+        }
+      ) {
+        //Prepare the message for sending.
+        let data = dataLines.map((line) => `data: ${line}\n`).join("") + "\n";
+        let eventString = "";
+        if (sendOptions.eventId != null) {
+          eventString += `id: ${sendOptions.eventId}\n`;
+        }
+        if (eventType) {
+          eventString += `event: ${eventType}\n`;
+        }
+        eventString += `retry: ${sendOptions.retryDuration}\n`;
+        eventString += data;
+        //Send Event
+        if (!this.headersSent) {
+          this.res.setHeader("Cache-Control", "nocache");
+          this.res.setHeader("Connection", "keep-alive");
+          this.res.setHeader("Content-Type", "text/event-stream");
+          this.headersSent = true;
+        }
+        this.res.write(eventString);
+        return eventString;
+      },
+      /**
+       * Reads signals based on HTTP methods and merges them with provided signals.
+       *
+       * @param {object} signals - Predefined signals to merge with.
+       * @returns {Promise<object>} Merged signals object.
+       */
+      ReadSignals: async function (signals) {
+        if (this.req.method === "GET") {
+          // Parse the URL
+          const parsedUrl = url.parse(this.req.url);
+          const parsedQuery = querystring.parse(parsedUrl.query);
+          const datastarParam = parsedQuery.datastar;
+          const query = JSON.parse(datastarParam);
+          return {
+            ...signals,
+            ...query,
+          };
+        } else {
+          const body = await new Promise((resolve, reject) => {
+            let chunks = "";
+            this.req.on("data", (chunk) => {
+              chunks += chunk;
+            });
+            this.req.on("end", () => {
+              console.log("No more data in response.");
+              resolve(chunks);
+            });
+          });
+          let parsedBody = {};
+          try {
+            parsedBody = JSON.parse(body);
+          } catch (err) {
+            console.error(
+              "Problem reading signals, could not parse body as JSON."
+            );
+          }
+          console.log("parsed Body", parsedBody);
+          return { ...signals, ...parsedBody };
+        }
+      },
+      /**
+       * @typedef {Object} MergeFragmentsOptions
+       * @property {string} [selector] - CSS selector affected.
+       * @property {string} [mergeMode="morph"] - Mode for merging.
+       * @property {number} [settleDuration=300] - Duration to settle.
+       * @property {?boolean} [useViewTransition=null] - Use view transition.
+       * @property {?string} [eventId=null] - Event ID to attach.
+       * @property {?number} [retryDuration=null] - Retry duration in milliseconds.
+       */
+      /**
+       * Sends a merge fragments event.
+       *
+       * @param {string[]} fragments - Array of fragment identifiers.
+       * @param {MergeFragmentsOptions} options - Additional options for merging.
+       * @throws Will throw an error if fragments are missing.
+       */
+      MergeFragments: function (
+        fragments,
+        options = {
+          selector: null,
+          mergeMode: "morph",
+          settleDuration: 300,
+          useViewTransition: null,
+          eventId: null,
+          retryDuration: null,
+        }
+      ) {
+        let dataLines = [];
+        if (options?.selector != null)
+          dataLines.push(`selector ${options.selector}`);
+        if (options?.settleDuration != null)
+          dataLines.push(`settleDuration ${options.settleDuration}`);
+        if (options?.useViewTransition != null)
+          dataLines.push(`useViewTransition ${options.useViewTransition}`);
+        if (fragments) {
+          if (typeof fragments === "string") {
+            // Handle case where 'fragments' is a string
+            dataLines.push(`fragments ${fragments.replace(/[\r\n]+/g, "")}`);
+          } else if (Array.isArray(fragments)) {
+            // Handle case where 'fragments' is an array
+            fragments.forEach((frag) => {
+              dataLines.push(`fragments ${frag.replace(/[\r\n]+/g, "")}`);
+            });
+          } else {
+            throw Error(
+              "Invalid type for fragments. Expected string or array."
+            );
+          }
+        } else {
+          throw Error("MergeFragments missing fragment(s).");
+        }
+        return this._send("datastar-merge-fragments", dataLines, {
+          eventId: options?.eventId,
+          retryDuration: options?.retryDuration,
+        });
+      },
+      /**
+       * @typedef {Object} RemoveFragmentsOptions
+       * @property {number} [settleDuration] - Duration to settle.
+       * @property {?boolean} [useViewTransition=null] - Use view transition.
+       * @property {?string} [eventId=null] - Event ID to attach.
+       * @property {?number} [retryDuration=null] - Retry duration in milliseconds.
+       */
+      /**
+       * Sends a remove fragments event.
+       *
+       * @param {string} selector - CSS selector of fragments to remove.
+       * @param {RemoveFragmentsOptions} options - Additional options for removing.
+       * @throws Will throw an error if selector is missing.
+       */
+      RemoveFragments: function (selector, options) {
+        let dataLines = [];
+        if (selector) {
+          dataLines.push(`selector ${selector}`);
+        } else {
+          throw Error("RemoveFragments missing selector.");
+        }
+        if (options?.settleDuration != null)
+          dataLines.push(`settleDuration ${options.settleDuration}`);
+        if (options?.useViewTransition != null)
+          dataLines.push(`useViewTransition ${options.useViewTransition}`);
+        return this._send(`datastar-remove-fragments`, dataLines, {
+          eventId: options?.eventId,
+          retryDuration: options?.retryDuration,
+        });
+      },
+      /**
+       * @typedef {Object} MergeSignalsOptions
+       * @property {boolean} [onlyIfMissing] - Merge only if signals are missing.
+       * @property {?string} [eventId=null] - Event ID to attach.
+       * @property {?number} [retryDuration=null] - Retry duration in milliseconds.
+       */
+      /**
+       * Sends a merge signals event.
+       *
+       * @param {object} signals - Signals to merge.
+       * @param {MergeSignalsOptions} options - Additional options for merging.
+       * @throws Will throw an error if signals are missing.
+       */
+      MergeSignals: function (signals, options) {
+        let dataLines = [];
+        if (options?.onlyIfMissing === true) {
+          dataLines.push(`onlyIfMissing true`);
+        }
+        if (signals) {
+          dataLines.push(`signals ${JSON.stringify(signals)}`);
+        } else {
+          throw Error("MergeSignals missing signals.");
+        }
+        return this._send(`datastar-merge-signals`, dataLines, {
+          eventId: options?.eventId,
+          retryDuration: options?.retryDuration,
+        });
+      },
+      /**
+       * Sends a remove signals event.
+       *
+       * @param {string[]} paths - Paths of signals to remove.
+       * @param {SendOptions} options - Additional options for removing signals.
+       * @throws Will throw an error if paths are missing.
+       */
+      RemoveSignals: function (paths, options) {
+        let dataLines = [];
+        if (paths) {
+          paths
+            .map((path) => {
+              dataLines.push(`paths ${path}`);
+            })
+            .join("");
+        } else {
+          throw Error("RemoveSignals missing paths");
+        }
+        return this._send(`datastar-remove-signals`, dataLines, {
+          eventId: options?.eventId,
+          retryDuration: options?.retryDuration,
+        });
+      },
+      /**
+       * @typedef {Object} ExecuteScriptOptions
+       * @property {boolean} [autoRemove] - Automatically remove the script after execution.
+       * @property {?string} [eventId=null] - Event ID to attach.
+       * @property {?number} [retryDuration=null] - Retry duration in milliseconds.
+       */
+      /**
+       * Executes a script on the client-side.
+       *
+       * @param {string} script - Script code to execute.
+       * @param {ExecuteScriptOptions} options - Additional options for execution.
+       */
+      ExecuteScript: function (script, options) {
+        let dataLines = [];
+        if (options?.autoRemove != null)
+          dataLines.push(`autoRemove ${options.autoRemove}`);
+        if (script) {
+          dataLines.push(`script ${script}`);
+        }
+        return this._send(`datastar-execute-script`, dataLines, {
+          eventId: options?.eventId,
+          retryDuration: options?.retryDuration,
+        });
+      },
+    };
+  },
+};

package/package.json ADDED Viewed

@@ -0,0 +1,31 @@
+{
+  "name": "datastar-ssegen",
+  "version": "0.0.1",
+  "description": "Datastar Server-Sent Event generator",
+  "author": "John Cudd",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "dev": "concurrently -c \"red,green,blue\" -n \"node,express,hyper-express\" \"npm run node\" \"npm run express\" \"npm run hyper-express\"",
+    "node": "nodemon examples/node.example.js",
+    "express": "nodemon examples/express.example.js",
+    "hyper-express": "nodemon examples/hyper-express.example.js"
+  },
+  "keywords": ["datastar", "hypermedia", "sse"],
+  "license": "mit",
+  "homepage": "https://github.com/jmcudd/datastar-ssegen#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmcudd/datastar-ssegen.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jmcudd/datastar-ssegen/issues"
+  },
+  "devdependencies": {
+    "concurrently": "^9.1.0",
+    "express": "^4.21.2",
+    "hyper-express": "^6.17.3",
+    "nodemon": "^3.1.9",
+    "npm-run-all": "^4.1.5"
+  }
+}