ghtml 1.0.1 → 1.2.0

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 (6) hide show
  1. package/README.md +61 -3
  2. package/package.json +3 -2
  3. package/src/html.js +83 -11
  4. package/src/includeFile.js +2 -2
  5. package/src/index.js +1 -1
  6. package/test/index.js +56 -3
package/README.md CHANGED
@@ -10,12 +10,22 @@ npm i ghtml
10
10
 
11
11
  ## API Reference
12
12
 
13
- 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 `!`.
13
+ ### `html`
14
14
 
15
- 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.
15
+ The `html` function is used to tag template literals and escape their expressions. To bypass escaping an expression, prefix it with `!`.
16
+
17
+ ### `htmlGenerator`
18
+
19
+ The `htmlGenerator` function is the generator version of the `html` function. It allows for the generation of HTML fragments in a streaming manner, which can be particularly useful for large templates or when generating HTML on-the-fly.
20
+
21
+ ### `includeFile`
22
+
23
+ Available for Node.js users, the `includeFile` function is a wrapper around `readFileSync`. It reads and outputs the content of a file while also caching it in memory for faster future reuse.
16
24
 
17
25
  ## Usage
18
26
 
27
+ ### `html`
28
+
19
29
  ```js
20
30
  import { html } from "ghtml";
21
31
 
@@ -24,7 +34,11 @@ const greeting = html`<h1>Hello, ${username}!</h1>`;
24
34
 
25
35
  console.log(greeting);
26
36
  // Output: <h1>Hello, &lt;img src=&quot;https://example.com/hacker.png&quot;&gt;</h1>
37
+ ```
27
38
 
39
+ To bypass escaping:
40
+
41
+ ```js
28
42
  const img = '<img src="https://example.com/safe.png">';
29
43
  const container = html`<div>!${img}</div>`;
30
44
 
@@ -32,7 +46,51 @@ console.log(container);
32
46
  // Output: <div><img src="https://example.com/safe.png"></div>
33
47
  ```
34
48
 
35
- 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:
49
+ When nesting multiple `html` expressions, always use `!` as they will do their own escaping:
50
+
51
+ ```js
52
+ const someCondition = Math.random() >= 0.5;
53
+ const data = {
54
+ username: "John",
55
+ age: 21,
56
+ };
57
+
58
+ const htmlString = html`
59
+ <div>
60
+ !${someCondition
61
+ ? html`
62
+ <p>Data:</p>
63
+ <ul>
64
+ ${Object.values(data).map(
65
+ ([key, val]) => `
66
+ ${key}: ${val}
67
+ `,
68
+ )}
69
+ </ul>
70
+ `
71
+ : "<p>No data...</p>"}
72
+ </div>
73
+ `;
74
+ ```
75
+
76
+ ### `htmlGenerator`
77
+
78
+ ```js
79
+ import { htmlGenerator as html } from "ghtml";
80
+ import { Readable } from "node:stream";
81
+
82
+ const htmlContent = html`<html>
83
+ <p>${"...your HTML content..."}</p>
84
+ </html>`;
85
+ const readableStream = Readable.from(htmlContent);
86
+
87
+ http.createServer((req, res) => {
88
+ res.writeHead(200, { "Content-Type": "text/html;charset=utf-8" });
89
+ readableStream.pipe(res);
90
+ });
91
+ ```
92
+
93
+ ### `includeFile`
36
94
 
