ghtml 1.2.4 → 1.5.0

package/.eslintrc.json

@@ -1,4 +1,7 @@
 {
   "root": true,
-  "extends": ["plugin:grules/all"]
+  "extends": ["plugin:grules/all"],
+  "rules": {
+    "no-await-in-loop": "off"
+  }
 }

package/.github/workflows/benchmark.yml

@@ -1,16 +1,16 @@
-name: Benchmark Comparison
+name: benchmark
+
+on:
+  pull_request_target:
+    types: [labeled]
 
 permissions:
   contents: read
   pull-requests: write
 
-on:
-  pull_request:
-    branches:
-      - main
-
 jobs:
-  benchmark-comparison:
+  benchmark:
+    if: ${{ github.event.label.name == 'benchmark' }}
     runs-on: ubuntu-latest
     steps:
       # Checkout PR code
@@ -25,11 +25,11 @@ jobs:
 
       # Install dependencies
       - name: Install dependencies
-        run: npm install
+        run: npm install --ignore-scripts
 
       # Run benchmark on PR code
       - name: Run benchmark on PR code
-        run: node bench/index.js
+        run: npm run benchmark
         id: benchmark_pr
 
       # Save PR benchmark results
@@ -55,7 +55,7 @@ jobs:
 
       # Run benchmark on main branch src with PR's benchmark tooling
       - name: Run benchmark on main branch src
-        run: node bench/index.js
+        run: npm run benchmark
         id: benchmark_main
 
       # Save main benchmark results
@@ -70,24 +70,31 @@ jobs:
           script: |
             const prResults = JSON.parse(Buffer.from(process.env.PR_RESULTS, 'base64').toString('utf8'));
             const mainResults = JSON.parse(Buffer.from(process.env.MAIN_RESULTS, 'base64').toString('utf8'));
-
             const commentBody = `
               Benchmark Results Comparison (${context.sha}):
-
               **PR Branch:**
               \`\`\`json
               ${JSON.stringify(prResults, null, 2)}
               \`\`\`
-
               **Main Branch:**
               \`\`\`json
               ${JSON.stringify(mainResults, null, 2)}
               \`\`\`
             `;
-
             github.rest.issues.createComment({
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
               body: commentBody
             });
+
+  remove-label:
+    needs: benchmark
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove benchmark label
+        uses: octokit/request-action@v2.x
+        with:
+          route: DELETE /repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/labels/benchmark
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/npm-test.yml

@@ -22,5 +22,5 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-      - run: npm install
+      - run: npm install --ignore-scripts
       - run: npm test

package/README.md

@@ -18,11 +18,13 @@ The `html` function is designed to tag template literals and automatically escap
 
 The `htmlGenerator` function acts as the generator version of the `html` function. It facilitates the creation of HTML fragments iteratively, making it ideal for parsing large templates or constructing HTML content dynamically.
 
-**Note:**
+### `htmlAsyncGenerator`
+
+This version of HTML generator should be preferred for asynchronous use cases. The output will be generated as the promise expressions resolve.
 
-A key difference of `htmlGenerator` is its ability to recognize and properly handle iterable elements within array expressions. This is to detect nested `htmlGenerator` usage, enabling scenarios such as ``[1,2,3].map(i => htmlGenerator`<li>${i}</li>`)``.
+**Note:**
 
-As a side effect, an expression like `${[[1, 2, 3], 4]}` (where an element is an array itself) will not be rendered as `"1,2,34"`, which is the case with `html`, but as `"1234"`. This is the intended behavior most of the time anyway.
+Because they return generators instead of strings, a key difference of `htmlGenerator` and `htmlAsyncGenerator` is their ability to recognize and properly handle iterable elements within array expressions. This is to detect nested `htmlGenerator` and `htmlAsyncGenerator` usage, enabling scenarios such as ``${[1, 2, 3].map(i => htmlGenerator`<li>${i}</li>`)}``.
 
 ### `includeFile`
 
@@ -82,12 +84,33 @@ const htmlString = html`
 ```js
 import { htmlGenerator as html } from "ghtml";
 import { Readable } from "node:stream";
