ui5-tooling-modules/lib/utils/HandlebarsHelper.js

UI5 CLI extensions to load and convert node modules as UI5 AMD-like modules

const handlebars = require("handlebars");
const { join } = require("path");
const { readFileSync } = require("fs");

// ------------------------------ General Helpers -----------------------------------
// Below we register some Handlebars helpers that can be used in different templates
// ----------------------------------------------------------------------------------

/**
 * Helper function to stringify objects into valid JSON from within HBS templates.
 * @param {object} context the object to stringify
 * @param {number} space the depth of the JSON stringification
 * @returns {string} the JSON string
 */
handlebars.registerHelper("json", function (context, space) {
	// default values are special cased here to avoid the JSON.stringify() from escaping them, which would make them invalid in the generated code.
	// !!! Note: This must be in sync with the default value handling in the rollup-plugin-webcomponents, otherwise the generated code will be different. !!!
	if (context.defaultValue && context.defaultValue !== "undefined") {
		const sanitizedContext = { ...context, defaultValue: "" };
		const json = JSON.stringify(sanitizedContext, null, space);
		return json.replace(/"defaultValue":\s*""/g, `"defaultValue": ${context.defaultValue}`);
	} else if (context.defaultValue === "undefined") {
		return JSON.stringify({ ...context, defaultValue: undefined }, null, space);
	}
	return JSON.stringify(context, null, space);
});

handlebars.registerHelper("escapeType", function (str) {
	return `{${str}}`;
});

handlebars.registerHelper("formatNewLine", function (str) {
	return `${str.replace(/\n/g, "\n * ")}${str.length > 0 ? "\n *" : ""}`;
});

handlebars.registerHelper("join", function (array) {
	return array.join(", ");
});

// ---------------------------- JSDoc Templating ---------------------------------
// Below is a structured string template for generically rendering JSDoc comments.
// This template is used to create JSDoc comment blocks for the JSDocSerializer,
// as well as the DtsSerializer.
// -------------------------------------------------------------------------------

/**
 * Creates a template function that structures strings with placeholders.
 * @param {string[]} strings - Template string parts
 * @param {...string} keys - Keys for the placeholders
 * @returns {Function} Template function that accepts values for the placeholders
 */
function structureTemplate(strings, ...keys) {
	return (...values) => {
		const newLine = "\n *";
		const dict = values[values.length - 1] || {};
		const result = [`/**`];
		keys.forEach((key, i) => {
			const value = Number.isInteger(key) ? values[key] : dict[key];
			if (value) {
				value.split(/\n/).forEach((valueLine) => {
					result.push(`${newLine} `, valueLine);
				});
				result.push(strings[i + 1]);
			}
		});
		result.push(`${newLine}/`);
		return result.length > 2 ? result.join("") : "";
	};
}

/**
 * Base template for generating standardized documentation blocks:
 *   - text = The main text of the documentation
 *   - description = A detailed description of the entity
 *   - defaultValue = The default value of the entity, if applicable
 *   - alias = the alias of the entity, can be "alias" or "name" tag in "module:..." syntax
 *   - override = The UI5 override tag for the entity, if applicable
 *   - visibility = The visibility of the entity (public, private, etc.)
 *   - additionalTags = Array of additional tags to be included in the documentation
 *   - returnValue = The return value of the entity, if applicable
 * @type {Function}
 */
const baseTemplate = structureTemplate`${"text"}${"description"}${"entityType"}${"defaultValue"}${"alias"}${"override"}${"visibility"}${"additionalTags"}${"returnValue"}`;

/**
 * Register the helper that generates geneic JSDoc comment blocks.
 * For the most part we only need the description part from the base template.
 * @param {string} description - The description to be included in the JSDoc comment
 * @returns {string} - The generated JSDoc comment block
 */
handlebars.registerHelper("generateApiDocumentation", function (description) {
	return baseTemplate({ description });
});

/**
 * This modules contains a bunch of Handlebars helpers, which can be shared across
 * different templates.
 * The handlebars helpers are automatically registered when this module is imported.
 */
const HandlebarsHelper = {
	/**
	 * helper function to load and compile a handlebars template
	 * @param {string} templatePath - The path to the Handlebars template file
	 * @returns {Function} - A compiled Handlebars template function
	 */
	loadAndCompile(templatePath) {
		const templateFile = readFileSync(join(__dirname, templatePath), { encoding: "utf-8" });
		return handlebars.compile(templateFile);
	},

	/**
	 * The generic base template for generating JSDoc comments.
	 * This template is very versatile and mainly used to generate different JSDoc comments
	 * in the DTSSerializer.
	 * The JSDocSerializer uses this template to generate description comments.
	 */
	baseTemplate,

	/**
	 * A template function that structures strings with placeholders.
	 */
	structureTemplate,
};

module.exports = HandlebarsHelper;