es-toolkit 1.25.2-dev.821 → 1.25.2-dev.824

package/dist/compat/index.d.mts

@@ -201,6 +201,7 @@ export { snakeCase } from './string/snakeCase.mjs';
 export { startCase } from './string/startCase.mjs';
 export { startsWith } from './string/startsWith.mjs';
 export { upperCase } from './string/upperCase.mjs';
+export { template, templateSettings } from './string/template.mjs';
 export { trim } from './string/trim.mjs';
 export { trimEnd } from './string/trimEnd.mjs';
 export { trimStart } from './string/trimStart.mjs';

package/dist/compat/index.d.ts

@@ -201,6 +201,7 @@ export { snakeCase } from './string/snakeCase.js';
 export { startCase } from './string/startCase.js';
 export { startsWith } from './string/startsWith.js';
 export { upperCase } from './string/upperCase.js';
+export { template, templateSettings } from './string/template.js';
 export { trim } from './string/trim.js';
 export { trimEnd } from './string/trimEnd.js';
 export { trimStart } from './string/trimStart.js';

package/dist/compat/index.js

@@ -2164,6 +2164,86 @@ function upperCase(str) {
     return upperFirst.upperCase(normalizeForCase(str));
 }
 
+const esTemplateRegExp = /\$\{([^\\}]*(?:\\.[^\\}]*)*)\}/g;
+const unEscapedRegExp = /['\n\r\u2028\u2029\\]/g;
+const noMatchExp = /($^)/;
+const escapeMap = new Map([
+    ['\\', '\\'],
+    ["'", "'"],
+    ['\n', 'n'],
+    ['\r', 'r'],
+    ['\u2028', 'u2028'],
+    ['\u2029', 'u2029'],
+]);
+function escapeString(match) {
+    return `\\${escapeMap.get(match)}`;
+}
+const templateSettings = {
+    escape: /<%-([\s\S]+?)%>/g,
+    evaluate: /<%([\s\S]+?)%>/g,
+    interpolate: /<%=([\s\S]+?)%>/g,
+    variable: '',
+    imports: {
+        _: {
+            escape,
+            template,
+        },
+    },
+};
+function template(string, options, guard) {
+    string = toString(string);
+    if (guard) {
+        options = templateSettings;
+    }
+    options = defaults({ ...options }, templateSettings);
+    const delimitersRegExp = new RegExp([
+        options.escape?.source ?? noMatchExp.source,
+        options.interpolate?.source ?? noMatchExp.source,
+        options.interpolate ? esTemplateRegExp.source : noMatchExp.source,
+        options.evaluate?.source ?? noMatchExp.source,
+        '$',
+    ].join('|'), 'g');
+    let lastIndex = 0;
+    let isEvaluated = false;
+    let source = `__p += ''`;
+    for (const match of string.matchAll(delimitersRegExp)) {
+        const [fullMatch, escapeValue, interpolateValue, esTemplateValue, evaluateValue] = match;
+        const { index } = match;
+        source += ` + '${string.slice(lastIndex, index).replace(unEscapedRegExp, escapeString)}'`;
+        if (escapeValue) {
+            source += ` + _.escape(${escapeValue})`;
+        }
+        if (interpolateValue) {
+            source += ` + ((${interpolateValue}) == null ? '' : ${interpolateValue})`;
+        }
+        else if (esTemplateValue) {
+            source += ` + ((${esTemplateValue}) == null ? '' : ${esTemplateValue})`;
+        }
+        if (evaluateValue) {
+            source += `;\n${evaluateValue};\n __p += ''`;
+            isEvaluated = true;
+        }
+        lastIndex = index + fullMatch.length;
+    }
+    const imports = defaults({ ...options.imports }, templateSettings.imports);
+    const importsKeys = Object.keys(imports);
+    const importValues = Object.values(imports);
+    const sourceURL = `//# sourceURL=${options.sourceURL ? String(options.sourceURL).replace(/[\r\n]/g, ' ') : `es-toolkit.templateSource[${Date.now()}]`}\n`;
+    const compiledFunction = `function(${options.variable || 'obj'}) {
+    let __p = '';
+    ${options.variable ? '' : 'if (obj == null) { obj = {}; }'}
+    ${isEvaluated ? `function print() { __p += Array.prototype.join.call(arguments, ''); }` : ''}
+    ${options.variable ? source : `with(obj) {\n${source}\n}`}
+    return __p;
+  }`;
+    const result = attempt(() => new Function(...importsKeys, `${sourceURL}return ${compiledFunction}`)(...importValues));
+    result.source = compiledFunction;
+    if (result instanceof Error) {
+        throw result;
+    }
+    return result;
+}
+
 function trim(str, chars, guard) {
     if (str == null) {
         return '';
@@ -2480,6 +2560,8 @@ exports.startsWith = startsWith;
 exports.tail = tail;
 exports.take = take;
 exports.takeRight = takeRight;
+exports.template = template;
+exports.templateSettings = templateSettings;
 exports.throttle = throttle;
 exports.times = times;
 exports.toDefaulted = toDefaulted;

package/dist/compat/index.mjs

@@ -202,6 +202,7 @@ export { snakeCase } from './string/snakeCase.mjs';
 export { startCase } from './string/startCase.mjs';
 export { startsWith } from './string/startsWith.mjs';
 export { upperCase } from './string/upperCase.mjs';
+export { template, templateSettings } from './string/template.mjs';
 export { trim } from './string/trim.mjs';
 export { trimEnd } from './string/trimEnd.mjs';
 export { trimStart } from './string/trimStart.mjs';

package/dist/compat/string/template.d.mts

@@ -0,0 +1,89 @@
+import { escape } from './escape.mjs';
+
+declare const templateSettings: {
+    escape: RegExp;
+    evaluate: RegExp;
+    interpolate: RegExp;
+    variable: string;
+    imports: {
+        _: {
+            escape: typeof escape;
+            template: typeof template;
+        };
+    };
+};
+interface TemplateOptions {
+    escape?: RegExp;
+    evaluate?: RegExp;
+    interpolate?: RegExp;
+    variable?: string;
+    imports?: Record<string, unknown>;
+    sourceURL?: string;
+}
+/**
+ * Compiles a template string into a function that can interpolate data properties.
+ *
+ * This function allows you to create a template with custom delimiters for escaping,
+ * evaluating, and interpolating values. It can also handle custom variable names and
+ * imported functions.
+ *
+ * @param {string} string - The template string.
+ * @param {TemplateOptions} [options] - The options object.
+ * @param {RegExp} [options.escape] - The regular expression for "escape" delimiter.
+ * @param {RegExp} [options.evaluate] - The regular expression for "evaluate" delimiter.
+ * @param {RegExp} [options.interpolate] - The regular expression for "interpolate" delimiter.
+ * @param {string} [options.variable] - The data object variable name.
+ * @param {Record<string, unknown>} [options.imports] - The object of imported functions.
+ * @param {string} [options.sourceURL] - The source URL of the template.
+ * @param {unknown} [guard] - The guard to detect if the function is called with `options`.
+ * @returns {(data?: object) => string} Returns the compiled template function.
+ *
+ * @example
+ * // Use the "escape" delimiter to escape data properties.
+ * const compiled = template('<%- value %>');
+ * compiled({ value: '<div>' }); // returns '&lt;div&gt;'
+ *
+ * @example
+ * // Use the "interpolate" delimiter to interpolate data properties.
+ * const compiled = template('<%= value %>');
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "evaluate" delimiter to evaluate JavaScript code.
+ * const compiled = template('<% if (value) { %>Yes<% } else { %>No<% } %>');
+ * compiled({ value: true }); // returns 'Yes'
+ *
+ * @example
+ * // Use the "variable" option to specify the data object variable name.
+ * const compiled = template('<%= data.value %>', { variable: 'data' });
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "imports" option to import functions.
+ * const compiled = template('<%= _.toUpper(value) %>', { imports: { _: { toUpper } } });
+ * compiled({ value: 'hello, world!' }); // returns 'HELLO, WORLD!'
+ *
+ * @example
+ * // Use the custom "escape" delimiter.
+ * const compiled = template('<@ value @>', { escape: /<@([\s\S]+?)@>/g });
+ * compiled({ value: '<div>' }); // returns '&lt;div&gt;'
+ *
+ * @example
+ * // Use the custom "evaluate" delimiter.
+ * const compiled = template('<# if (value) { #>Yes<# } else { #>No<# } #>', { evaluate: /<#([\s\S]+?)#>/g });
+ * compiled({ value: true }); // returns 'Yes'
+ *
+ * @example
+ * // Use the custom "interpolate" delimiter.
+ * const compiled = template('<$ value $>', { interpolate: /<\$([\s\S]+?)\$>/g });
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "sourceURL" option to specify the source URL of the template.
+ * const compiled = template('hello <%= user %>!', { sourceURL: 'template.js' });
+ */
+declare function template(string: string, options?: TemplateOptions, guard?: unknown): ((data?: object) => string) & {
+    source: string;
+};
+
+export { template, templateSettings };

package/dist/compat/string/template.d.ts

@@ -0,0 +1,89 @@
+import { escape } from './escape.js';
+
+declare const templateSettings: {
+    escape: RegExp;
+    evaluate: RegExp;
+    interpolate: RegExp;
+    variable: string;
+    imports: {
+        _: {
+            escape: typeof escape;
+            template: typeof template;
+        };
+    };
+};
+interface TemplateOptions {
+    escape?: RegExp;
+    evaluate?: RegExp;
+    interpolate?: RegExp;
+    variable?: string;
+    imports?: Record<string, unknown>;
+    sourceURL?: string;
+}
+/**
+ * Compiles a template string into a function that can interpolate data properties.
+ *
+ * This function allows you to create a template with custom delimiters for escaping,
+ * evaluating, and interpolating values. It can also handle custom variable names and
+ * imported functions.
+ *
+ * @param {string} string - The template string.
+ * @param {TemplateOptions} [options] - The options object.
+ * @param {RegExp} [options.escape] - The regular expression for "escape" delimiter.
+ * @param {RegExp} [options.evaluate] - The regular expression for "evaluate" delimiter.
+ * @param {RegExp} [options.interpolate] - The regular expression for "interpolate" delimiter.
+ * @param {string} [options.variable] - The data object variable name.
+ * @param {Record<string, unknown>} [options.imports] - The object of imported functions.
+ * @param {string} [options.sourceURL] - The source URL of the template.
+ * @param {unknown} [guard] - The guard to detect if the function is called with `options`.
+ * @returns {(data?: object) => string} Returns the compiled template function.
+ *
+ * @example
+ * // Use the "escape" delimiter to escape data properties.
+ * const compiled = template('<%- value %>');
+ * compiled({ value: '<div>' }); // returns '&lt;div&gt;'
+ *
+ * @example
+ * // Use the "interpolate" delimiter to interpolate data properties.
+ * const compiled = template('<%= value %>');
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "evaluate" delimiter to evaluate JavaScript code.
+ * const compiled = template('<% if (value) { %>Yes<% } else { %>No<% } %>');
+ * compiled({ value: true }); // returns 'Yes'
+ *
+ * @example
+ * // Use the "variable" option to specify the data object variable name.
+ * const compiled = template('<%= data.value %>', { variable: 'data' });
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "imports" option to import functions.
+ * const compiled = template('<%= _.toUpper(value) %>', { imports: { _: { toUpper } } });
+ * compiled({ value: 'hello, world!' }); // returns 'HELLO, WORLD!'
+ *
+ * @example
+ * // Use the custom "escape" delimiter.
+ * const compiled = template('<@ value @>', { escape: /<@([\s\S]+?)@>/g });
+ * compiled({ value: '<div>' }); // returns '&lt;div&gt;'
+ *
+ * @example
+ * // Use the custom "evaluate" delimiter.
+ * const compiled = template('<# if (value) { #>Yes<# } else { #>No<# } #>', { evaluate: /<#([\s\S]+?)#>/g });
+ * compiled({ value: true }); // returns 'Yes'
+ *
+ * @example
+ * // Use the custom "interpolate" delimiter.
+ * const compiled = template('<$ value $>', { interpolate: /<\$([\s\S]+?)\$>/g });
+ * compiled({ value: 'Hello, World!' }); // returns 'Hello, World!'
+ *
+ * @example
+ * // Use the "sourceURL" option to specify the source URL of the template.
+ * const compiled = template('hello <%= user %>!', { sourceURL: 'template.js' });
+ */
+declare function template(string: string, options?: TemplateOptions, guard?: unknown): ((data?: object) => string) & {
+    source: string;
+};
+
+export { template, templateSettings };

package/dist/compat/string/template.mjs

@@ -0,0 +1,86 @@
+import { escape } from './escape.mjs';
+import { attempt } from '../function/attempt.mjs';
+import { defaults } from '../object/defaults.mjs';
+import { toString } from '../util/toString.mjs';
+
+const esTemplateRegExp = /\$\{([^\\}]*(?:\\.[^\\}]*)*)\}/g;
+const unEscapedRegExp = /['\n\r\u2028\u2029\\]/g;
+const noMatchExp = /($^)/;
+const escapeMap = new Map([
+    ['\\', '\\'],
+    ["'", "'"],
+    ['\n', 'n'],
+    ['\r', 'r'],
+    ['\u2028', 'u2028'],
+    ['\u2029', 'u2029'],
+]);
+function escapeString(match) {
+    return `\\${escapeMap.get(match)}`;
+}
+const templateSettings = {
+    escape: /<%-([\s\S]+?)%>/g,
+    evaluate: /<%([\s\S]+?)%>/g,
+    interpolate: /<%=([\s\S]+?)%>/g,
+    variable: '',
+    imports: {
+        _: {
+            escape,
+            template,
+        },
+    },
+};
+function template(string, options, guard) {
+    string = toString(string);
+    if (guard) {
+        options = templateSettings;
+    }
+    options = defaults({ ...options }, templateSettings);
+    const delimitersRegExp = new RegExp([
+        options.escape?.source ?? noMatchExp.source,
+        options.interpolate?.source ?? noMatchExp.source,
+        options.interpolate ? esTemplateRegExp.source : noMatchExp.source,
+        options.evaluate?.source ?? noMatchExp.source,
+        '$',
+    ].join('|'), 'g');
+    let lastIndex = 0;
+    let isEvaluated = false;
+    let source = `__p += ''`;
+    for (const match of string.matchAll(delimitersRegExp)) {
+        const [fullMatch, escapeValue, interpolateValue, esTemplateValue, evaluateValue] = match;
+        const { index } = match;
+        source += ` + '${string.slice(lastIndex, index).replace(unEscapedRegExp, escapeString)}'`;
+        if (escapeValue) {
+            source += ` + _.escape(${escapeValue})`;
+        }
+        if (interpolateValue) {
+            source += ` + ((${interpolateValue}) == null ? '' : ${interpolateValue})`;
+        }
+        else if (esTemplateValue) {
+            source += ` + ((${esTemplateValue}) == null ? '' : ${esTemplateValue})`;
+        }
+        if (evaluateValue) {
+            source += `;\n${evaluateValue};\n __p += ''`;
+            isEvaluated = true;
+        }
+        lastIndex = index + fullMatch.length;
+    }
+    const imports = defaults({ ...options.imports }, templateSettings.imports);
+    const importsKeys = Object.keys(imports);
+    const importValues = Object.values(imports);
+    const sourceURL = `//# sourceURL=${options.sourceURL ? String(options.sourceURL).replace(/[\r\n]/g, ' ') : `es-toolkit.templateSource[${Date.now()}]`}\n`;
+    const compiledFunction = `function(${options.variable || 'obj'}) {
+    let __p = '';
+    ${options.variable ? '' : 'if (obj == null) { obj = {}; }'}
+    ${isEvaluated ? `function print() { __p += Array.prototype.join.call(arguments, ''); }` : ''}
+    ${options.variable ? source : `with(obj) {\n${source}\n}`}
+    return __p;
+  }`;
+    const result = attempt(() => new Function(...importsKeys, `${sourceURL}return ${compiledFunction}`)(...importValues));
+    result.source = compiledFunction;
+    if (result instanceof Error) {
+        throw result;
+    }
+    return result;
+}
+
+export { template, templateSettings };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "es-toolkit",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
-  "version": "1.25.2-dev.821+bd7468fc",
+  "version": "1.25.2-dev.824+a000c597",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {