ghtml 1.0.0 → 1.1.0

package/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly

package/.github/workflows/ci.yml

@@ -1,6 +1,10 @@
 name: CI
 
 on:
+  push:
+    branches:
+      - main
+
   pull_request:
     branches:
       - main
@@ -9,9 +13,14 @@ jobs:
   test:
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        node-version: [^18, lts/*]
+
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: ^18
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
       - run: npm run test

package/README.md

@@ -0,0 +1,44 @@
+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).
+
+Inspired by [html-template-tag](https://github.com/AntonioVdlC/html-template-tag).
+
+## Installation
+
+```shell
+npm i ghtml
+```
+
+## API Reference
+
+The main export of the package is the `html` function that can be used to tag template literals and escape their expressions. To bypass escaping an expression, prefix it with `!`.
+
+Node.js users also have access to the `includeFile` function that reads and outputs the content of a file while caching it in memory for future use.
+
+## Usage
+
+```js
+import { html } from "ghtml";
+
+const username = '<img src="https://example.com/hacker.png">';
+const greeting = html`<h1>Hello, ${username}!</h1>`;
+
+console.log(greeting);
+// Output: <h1>Hello, &lt;img src=&quot;https://example.com/hacker.png&quot;&gt;</h1>
+
+const img = '<img src="https://example.com/safe.png">';
+const container = html`<div>!${img}</div>`;
+
+console.log(container);
+// Output: <div><img src="https://example.com/safe.png"></div>
+```
+
+The `includeFile` function returns the content of a file. Again, remember that it also caches the result, so any subsequent modifications to the same file won't be reflected until the app is restarted:
+
+```js
+import { includeFile } from "ghtml/includeFile.js";
+
+const logo = includeFile("static/logo.svg");
+
+console.log(logo);
+// Output: content of "static/logo.svg"
+```

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.0.0",
+  "version": "1.1.0",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -19,7 +19,7 @@
     "lint:fix": "eslint --fix . && prettier --write ."
   },
   "devDependencies": {
-    "grules": "^0.5.0"
+    "grules": "^0.12.1"
   },
   "repository": {
     "type": "git",

package/src/html.js

@@ -16,19 +16,14 @@ const escapeFunction = (key) => {
 };
 
 /**
- * @param {{ raw: string[] }} literals
- * @param {...any} expressions
- * @returns {string}
+ * @param {{ raw: string[] }} literals Tagged template literals.
+ * @param {...any} expressions Expressions to interpolate.
+ * @returns {string} The HTML string.
  */
 const html = (literals, ...expressions) => {
-  const lastLiteralIndex = literals.raw.length - 1;
   let accumulator = "";
 
-  if (lastLiteralIndex === -1) {
-    return accumulator;
-  }
-
-  for (let index = 0; index < lastLiteralIndex; ++index) {
+  for (let index = 0; index < expressions.length; ++index) {
     let literal = literals.raw[index];
     let expression =
       typeof expressions[index] === "string"
@@ -48,7 +43,7 @@ const html = (literals, ...expressions) => {
     accumulator += literal + expression;
   }
 
-  accumulator += literals.raw[lastLiteralIndex];
+  accumulator += literals.raw[expressions.length];
 
   return accumulator;
 };

package/src/includeFile.js

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
 
 const readFileSyncOptions = { encoding: "utf8" };
-
 const fileCache = new Map();
 
 /**
- * @param {string} path
- * @returns {string}
+ * @param {string} path The path to the file to render.
+ * @returns {string} The cached content of the file.
  */
 const includeFile = (path) => {
   let file = fileCache.get(path);

package/test/index.js

@@ -2,24 +2,24 @@ import test from "node:test";
 import assert from "node:assert";
 import { html } from "../src/index.js";
 
-const username = "G";
+const username = "Paul";
 const descriptionSafe = "This is a safe description.";
 const descriptionUnsafe =
   "<script>alert('This is an unsafe description.')</script>";
 const array1 = [1, 2, 3, 4, 5];
 const conditionTrue = true;
 const conditionFalse = false;
-const empty = "";
+const emptyString = "";
 
-test("renders correctly", () => {
-  assert.strictEqual(html({ raw: [] }, []), "");
+test("renders empty input", () => {
+  assert.strictEqual(html({ raw: [""] }), "");
 });
 
-test("renders correctly", () => {
-  assert.strictEqual(html`${empty}`, "");
+test("renders empty input", () => {
+  assert.strictEqual(html`${emptyString}`, "");
 });
 
-test("renders correctly", () => {
+test("renders normal input", () => {
   assert.strictEqual(html`Hey, ${username}!`, `Hey, ${username}!`);
 });
 
@@ -37,13 +37,6 @@ test("escapes unsafe output", () => {
   );
 });
 
-test("escapes unsafe output", () => {
-  assert.strictEqual(
-    html`<p>${descriptionUnsafe}</p>`,
-    `<p>&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;</p>`,
-  );
-});
-
 test("renders arrays", () => {
   assert.strictEqual(
     html`<p>${[descriptionSafe, descriptionUnsafe]}</p>`,
@@ -59,8 +52,8 @@ test("bypass escaping", () => {
 });
 
 test("renders wrapped html calls", () => {
+  // prettier-ignore
   assert.strictEqual(
-    // prettier-ignore
     html`<p>!${conditionTrue ? html`<strong>${descriptionUnsafe}</strong>` : ""}</p>`,
     "<p><strong>&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;</strong></p>",
   );
@@ -75,7 +68,6 @@ test("renders multiple html calls", () => {
         !${conditionFalse ? html`<em> ${array1} </em>` : ""}
       </p>
     `,
-    // it should be formatted
     `
       <p>
         <strong> This is a safe description. </strong>
@@ -89,26 +81,26 @@ test("renders multiple html calls", () => {
 test("renders multiple html calls with different expression types", () => {
   const obj = {};
   obj.toString = () => {
-    return "Description of the object.";
+    return "description of the object";
   };
 
+  // prettier-ignore
   assert.strictEqual(
     html`
       <p>
         !${conditionTrue ? html`<strong> ${descriptionSafe} </strong>` : ""}
         !${conditionFalse
           ? ""
-          : // prettier-ignore
+          :
             html`<em> ${array1.map((i) => {return i + 1;})} </em>`}<br />
-        And also, ${false} ${null}${undefined}${obj}
+        And also, ${false} ${null}${undefined}${obj} is ${true}
       </p>
     `,
-    // it should be formatted
     `
       <p>
         <strong> This is a safe description. </strong>
         <em> 23456 </em><br />
-        And also, false Description of the object.
+        And also, false description of the object is true
       </p>
     `,
   );