layout-data 0.0.0-stage → 0.3.0

package/src/types.js

@@ -0,0 +1,74 @@
+// Renders TypeScript declarations of registered layouts, for editor completion
+// of the tag accessors (doc/spec-data-api.md §6.7, doc/design.md §4).
+
+/** A name that can be part of a type name: an identifier of JavaScript, in any script. */
+const IDENTIFIER = /^[\p{ID_Start}_$][\p{ID_Continue}$‌‍]*$/u;
+
+/**
+ * Renders a text as a doc comment, one line or several, with the `*` and `/`
+ * pair that would end the comment early escaped.
+ *
+ * @param {string} text
+ * @param {string} indent
+ * @returns {string[]}
+ */
+function doc_comment(text, indent) {
+	const lines = String(text).replaceAll("*/", "*\\/").split(/\r?\n/);
+	if (lines.length === 1) return [`${indent}/** ${lines[0]} */`];
+	return [`${indent}/**`, ...lines.map((line) => `${indent} * ${line}`.trimEnd()), `${indent} */`];
+}
+
+/**
+ * Renders a declaration file with, for each layout, an interface of its tags
+ * (`<Layout>_Tags`, one property per tag) and the type of its data block
+ * (`<Layout>_Ldata`). The layout name is used as it is, with the case it has,
+ * so that the type names are those of `new Ldata("<Layout>", ...)` and layouts
+ * with different names never get the same type name.
+ *
+ * In JavaScript a JSDoc cast names the type of the value, which an editor
+ * uses for completion and, with `checkJs`, to check the tags:
+ *
+ * ```js
+ * const pump = /** @type {import("./layout_types.js").Pump_Ldata} *\/ (new Ldata("Pump", "pump_1"));
+ * ```
+ *
+ * @param {Record<string, import("./typedefs.js").Layout>} layouts - Registered layouts by name.
+ * @param {object} [options]
+ * @param {string} [options.source] - The layout file, named in the header; the header names none when it is omitted.
+ * @param {string} [options.ldata_module] - Module specifier of Ldata, relative to the output file; "layout-data" by default.
+ * @returns {string}
+ * @throws {Error} With `errors`, when the name of a layout is not an identifier, which a type name needs.
+ */
+export function render_types(layouts, { source, ldata_module = "layout-data" } = {}) {
+	const names = Object.keys(layouts);
+	const errors = names
+		.filter((name) => !IDENTIFIER.test(name))
+		.map((name) => `layout ${JSON.stringify(name)}: the name is not an identifier, so it cannot be part of a type name`);
+	if (errors.length > 0) {
+		const error = new Error(`cannot render the types of the layouts:\n${errors.join("\n")}`);
+		error.errors = errors;
+		throw error;
+	}
+
+	const lines = [
+		source === undefined ? "// Generated by render_types. Do not edit." : `// Generated from ${source}. Do not edit.`,
+		`import type { Ldata } from ${JSON.stringify(ldata_module)};`,
+	];
+	if (names.length > 0) {
+		lines.push(
+			"//",
+			"// In JavaScript, a JSDoc cast names the type of the value:",
+			`//   const data = /** @type {import("<this file>").${names[0]}_Ldata} */ (new Ldata("${names[0]}", "data_1"));`,
+		);
+	}
+	for (const [name, layout] of Object.entries(layouts)) {
+		lines.push("", `/** Tags of the ${name} data block. */`, `export interface ${name}_Tags {`);
+		for (const item of layout.items) {
+			if (item.comment) lines.push(...doc_comment(item.comment, "\t"));
+			const ts_type = item.type.toLowerCase() === "bool" ? "boolean" : "number";
+			lines.push(`\t${item.name}: ${ts_type};`);
+		}
+		lines.push("}", "", `/** A ${name} data block, with its tags as properties. */`, `export type ${name}_Ldata = Ldata & ${name}_Tags;`);
+	}
+	return `${lines.join("\n")}\n`;
+}