37
95
  ```js
38
96
  import { includeFile } from "ghtml/includeFile.js";
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "Replace your template engine with fast JavaScript by leveraging the power of tagged templates.",
4
4
  "author": "Gürgün Dayıoğlu",
5
5
  "license": "MIT",
6
- "version": "1.0.1",
6
+ "version": "1.2.0",
7
7
  "type": "module",
8
8
  "main": "./src/index.js",
9
9
  "exports": {
@@ -19,7 +19,8 @@
19
19
  "lint:fix": "eslint --fix . && prettier --write ."
20
20
  },
21
21
  "devDependencies": {
22
- "grules": "^0.5.0"
22
+ "@fastify/pre-commit": "^2.1.0",
23
+ "grules": "^0.13.0"
23
24
  },
24
25
  "repository": {
25
26
  "type": "git",
package/src/html.js CHANGED
@@ -16,19 +16,15 @@ const escapeFunction = (key) => {
16
16
  };
17
17
 
18
18
  /**
19
- * @param {{ raw: string[] }} literals
20
- * @param {...any} expressions
21
- * @returns {string}
19
+ * @param {{ raw: string[] }} literals Tagged template literals.
20
+ * @param {...any} expressions Expressions to interpolate.
21
+ * @returns {string} The HTML string.
22
22
  */
23
23
  const html = (literals, ...expressions) => {
24
- const lastLiteralIndex = literals.raw.length - 1;
25
24
  let accumulator = "";
25
+ let index = 0;
26
26
 
27
- if (lastLiteralIndex === -1) {
28
- return accumulator;
29
- }
30
-
31
- for (let index = 0; index < lastLiteralIndex; ++index) {
27
+ while (index < expressions.length) {
32
28
  let literal = literals.raw[index];
33
29
  let expression =
34
30
  typeof expressions[index] === "string"
@@ -46,11 +42,87 @@ const html = (literals, ...expressions) => {
46
42
  }
47
43
 
48
44
  accumulator += literal + expression;
45
+ ++index;
49
46
  }
50
47
 
51
- accumulator += literals.raw[lastLiteralIndex];
48
+ accumulator += literals.raw[index];
52
49
 
53
50
  return accumulator;
54
51
  };
55
52
 
56
- export { html };
53
+ /**
54
+ * @param {{ raw: string[] }} literals Tagged template literals.
55
+ * @param {...any} expressions Expressions to interpolate.
56
+ * @yields {string} The HTML strings.
57
+ */
58
+ const htmlGenerator = function* (literals, ...expressions) {
59
+ let index = 0;
60
+
61
+ while (index < expressions.length) {
62
+ let literal = literals.raw[index];
63
+ let expression;
64
+
65
+ if (typeof expressions[index] === "string") {
66
+ expression = expressions[index];
67
+ } else if (expressions[index] == null) {
68
+ expression = "";
69
+ } else if (Array.isArray(expressions[index])) {
70
+ expression = expressions[index].join("");
71
+ } else {
72
+ if (typeof expressions[index][Symbol.iterator] === "function") {
73
+ const isRaw =
74
+ literal.length > 0 && literal.charCodeAt(literal.length - 1) === 33;
75
+
76
+ if (isRaw) {
77
+ literal = literal.slice(0, -1);
78
+ }
79
+
80
+ if (literal.length) {
81
+ yield literal;
82
+ }
83
+
84
+ for (const value of expressions[index]) {
85
+ expression =
86
+ typeof value === "string"
87
+ ? value
88
+ : value == null
89
+ ? ""
90
+ : Array.isArray(value)
91
+ ? value.join("")
92
+ : `${value}`;
93
+
94
+ if (expression.length) {
95
+ if (!isRaw) {
96
+ expression = expression.replace(escapeRegExp, escapeFunction);
97
+ }
98
+
99
+ yield expression;
100
+ }
101
+ }
102
+
103
+ ++index;
104
+ continue;
105
+ }
106
+
107
+ expression = `${expressions[index]}`;
108
+ }
109
+
110
+ if (literal.length && literal.charCodeAt(literal.length - 1) === 33) {
111
+ literal = literal.slice(0, -1);
112
+ } else if (expression.length) {
113
+ expression = expression.replace(escapeRegExp, escapeFunction);
114
+ }
115
+
116
+ if (literal.length || expression.length) {
117
+ yield literal + expression;
118
+ }
119
+
120
+ ++index;
121
+ }
122
+
123
+ if (literals.raw[index].length) {
124
+ yield literals.raw[index];
125
+ }
126
+ };
127
+
128
+ export { html, htmlGenerator };
package/src/includeFile.js CHANGED
@@ -5,8 +5,8 @@ const readFileSyncOptions = { encoding: "utf8" };
5
5
  const fileCache = new Map();
6
6
 
7
7
  /**
8
- * @param {string} path
9
- * @returns {string}
8
+ * @param {string} path The path to the file to render.
9
+ * @returns {string} The cached content of the file.
10
10
  */
11
11
  const includeFile = (path) => {
12
12
  let file = fileCache.get(path);
package/src/index.js CHANGED
@@ -1 +1 @@
1
- export { html } from "./html.js";
1
+ export { html, htmlGenerator } from "./html.js";
package/test/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import test from "node:test";
2
2
  import assert from "node:assert";
3
- import { html } from "../src/index.js";
3
+ import { html, htmlGenerator } from "../src/index.js";
4
4
 
5
5
  const username = "Paul";
6
6
  const descriptionSafe = "This is a safe description.";
@@ -11,8 +11,18 @@ const conditionTrue = true;
11
11
  const conditionFalse = false;
12
12
  const emptyString = "";
13
13
 
14
+ const generatorExample = function* () {
15
+ yield "<p>";
16
+ yield descriptionSafe;
17
+ yield descriptionUnsafe;
18
+ yield array1;
19
+ yield null;
20
+ yield 255;
21
+ yield "</p>";
22
+ };
23
+
14
24
  test("renders empty input", () => {
15
- assert.strictEqual(html({ raw: [] }), "");
25
+ assert.strictEqual(html({ raw: [""] }), "");
16
26
  });
17
27
 
18
28
  test("renders empty input", () => {
@@ -30,7 +40,7 @@ test("renders safe content", () => {
30
40
  );
31
41
  });
32
42
 
33
- test("escapes unsafe output", () => {
43
+ test("escapes unsafe content", () => {
34
44
  assert.strictEqual(
35
45
  html`<p>${descriptionUnsafe}</p>`,
36
46
  `<p>&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;</p>`,
@@ -105,3 +115,46 @@ test("renders multiple html calls with different expression types", () => {
105
115
  `,
