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

datastar-ssegen 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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"
+  }
+}