ghtml 2.2.1 → 3.0.0

package/.eslintrc.json

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

package/README.md

@@ -1,6 +1,10 @@
-ta**ghtml** lets you replace your template engine with fast JavaScript by leveraging the power of [tagged templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
+# ghtml ![img.shields.io/bundlephobia/minzip/ghtml](https://img.shields.io/bundlephobia/minzip/ghtml)
 
-Inspired by [html-template-tag](https://github.com/AntonioVdlC/html-template-tag).
+ta**ghtml** lets you replace your template engine with fast JavaScript by leveraging the power of tagged templates.
+
+Works in the browser. No runtime dependencies. [~30x faster than React. ~10x faster than common-tags.](#benchmarks)
+
+![ghtml.gif](./ghtml.gif)
 
 ## Installation
 
@@ -8,6 +12,12 @@ Inspired by [html-template-tag](https://github.com/AntonioVdlC/html-template-tag
 npm i ghtml
 ```
 
+Or import directly from a CDN:
+
+```js
+import { html } from "https://cdn.jsdelivr.net/npm/ghtml/+esm";
+```
+
 ## API
 
 ### `html`
@@ -32,7 +42,7 @@ Because they return generators instead of strings, a key difference of `htmlGene
 
 ### `includeFile`
 
-Available in Node.js, the `includeFile` function is a wrapper around `readFileSync`. It reads and returns the content of a file while also caching it in memory for faster future reuse.
+Available in Node.js, the `includeFile` function is a wrapper around `readFileSync`. It reads and returns the content of a file while caching it in memory for faster future reuse.
 
 ## Usage
 
@@ -45,7 +55,7 @@ const username = '<img src="https://example.com/pwned.png">';
 const greeting = html`<h1>Hello, ${username}</h1>`;
 
 console.log(greeting);
-// Output: <h1>Hello, &#60;img src=&#34;https://example.com/pwned.png&#34;&#62;</h1>
+// Output: <h1>Hello, &#60;img src&#61;&#34;https://example.com/pwned.png&#34;&#62;</h1>
 ```
 
 To bypass escaping:
@@ -169,6 +179,38 @@ console.log(logo);
 // Output: content of "static/logo.svg"
 ```
 
+## Benchmarks
+
+Latest results [from Kita](https://github.com/kitajs/html/tree/cb7950c68489ff70dd0b0c130c9b70046c1543ea/benchmarks):
+
+```sh
+benchmark        time (avg)             (min … max)       p75       p99      p999
+--------------------------------------------------- -----------------------------
+• Real World Scenario
+--------------------------------------------------- -----------------------------
+KitaJS/Html     505 µs/iter     (387 µs … 2'007 µs)    417 µs  1'209 µs  1'857 µs
+Typed Html    1'844 µs/iter   (1'604 µs … 2'415 µs)  2'088 µs  2'211 µs  2'415 µs
+VHtml         2'424 µs/iter   (2'250 µs … 2'864 µs)  2'462 µs  2'829 µs  2'864 µs
+React JSX     6'416 µs/iter   (5'893 µs … 9'399 µs)  6'840 µs  9'399 µs  9'399 µs
+Preact          970 µs/iter     (673 µs … 5'038 µs)    766 µs  2'224 µs  5'038 µs
+React         6'319 µs/iter   (5'885 µs … 7'306 µs)  6'678 µs  7'306 µs  7'306 µs
+Common Tags   2'967 µs/iter   (2'774 µs … 3'801 µs)  2'916 µs  3'794 µs  3'801 µs
+Ghtml           225 µs/iter     (184 µs … 1'567 µs)    206 µs  1'066 µs  1'450 µs
+JSXTE         4'489 µs/iter   (3'605 µs … 6'215 µs)  4'517 µs  6'062 µs  6'215 µs
+
+
+summary for Real World Scenario
+  Ghtml
+   2.25x faster than KitaJS/Html
+   4.32x faster than Preact
+   8.21x faster than Typed Html
+   10.8x faster than VHtml
+   13.22x faster than Common Tags
+   20x faster than JSXTE
+   28.15x faster than React
+   28.58x faster than React JSX
+```
+
 ## Security
 
-Like [similar](https://github.com/mde/ejs/blob/main/SECURITY.md#out-of-scope-vulnerabilities) [tools](https://handlebarsjs.com/guide/#html-escaping), ghtml does not prevent all kinds of XSS attacks. It is the responsibility of developers to sanitize user inputs. Some inherently insecure uses include dynamically generating JavaScript, failing to quote HTML attribute values (especially when they contain expressions), and relying on unsanitized user-provided URLs.
+Like [similar tools](https://github.com/mde/ejs/blob/a4770b8ff49b93387c7f2760d957446cd332531a/SECURITY.md#out-of-scope-vulnerabilities), ghtml does not prevent all kinds of XSS attacks. It is the responsibility of developers to sanitize user inputs. Some inherently insecure uses include dynamically generating JavaScript, failing to quote HTML attribute values, and relying on unsanitized user-provided URIs.

package/SECURITY.md

@@ -5,7 +5,8 @@
 | Version | Supported          |
 | ------- | ------------------ |
 | ^1      | :x:                |
-| ^2      | :white_check_mark: |
+| ^2      | :x:                |
+| ^3      | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

package/bench/index.js

@@ -1,5 +1,4 @@
 /* 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";
@@ -8,7 +7,6 @@ import { Buffer } from "node:buffer";
 let result = "";
 const bench = new Bench({ time: 500 });
 
-// Simple cases
 bench.add("simple HTML formatting", () => {
   result = html`<div>Hello, world!</div>`;
 });
@@ -17,7 +15,6 @@ bench.add("null and undefined expressions", () => {
   result = html`<p>${null} and ${undefined}</p>`;
 });
 
-// String expressions
 const username = "User";
 bench.add("single string expression", () => {
   result = html`<p>${username}</p>`;
@@ -27,7 +24,6 @@ bench.add("multiple string expressions", () => {
   result = html`<p>${username} and ${username}</p>`;
 });
 
-// Array expressions
 const items1 = ["Item 1", undefined, "Item 2", null, 2000, 1500.5];
 bench.add("array expressions", () => {
   result = html`<ul>
@@ -46,7 +42,6 @@ bench.add("array expressions with escapable chars", () => {
   </ul>`;
 });
 
-// Object expressions
 const user = { id: 1, name: "John Doe" };
 bench.add("object expressions", () => {
   result = html`
@@ -55,7 +50,6 @@ bench.add("object expressions", () => {
   `;
 });
 
-// Mixed expressions
 bench.add("multiple types of expressions", () => {
   result = html`
     ${undefined}
@@ -70,17 +64,15 @@ bench.add("multiple types of expressions", () => {
   `;
 });
 
-// Large strings
 const largeString = Array.from({ length: 1000 }).join("Lorem ipsum ");
 bench.add("large strings", () => {
   result = html`<p>${largeString}${largeString}</p>`;
 });
 
-// Escaped and unescaped expressions
 const rawHTML = "<em>Italic</em> and <strong>bold</strong>";
 const markup = "<mark>Highlighted</mark>";
 bench.add("unescaped expressions", () => {
-  html`
+  result = html`
     <div>!${rawHTML}</div>
     <div>!${rawHTML}</div>
     <div>!${markup}</div>
@@ -91,7 +83,7 @@ bench.add("unescaped expressions", () => {
 });
 
 bench.add("escaped expressions", () => {
-  html`
+  result = html`
     <div>${rawHTML}</div>
     <div>${rawHTML}</div>
     <div>${markup}</div>
@@ -102,7 +94,7 @@ bench.add("escaped expressions", () => {
 });
 
 bench.add("mixed escaped and unescaped expressions", () => {
-  html`
+  result = html`
     <div>!${rawHTML}</div>
     <div>!${rawHTML}</div>
     <div>${markup}</div>

package/bin/README.md

@@ -1,4 +1,4 @@
-Lets you append unique hashes to assets referenced in your views to aggressively cache them while guaranteeing that clients receive the most recent versions.
+Append unique hashes to assets referenced in your views to aggressively cache them while guaranteeing that clients receive the most recent versions.
 
 ## Usage
 
@@ -27,7 +27,7 @@ Add the `ghtml` command to the build script:
 
 ```json
 "scripts": {
-  "build": "npx ghtml --roots=assets/ --refs=views/,routes/",
+  "build": "npx ghtml --roots=assets/ --refs=views/,routes/ --prefix=/p/assets/",
 },
 ```
 

package/bin/example/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "require-await": "off",
+    "n/no-missing-import": "off"
+  }
+}

package/bin/example/package.json

@@ -3,7 +3,7 @@
   "main": "./server.js",
   "scripts": {
     "start": "node server.js",
-    "build": "ghtml --roots=assets/ --refs=routes/"
+    "build": "ghtml --roots=assets/ --refs=routes/ --prefix=/p/assets/"
   },
   "dependencies": {
     "@fastify/static": "^7.0.1",

package/bin/example/routes/index.js

@@ -1,5 +1,3 @@
-/* eslint-disable n/no-missing-import */
-
 import { html } from "ghtml";
 
 export default async (fastify) => {

package/bin/example/server.js

@@ -1,5 +1,3 @@
-/* eslint-disable n/no-missing-import */
-
 import Fastify from "fastify";
 
 const fastify = Fastify();

package/bin/src/index.js

@@ -1,41 +1,45 @@
 #!/usr/bin/env node
-
 import { generateHashesAndReplace } from "./utils.js";
 import process from "node:process";
 
 const parseArguments = (args) => {
   let roots = null;
   let refs = null;
+  let prefix = "/";
 
   for (const arg of args) {
     if (arg.startsWith("--roots=")) {
       roots = arg.split("=", 2)[1].split(",");
     } else if (arg.startsWith("--refs=")) {
       refs = arg.split("=", 2)[1].split(",");
+    } else if (arg.startsWith("--prefix=")) {
+      prefix = arg.split("=", 2)[1];
     }
   }
 
   if (!roots || !refs) {
     console.error(
-      'Usage: npx ghtml --roots="path/to/scan/assets1/,path/to/scan/assets2/" --refs="views/path/to/append/hashes1/,views/path/to/append/hashes2/"',
+      'Usage: npx ghtml --roots="base/path/to/scan/assets/1/,base/path/to/scan/assets/2/" --refs="views/path/to/append/hashes/1/,views/path/to/append/hashes/2/" [--prefix="/optional/prefix/"]',
     );
     process.exit(1);
   }
 
-  return { roots, refs };
+  return { roots, refs, prefix };
 };
 
 const main = async () => {
-  const { roots, refs } = parseArguments(process.argv.slice(2));
+  const { roots, refs, prefix } = parseArguments(process.argv.slice(2));
 
   try {
     console.warn(`Generating hashes and updating file paths...`);
     console.warn(`Scanning files in: ${roots}`);
     console.warn(`Updating files in: ${refs}`);
+    console.warn(`Using prefix: ${prefix}`);
 
     await generateHashesAndReplace({
       roots,
       refs,
+      prefix,
     });
 
     console.warn("Hash generation and file updates completed successfully.");

package/bin/src/utils.js

@@ -1,7 +1,7 @@
+import { Glob } from "glob";
 import { createHash } from "node:crypto";
 import { readFile, writeFile } from "node:fs/promises";
 import { win32, posix } from "node:path";
-import { Glob } from "glob";
 
 const generateFileHash = async (filePath) => {
   try {
@@ -18,6 +18,7 @@ const generateFileHash = async (filePath) => {
 const updateFilePathsWithHashes = async (
   fileHashes,
   refs,
+  prefix,
   includeDotFiles,
   skipPatterns,
 ) => {
@@ -40,14 +41,15 @@ const updateFilePathsWithHashes = async (
       let content = await readFile(filePath, "utf8");
       let found = false;
 
-      for (const [originalPath, hash] of fileHashes) {
-        const escapedPath = originalPath.replace(
-          /[$()*+.?[\\\]^{|}]/gu,
-          "\\$&",
+      for (const [path, hash] of fileHashes) {
+        const fullPath = prefix + path;
+        const escapedPath = fullPath.replace(
+          /[$()*+.?[\\\]^{|}]/g,
+          String.raw`\$&`,
         );
         const regex = new RegExp(
           `(?<path>${escapedPath})(\\?(?<queryString>[^#"'\`]*))?`,
-          "gu",
+          "g",
         );
 
         content = content.replace(
@@ -75,6 +77,7 @@ const updateFilePathsWithHashes = async (
 const generateHashesAndReplace = async ({
   roots,
   refs,
+  prefix,
   includeDotFiles = false,
   skipPatterns = ["**/node_modules/**"],
 }) => {
@@ -116,6 +119,7 @@ const generateHashesAndReplace = async ({
   await updateFilePathsWithHashes(
     fileHashes,
     refs,
+    prefix,
     includeDotFiles,
     skipPatterns,
   );

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": "2.2.1",
+  "version": "3.0.0",
   "type": "module",
   "bin": "./bin/src/index.js",
   "main": "./src/index.js",
@@ -26,7 +26,7 @@
   "devDependencies": {
     "@fastify/pre-commit": "^2.1.0",
     "c8": "^10.1.2",
-    "grules": "^0.17.3",
+    "grules": "^0.23.0",
     "tinybench": "^2.8.0"
   },
   "repository": {

package/src/html.js

@@ -1,4 +1,4 @@
-const escapeRegExp = /["&'<>`]/;
+const escapeRegExp = /["&'<=>]/;
 
 const escapeFunction = (string) => {
   let escaped = "";
@@ -22,18 +22,18 @@ const escapeFunction = (string) => {
         escaped += string.slice(start, end) + "&#60;";
         start = end + 1;
         continue;
-      case 62: // >
-        escaped += string.slice(start, end) + "&#62;";
+      case 61: // =
+        escaped += string.slice(start, end) + "&#61;";
         start = end + 1;
         continue;
-      case 96: // `
-        escaped += string.slice(start, end) + "&#96;";
+      case 62: // >
+        escaped += string.slice(start, end) + "&#62;";
         start = end + 1;
         continue;
     }
   }
 
-  escaped += string.slice(start, string.length);
+  escaped += string.slice(start);
 
   return escaped;
 };
@@ -47,16 +47,15 @@ const html = ({ raw: literals }, ...expressions) => {
   let accumulator = "";
 
   for (let i = 0; i !== expressions.length; ++i) {
-    const expression = expressions[i];
     let literal = literals[i];
     let string =
-      typeof expression === "string"
-        ? expression
-        : expression == null
+      typeof expressions[i] === "string"
+        ? expressions[i]
+        : expressions[i] == null
           ? ""
-          : Array.isArray(expression)
-            ? expression.join("")
-            : `${expression}`;
+          : Array.isArray(expressions[i])
+            ? expressions[i].join("")
+            : `${expressions[i]}`;
 
     if (literal && literal.charCodeAt(literal.length - 1) === 33) {
       literal = literal.slice(0, -1);

package/test/index.js

@@ -66,7 +66,15 @@ test("renders unsafe content", () => {
 test("renders unsafe content /2", () => {
   assert.strictEqual(
     html`<p>${`${descriptionUnsafe}"&\``}</p>`,
-    `<p>&#60;script&#62;alert(&#39;This is an unsafe description.&#39;)&#60;/script&#62;&#34;&#38;&#96;</p>`,
+    `<p>&#60;script&#62;alert(&#39;This is an unsafe description.&#39;)&#60;/script&#62;&#34;&#38;\`</p>`,
+  );
+});
+
+test("renders unsafe content /3", () => {
+  // prettier-ignore
+  assert.strictEqual(
+    html`<img src="https://picsum.photos/200/300" alt=${"altText onload=alert(String.fromCharCode(112,119,110,101,100))"} />`,
+    `<img src="https://picsum.photos/200/300" alt=altText onload&#61;alert(String.fromCharCode(112,119,110,101,100)) />`,
   );
 });