+import http from "node:http";
+
+http
+  .createServer((req, res) => {
+    const htmlContent = html`<html>
+      <p>${"...HTML content..."}</p>
+    </html>`;
+    const readableStream = Readable.from(htmlContent);
+    res.writeHead(200, { "Content-Type": "text/html;charset=utf-8" });
+    readableStream.pipe(res);
+  })
+  .listen(3000);
+```
+
+### `htmlAsyncGenerator`
+
+```js
+import { htmlAsyncGenerator as html } from "ghtml";
+import { readFile } from "node:fs/promises";
+import { Readable } from "node:stream";
+import http from "node:http";
 
 http
   .createServer((req, res) => {
-    const htmlContent = htmlGenerator`<html>
-    <p>${"...HTML content..."}</p>
-  </html>`;
+    const htmlContent = html`<html>
+      <code>${readFile("./README.md")}</code>
+    </html>`;
     const readableStream = Readable.from(htmlContent);
     res.writeHead(200, { "Content-Type": "text/html;charset=utf-8" });
     readableStream.pipe(res);

package/bench/index.js

@@ -1,84 +1,67 @@
+/* eslint-disable no-unused-vars */
 /* eslint-disable no-unused-expressions */
 import { html } from "../src/index.js";
 import { Bench } from "tinybench";
 import { writeFileSync } from "node:fs";
 import { Buffer } from "node:buffer";
 
+let result = "";
 const bench = new Bench({ time: 500 });
 
-bench.add("Simple formatting", () => {
-  html`<div>Hello, world!</div>`;
+bench.add("simple HTML formatting", () => {
+  result = html`<div>Hello, world!</div>`;
+});
+
+bench.add("null and undefined expressions", () => {
+  result = html`<p>${null} and ${undefined}</p>`;
 });
 
 const username = "User";
-bench.add("Using string variable", () => {
-  html`<p>${username}</p>`;
+bench.add("string expressions", () => {
+  result = html`<p>${username} and ${username}</p>`;
 });
 
-const value = null;
-const undef = undefined;
-bench.add("Handling null and undefined", () => {
-  html`<p>${value} and ${undef}</p>`;
+const items1 = ["Item 1", undefined, "Item 2", null, 2000, 1500.5];
+bench.add("array expressions", () => {
+  result = html`<ul>
+    ${items1.map((item) => {
+      return html`<li>${item}</li>`;
+    })}
+  </ul>`;
 });
 
 const user = { id: 1, name: "John Doe" };
-bench.add("Multiple types of expressions", () => {
-  html`
+const items2 = ["Item 1", "Item 2", "Item 3"];
+bench.add("multiple types of expressions", () => {
+  result = html`
     ${undefined}
     <div>User: <span>${user.name}</span></div>
     <div>Id: <span>${user.id}</span></div>
-    ${null}
+    ${null}${123}${456n}
+    <ul>
+      !${items2.map((item) => {
+        return html`<li>${item}</li>`;
+      })}
+    </ul>
   `;
 });
 
-const items = ["Item 1", "Item 2", "Item 3"];
-bench.add("Arrays and iteration", () => {
-  html`<ul>
-    ${items.map((item) => {
-      return html`<li>${item}</li>`;
-    })}
-  </ul>`;
-});
-
-const items2 = ["Item 1", undefined, "Item 2", null, 2000];
-bench.add("Arrays and iteration with multiple types", () => {
-  html`<ul>
-    ${items2.map((item) => {
-      return html`<li>${item}</li>`;
-    })}
-  </ul>`;
-});
-
-const loggedIn = true;
-bench.add("Complex/nested expressions", () => {
-  html`<nav>
-    ${loggedIn
-      ? html`<a href="/logout">Logout</a>`
-      : html`<a href="/login">Login</a>`}
-  </nav>`;
-});
-
 const largeString = Array.from({ length: 1000 }).join("Lorem ipsum ");
-bench.add("Large strings", () => {
-  html`<p>${largeString}</p>`;
-});
-
-bench.add("High iteration count", () => {
-  for (let i = 0; i !== 1000; i++) {
-    html`<span>${i}</span>`;
-  }
+bench.add("large strings", () => {
+  result = html`<p>${largeString}${largeString}</p>`;
 });
 
 const scriptContent =
   "<script>console.log('This should not execute');</script>";
-bench.add("Escape HTML", () => {
-  html`<div>${scriptContent} ${scriptContent}</div>`;
+bench.add("high iteration count", () => {
+  for (let i = 0; i !== 100; i++) {
+    result = html`<span>${i}: ${scriptContent}</span>`;
+  }
 });
 
-// Render raw HTML
 const rawHTML = "<em>Italic</em> and <strong>bold</strong>";
 const markup = "<mark>Highlighted</mark>";
-bench.add("Unescaped expressions", () => {
+bench.add("unescaped expressions", () => {
   html`
     <div>!${rawHTML}</div>
     <div>!${rawHTML}</div>

package/package.json

@@ -3,7 +3,7 @@
   "description": "Replace your template engine with fast JavaScript by leveraging the power of tagged templates.",
   "author": "Gürgün Dayıoğlu",
   "license": "MIT",
-  "version": "1.2.4",
+  "version": "1.5.0",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -14,7 +14,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "npm run lint && c8 --100 node --test test/**",
+    "benchmark": "node bench/index.js",
+    "test": "npm run lint && c8 --100 node --test test/*.js",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write ."
   },

package/src/html.js

@@ -27,10 +27,10 @@ const html = ({ raw: literals }, ...expressions) => {
   for (; index !== expressions.length; ++index) {
     let literal = literals[index];
     let expression =
-      typeof expressions[index] === "string"
-        ? expressions[index]
-        : expressions[index] == null
-          ? ""
+      expressions[index] === undefined || expressions[index] === null
+        ? ""
+        : typeof expressions[index] === "string"
+          ? expressions[index]
           : Array.isArray(expressions[index])
             ? expressions[index].join("")
             : `${expressions[index]}`;
@@ -59,14 +59,14 @@ const htmlGenerator = function* ({ raw: literals }, ...expressions) {
     let literal = literals[index];
     let expression;
 
-    if (typeof expressions[index] === "string") {
-      expression = expressions[index];
-    } else if (expressions[index] == null) {
+    if (expressions[index] === undefined || expressions[index] === null) {
       expression = "";
+    } else if (typeof expressions[index] === "string") {
+      expression = expressions[index];
     } else {
       if (typeof expressions[index][Symbol.iterator] === "function") {
         const isRaw =
-          literal.length > 0 && literal.charCodeAt(literal.length - 1) === 33;
+          literal.length !== 0 && literal.charCodeAt(literal.length - 1) === 33;
 
         if (isRaw) {
           literal = literal.slice(0, -1);
@@ -77,20 +77,138 @@ const htmlGenerator = function* ({ raw: literals }, ...expressions) {
         }
 
         for (const value of expressions[index]) {
-          if (typeof value === "string") {
+          if (value === undefined || value === null) {
+            continue;
+          } else if (typeof value === "string") {
             expression = value;
-          } else if (value == null) {
-            expression = "";
-          } else if (typeof value[Symbol.iterator] === "function") {
-            expression = "";
-
-            for (const innerValue of value) {
-              if (innerValue != null) {
-                // At this level, we simply mirror Array.prototype.join
-                expression += innerValue;
+          } else {
+            if (typeof value[Symbol.iterator] === "function") {
+              for (const innerValue of value) {
+                if (innerValue === undefined || innerValue === null) {
+                  continue;
+                } else if (typeof innerValue === "string") {
+                  expression = innerValue;
+                } else {
+                  expression = `${innerValue}`;
+                }
+
+                if (expression.length) {
+                  if (!isRaw) {
+                    expression = expression.replace(
+                      escapeRegExp,
+                      escapeFunction,
+                    );
+                  }
+
+                  yield expression;
+                }
               }
+
+              continue;
+            }
+
+            expression = `${value}`;
+          }
+
+          if (expression.length) {
+            if (!isRaw) {
+              expression = expression.replace(escapeRegExp, escapeFunction);
             }
+
+            yield expression;
+          }
+        }
+
+        continue;
+      }
+
+      expression = `${expressions[index]}`;
+    }
+
+    if (literal.length && literal.charCodeAt(literal.length - 1) === 33) {
+      literal = literal.slice(0, -1);
+    } else if (expression.length) {
+      expression = expression.replace(escapeRegExp, escapeFunction);
+    }
+
+    if (literal.length || expression.length) {
+      yield literal + expression;
+    }
+  }
+
+  if (literals[index].length) {
+    yield literals[index];
+  }
+};
+
+/**
+ * @param {{ raw: string[] }} literals Tagged template literals.
+ * @param {...any} expressions Expressions to interpolate.
+ * @yields {string} The HTML strings.
+ */
+const htmlAsyncGenerator = async function* ({ raw: literals }, ...expressions) {
+  let index = 0;
+
+  for (; index !== expressions.length; ++index) {
+    let literal = literals[index];
+    let expression;
+
+    expressions[index] = await expressions[index];
+
+    if (expressions[index] === undefined || expressions[index] === null) {
+      expression = "";
+    } else if (typeof expressions[index] === "string") {
+      expression = expressions[index];
+    } else {
+      if (
+        typeof expressions[index][Symbol.iterator] === "function" ||
+        typeof expressions[index][Symbol.asyncIterator] === "function"
+      ) {
+        const isRaw =
+          literal.length !== 0 && literal.charCodeAt(literal.length - 1) === 33;
+
+        if (isRaw) {
+          literal = literal.slice(0, -1);
+        }
+
+        if (literal.length) {
+          yield literal;
+        }
+
+        for await (const value of expressions[index]) {
+          if (value === undefined || value === null) {
+            continue;
+          } else if (typeof value === "string") {
+            expression = value;
           } else {
+            if (
+              typeof value[Symbol.iterator] === "function" ||
+              typeof value[Symbol.asyncIterator] === "function"
+            ) {
+              for await (const innerValue of value) {
+                if (innerValue === undefined || innerValue === null) {
+                  continue;
+                } else if (typeof innerValue === "string") {
+                  expression = innerValue;
+                } else {
+                  expression = `${innerValue}`;
+                }
+
+                if (expression.length) {
+                  if (!isRaw) {
+                    expression = expression.replace(
+                      escapeRegExp,
+                      escapeFunction,
+                    );
+                  }
+
+                  yield expression;
+                }
+              }
+
+              continue;
+            }
+
             expression = `${value}`;
           }
 
@@ -125,4 +243,4 @@ const htmlGenerator = function* ({ raw: literals }, ...expressions) {
   }
 };
 
-export { html, htmlGenerator };
+export { html, htmlGenerator, htmlAsyncGenerator };

package/src/index.js

@@ -1 +1 @@
-export { html, htmlGenerator } from "./html.js";
+export { html, htmlGenerator, htmlAsyncGenerator } from "./html.js";

package/test/index.js

@@ -1,4 +1,6 @@
-import { html, htmlGenerator } from "../src/index.js";
+import { html, htmlGenerator, htmlAsyncGenerator } from "../src/index.js";
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import test from "node:test";
 import assert from "node:assert";
 
@@ -20,6 +22,17 @@ const generatorExample = function* () {
   yield "</p>";
 };
 
+const generatorPromiseExample = function* () {
+  yield [
+    new Promise((resolve) => {
+      resolve("<p>");
+    }),
+    null,
+    12n,
+  ];
+  yield;
+};
+
 test("renders empty input", () => {
   assert.strictEqual(html({ raw: [""] }), "");
 });
@@ -163,38 +176,186 @@ test("htmlGenerator works with nested htmlGenerator calls in an array", () => {
 
 test("htmlGenerator works with other generators", () => {
   const generator = htmlGenerator`<div>!${generatorExample()}</div>`;
-  assert.strictEqual(generator.next().value, "<div>");
-  assert.strictEqual(generator.next().value, "<p>");
-  assert.strictEqual(generator.next().value, "This is a safe description.");
+  let accumulator = "";
+
+  for (const value of generator) {
+    accumulator += value;
+  }
+
   assert.strictEqual(
-    generator.next().value,
-    "<script>alert('This is an unsafe description.')</script>",
+    accumulator,
+    "<div><p>This is a safe description.<script>alert('This is an unsafe description.')</script>12345255</p></div>",
   );
-  assert.strictEqual(generator.next().value, "12345");
-  assert.strictEqual(generator.next().value, "255");
-  assert.strictEqual(generator.next().value, "</p>");
-  assert.strictEqual(generator.next().value, "</div>");
   assert.strictEqual(generator.next().done, true);
 });
 
 test("htmlGenerator works with other generators within an array (raw)", () => {
   const generator = htmlGenerator`<div>!${[generatorExample()]}</div>`;
-  assert.strictEqual(generator.next().value, "<div>");
+  let accumulator = "";
+
+  for (const value of generator) {
+    accumulator += value;
+  }
+
   assert.strictEqual(
-    generator.next().value,
-    "<p>This is a safe description.<script>alert('This is an unsafe description.')</script>1,2,3,4,5255</p>",
+    accumulator,
+    "<div><p>This is a safe description.<script>alert('This is an unsafe description.')</script>1,2,3,4,5255</p></div>",
   );
-  assert.strictEqual(generator.next().value, "</div>");
   assert.strictEqual(generator.next().done, true);
 });
 
 test("htmlGenerator works with other generators within an array (escaped)", () => {
   const generator = htmlGenerator`<div>${[generatorExample()]}</div>`;
-  assert.strictEqual(generator.next().value, "<div>");
+  let accumulator = "";
+
+  for (const value of generator) {
+    accumulator += value;
+  }
+
   assert.strictEqual(
-    generator.next().value,
-    "&lt;p&gt;This is a safe description.&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;1,2,3,4,5255&lt;/p&gt;",
+    accumulator,
+    "<div>&lt;p&gt;This is a safe description.&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;1,2,3,4,5255&lt;/p&gt;</div>",
   );
-  assert.strictEqual(generator.next().value, "</div>");
   assert.strictEqual(generator.next().done, true);
 });
+
+test("htmlAsyncGenerator renders safe content", async () => {
+  const generator = htmlAsyncGenerator`<p>${descriptionSafe}!${descriptionUnsafe}G!${htmlAsyncGenerator`${array1}`}!${null}${255}</p>`;
+  let accumulator = "";
+
+  for await (const value of generator) {
+    accumulator += value;
+  }
+
+  assert.strictEqual(
+    accumulator,
+    "<p>This is a safe description.<script>alert('This is an unsafe description.')</script>G12345255</p>",
+  );
+});
+
+test("htmlAsyncGenerator renders unsafe content", async () => {
+  const generator = htmlAsyncGenerator`<p>${descriptionSafe}${descriptionUnsafe}${htmlAsyncGenerator`${array1}`}${null}${255}</p>`;
+  let accumulator = "";
+
+  for await (const value of generator) {
+    accumulator += value;
+  }
+
+  assert.strictEqual(
+    accumulator,
+    "<p>This is a safe description.&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;12345255</p>",
+  );
+});
+
+test("htmlAsyncGenerator works with nested htmlAsyncGenerator calls in an array", async () => {
+  const generator = htmlAsyncGenerator`!${[1, 2, 3].map((i) => {
+    return htmlAsyncGenerator`${i}: <p>${readFile("test/test.md", "utf8")}</p>`;
+  })}`;
+  let accumulator = "";
+
+  for await (const value of generator) {
+    accumulator += value;
+  }
+
+  assert.strictEqual(
+    accumulator.replaceAll("\n", "").trim(),
+    "1: <p># test.md&gt;</p>2: <p># test.md&gt;</p>3: <p># test.md&gt;</p>",
+  );
+});
+
+test("htmlAsyncGenerator renders chunks with promises (escaped)", async () => {
+  const generator = htmlAsyncGenerator`<ul>!${[1, 2].map((i) => {
+    return htmlAsyncGenerator`${i}: ${readFile("test/test.md", "utf8")}`;
+  })}</ul>`;
+  const fileContent = readFileSync("test/test.md", "utf8").replaceAll(
+    ">",
+    "&gt;",
+  );
+
+  let value = await generator.next();
+  assert.strictEqual(value.value, "<ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `1`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `: ${fileContent}`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `2`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `: ${fileContent}`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "</ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.done, true);
+});
+
+test("htmlAsyncGenerator renders chunks with promises (raw)", async () => {
+  const generator = htmlAsyncGenerator`<ul>!${[1, 2].map((i) => {
+    return htmlAsyncGenerator`${i}: !${readFile("test/test.md", "utf8")}`;
+  })}</ul>`;
+  const fileContent = readFileSync("test/test.md", "utf8");
+
+  let value = await generator.next();
+  assert.strictEqual(value.value, "<ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `1`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `: ${fileContent}`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `2`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, `: ${fileContent}`);
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "</ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.done, true);
+});
+
+test("htmlAsyncGenerator redners in chuncks", async () => {
+  const generator = htmlAsyncGenerator`<ul>${generatorPromiseExample()}</ul>`;
+
+  let value = await generator.next();
+  assert.strictEqual(value.value, "<ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "&lt;p&gt;");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "12");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "</ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.done, true);
+});
+
+test("htmlAsyncGenerator redners in chuncks (raw)", async () => {
+  const generator = htmlAsyncGenerator`<ul>!${generatorPromiseExample()}</ul>`;
+
+  let value = await generator.next();
+  assert.strictEqual(value.value, "<ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "<p>");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "12");
+
+  value = await generator.next();
+  assert.strictEqual(value.value, "</ul>");
+
+  value = await generator.next();
+  assert.strictEqual(value.done, true);
+});

package/test/test.md

@@ -0,0 +1 @@
+# test.md>