106
116
  );
107
117
  });
118
+
119
+ test("htmlGenerator renders safe content", () => {
120
+ const generator = htmlGenerator`<p>${descriptionSafe}!${descriptionSafe}G!${htmlGenerator`${array1}`}!${null}${255}</p>`;
121
+ assert.strictEqual(generator.next().value, "<p>This is a safe description.");
122
+ assert.strictEqual(generator.next().value, "This is a safe description.");
123
+ assert.strictEqual(generator.next().value, "G");
124
+ assert.strictEqual(generator.next().value, "12345");
125
+ assert.strictEqual(generator.next().value, "255");
126
+ assert.strictEqual(generator.next().value, "</p>");
127
+ assert.strictEqual(generator.next().done, true);
128
+ });
129
+
130
+ test("htmlGenerator escapes unsafe content", () => {
131
+ const generator = htmlGenerator`<p>${descriptionUnsafe}${descriptionUnsafe}${htmlGenerator`${array1}`}${null}${255}</p>`;
132
+ assert.strictEqual(
133
+ generator.next().value,
134
+ "<p>&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;",
135
+ );
136
+ assert.strictEqual(
137
+ generator.next().value,
138
+ "&lt;script&gt;alert(&apos;This is an unsafe description.&apos;)&lt;/script&gt;",
139
+ );
140
+ assert.strictEqual(generator.next().value, "12345");
141
+ assert.strictEqual(generator.next().value, "255");
142
+ assert.strictEqual(generator.next().value, "</p>");
143
+ assert.strictEqual(generator.next().done, true);
144
+ });
145
+
146
+ test("htmlGenerator works with other generators", () => {
147
+ const generator = htmlGenerator`<div>!${generatorExample()}</div>`;
148
+ assert.strictEqual(generator.next().value, "<div>");
149
+ assert.strictEqual(generator.next().value, "<p>");
150
+ assert.strictEqual(generator.next().value, "This is a safe description.");
151
+ assert.strictEqual(
152
+ generator.next().value,
153
+ "<script>alert('This is an unsafe description.')</script>",
154
+ );
155
+ assert.strictEqual(generator.next().value, "12345");
156
+ assert.strictEqual(generator.next().value, "255");
157
+ assert.strictEqual(generator.next().value, "</p>");
158
+ assert.strictEqual(generator.next().value, "</div>");
159
+ assert.strictEqual(generator.next().done, true);
160
+ });