[IMP] tools: expose template compiler as npm command

Previously, we made it possible to compile templates ahead of time as
this was required by the owl devtools. Unfortunately, no effort was made
at the time to make this ahead-of-time compiler outside of the owl repo.

This commit refactors the AoT template compiler by splitting it in two
parts: a typescript module that gets bundled in the dist folder that
gives a programmatic way to call the standalone compiler from another
javascript module by importing it, and a command line utility that is
exposed as an executable files available to npm run-script of dependent
modules (configured in the bin field of owl's package.json).

This allows a simple workflow for modules wanting to use owl:

`npm install @odoo/owl`

add a script to your package.json that calls compile_owl_templates on
your source files, eg:

```jsonc
{
  // ...
  "scripts": {
    "build": "compile_owl_templates src -o dist/templates.js"
  }
}
```

`npm run build`

package.json

@@ -32,7 +32,10 @@
     "check-formatting": "prettier {src/*.ts,src/**/*.ts,tests/*.ts,tests/**/*.ts,doc/*.md,doc/**/*.md,tools/devtools/**/*.js} --check",
     "lint": "eslint src/**/*.ts tests/**/*.ts",
     "release": "node tools/release.js",
-    "compile_templates": "node tools/compile_xml.js"
+    "compile_templates": "node tools/compile_owl_templates.mjs"
+  },
+  "bin": {
+    "compile_owl_templates": "tools/compile_owl_templates.mjs"
   },
   "repository": {
     "type": "git",
@@ -46,6 +49,7 @@
   "homepage": "https://github.com/odoo/owl#readme",
   "devDependencies": {
     "@types/jest": "^27.0.1",
+    "@types/jsdom": "^21.1.7",
     "@types/node": "^14.11.8",
     "@typescript-eslint/eslint-plugin": "5.48.1",
     "@typescript-eslint/parser": "5.48.1",
@@ -97,5 +101,8 @@
   "prettier": {
     "printWidth": 100,
     "endOfLine": "auto"
+  },
+  "dependencies": {
+    "jsdom": "^25.0.1"
   }
 }

rollup.config.js

@@ -1,6 +1,6 @@
 import pkg from "./package.json";
 import git from "git-rev-sync";
-import typescript from 'rollup-plugin-typescript2';
+import typescript from "rollup-plugin-typescript2";
 import { terser } from "rollup-plugin-terser";
 import dts from "rollup-plugin-dts";
 
@@ -12,7 +12,7 @@ const ES_FILENAME = "dist/owl.es.js";
 
 if (pkg.module !== ES_FILENAME || pkg.main !== CJS_FILENAME) {
   throw new Error("package.json has been modified. Build script should be updated accordingly");
-}  
+}
 
 const outro = `
 __info__.date = '${new Date().toISOString()}';
@@ -21,39 +21,37 @@ __info__.url = 'https://github.com/odoo/owl';
 `;
 
 switch (process.argv[4]) {
-  case "compiler": 
-    input = "src/compiler/index.ts",
-    output = [
-      getConfigForFormat('cjs', 'dist/compiler.js', ''),
-    ]
+  case "compiler":
+    (input = "src/compiler/index.ts"),
+      (output = [getConfigForFormat("cjs", "dist/compiler.js", "")]);
     break;
   case "runtime":
     input = "src/runtime/index.ts";
     output = [
-      getConfigForFormat('esm', addSuffix(ES_FILENAME,  'runtime'), outro),
-      getConfigForFormat('cjs', addSuffix(CJS_FILENAME,  'runtime'), outro),
-      getConfigForFormat('iife', addSuffix(IIFE_FILENAME,  'runtime'), outro),
-      getConfigForFormat('iife', addSuffix(IIFE_FILENAME,  'runtime'), outro, true),
-    ]
+      getConfigForFormat("esm", addSuffix(ES_FILENAME, "runtime"), outro),
+      getConfigForFormat("cjs", addSuffix(CJS_FILENAME, "runtime"), outro),
+      getConfigForFormat("iife", addSuffix(IIFE_FILENAME, "runtime"), outro),
+      getConfigForFormat("iife", addSuffix(IIFE_FILENAME, "runtime"), outro, true),
+    ];
     break;
   default:
-    input = "src/index.ts",
-    output = [
-      getConfigForFormat('esm', ES_FILENAME, outro),
-      getConfigForFormat('cjs', CJS_FILENAME, outro),
-      getConfigForFormat('iife', IIFE_FILENAME, outro),
-      getConfigForFormat('iife', IIFE_FILENAME, outro, true),
-    ]
-  }
+    (input = "src/index.ts"),
+      (output = [
+        getConfigForFormat("esm", ES_FILENAME, outro),
+        getConfigForFormat("cjs", CJS_FILENAME, outro),
+        getConfigForFormat("iife", IIFE_FILENAME, outro),
+        getConfigForFormat("iife", IIFE_FILENAME, outro, true),
+      ]);
+}
 
 /**
  * Generate from a string depicting a path a new path for the minified version.
  * @param {string} pkgFileName file name
  */
 function addSuffix(pkgFileName, suffix) {
-  const parts = pkgFileName.split('.');
+  const parts = pkgFileName.split(".");
   parts.splice(parts.length - 1, 0, suffix);
-  return parts.join('.');
+  return parts.join(".");
 }
 
 /**
@@ -71,7 +69,7 @@ function getConfigForFormat(format, generatedFileName, outro, minified = false)
     outro: outro,
     freeze: false,
     plugins: minified ? [terser()] : [],
-    indent: '    ', // indent with 4 spaces
+    indent: "    ", // indent with 4 spaces
   };
 }
 
@@ -81,9 +79,19 @@ export default [
     output,
     plugins: [
       typescript({
-        useTsconfigDeclarationDir: true
+        useTsconfigDeclarationDir: true,
       }),
-    ]
+    ],
+  },
+  {
+    input: "src/compiler/standalone/index.ts",
+    output: [{ file: "dist/compile_templates.mjs", format: "es" }],
+    external: ["fs", "fs/promises", "path", "jsdom"],
+    plugins: [
+      typescript({
+        useTsconfigDeclarationDir: true,
+      }),
+    ],
   },
   {
     input: "dist/types/index.d.ts",

src/compiler/standalone/index.ts

@@ -0,0 +1,89 @@
+// -----------------------------------------------------------------------------
+// This file exports a function that allows compiling templates ahead of time.
+// It is used by the "compile_owl_template" command registered in the "bin"
+// section of owl's package.json
+// -----------------------------------------------------------------------------
+
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
+import "./setup_jsdom";
+// Owl imports must be made after setting up jsdom in the global namespace
+import { compile } from "..";
+
+// -----------------------------------------------------------------------------
+// helpers
+// -----------------------------------------------------------------------------
+async function getXmlFiles(paths: string[]): Promise<string[]> {
+  return (
+    await Promise.all(
+      paths.map(async (file) => {
+        const stats = await stat(path.join(file));
+        if (stats.isDirectory()) {
+          return await getXmlFiles(
+            (await readdir(file)).map((fileName) => path.join(file, fileName))
+          );
+        }
+        if (file.endsWith(".xml")) {
+          return file;
+        }
+        return [];
+      })
+    )
+  ).flat();
+}
+
+// adapted from https://medium.com/@mhagemann/the-ultimate-way-to-slugify-a-url-string-in-javascript-b8e4a0d849e1
+const a = "·-_,:;";
+const p = new RegExp(a.split("").join("|"), "g");
+
+function slugify(str: string) {
+  return str
+    .replace(/\//g, "") // remove /
+    .replace(/\./g, "_") // Replace . with _
+    .replace(p, (c) => "_") // Replace special characters
+    .replace(/&/g, "_and_") // Replace & with ‘and’
+    .replace(/[^\w\-]+/g, ""); // Remove all non-word characters
+}
+
+// -----------------------------------------------------------------------------
+// main
+// -----------------------------------------------------------------------------
+
+export async function compileTemplates(paths: string[]) {
+  const files = await getXmlFiles(paths);
+  process.stdout.write(`Processing ${files.length} files`);
+  let xmlStrings = await Promise.all(files.map((file) => readFile(file, "utf8")));
+
+  const templates = [];
+  const errors = [];
+
+  for (let i = 0; i < files.length; i++) {
+    const fileName = files[i];
+    const fileContent = xmlStrings[i];
+    process.stdout.write(`.`);
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(fileContent, "text/xml");
+    for (const template of doc.querySelectorAll("[t-name]")) {
+      const name = template.getAttribute("t-name");
+      if (template.hasAttribute("owl")) {
+        template.removeAttribute("owl");
+      }
+      const fnName = slugify(name!);
+      try {
+        const fn = compile(template).toString().replace("anonymous", fnName);
+        templates.push(`"${name}": ${fn},\n`);
+      } catch (e) {
+        errors.push({ name, fileName, e });
+      }
+    }
+  }
+  process.stdout.write(`\n`);
+
+  for (let { name, fileName, e } of errors) {
+    console.warn(`Error while compiling '${name}' (in file ${fileName})`);
+    console.error(e);
+  }
+  console.log(`${templates.length} templates compiled`);
+
+  return `export const templates = {\n ${templates.join("\n")} \n}`;
+}

src/compiler/standalone/setup_jsdom.ts

@@ -0,0 +1,13 @@
+import jsdom from "jsdom";
+
+// -----------------------------------------------------------------------------
+// add global DOM stuff for compiler. Needs to be in a separate file so rollup
+// doesn't hoist the owl imports above this block of code.
+// -----------------------------------------------------------------------------
+var document = new jsdom.JSDOM("", {});
+var window = document.window;
+global.document = window.document;
+global.window = window as unknown as Window & typeof globalThis;
+global.DOMParser = window.DOMParser;
+global.Element = window.Element;
+global.Node = window.Node;

tools/compile_owl_templates.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// this is the "compile_owl_templates" command that owl makes available when
+// installed as a node_module.
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { compileTemplates } from "../dist/compile_templates.mjs";
+import { parseArgs } from "util";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    output: {
+      type: "string",
+      short: "o",
+      default: "templates.js",
+    },
+  },
+});
+
+if (positionals.length) {
+  const result = await compileTemplates(positionals);
+  const outputPath = values.output;
+  const dir = dirname(outputPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(outputPath, result);
+} else {
+  console.log("Please provide a path");
+}

tools/compile_xml.js

@@ -1,113 +0,0 @@
-const fs = require("fs");
-const path = require("path");
-const jsdom = require("jsdom");
-
-// -----------------------------------------------------------------------------
-// add global DOM stuff for compiler
-// -----------------------------------------------------------------------------
-var document = new jsdom.JSDOM("", {});
-var window = document.window;
-global.document = window.document;
-global.window = window;
-global.DOMParser = window.DOMParser;
-global.Element = window.Element;
-global.Node = window.Node;
-// this needs to be below the jsdom stuff
-const { compile } = require("../dist/compiler.js");
-
-// -----------------------------------------------------------------------------
-// helpers
-// -----------------------------------------------------------------------------
-async function getXmlFiles(dir) {
-  let xmls = [];
-  const files = await fs.promises.readdir(dir);
-  const filesStats = await Promise.all(files.map((file) => fs.promises.stat(path.join(dir, file))));
-  for (let i in files) {
-    const name = path.join(dir, files[i]);
-    if (filesStats[i].isDirectory()) {
-      xmls = xmls.concat(await getXmlFiles(name));
-    } else {
-      if (name.endsWith(".xml")) {
-        xmls.push(name);
-      }
-    }
-  }
-  return xmls;
-}
-
-function writeToFile(filepath, data) {
-  if (!fs.existsSync(path.dirname(filepath))) {
-    fs.mkdirSync(path.dirname(filepath), { recursive: true });
-  }
-  fs.writeFile(filepath, data, (err) => {
-    if (err) {
-      process.stdout.write(`Error while writing file ${filepath}: ${err}`);
-      return;
-    }
-  });
-}
-
-// adapted from https://medium.com/@mhagemann/the-ultimate-way-to-slugify-a-url-string-in-javascript-b8e4a0d849e1
-const a = "·-_,:;";
-const p = new RegExp(a.split("").join("|"), "g");
-
-function slugify(str) {
-  return str
-    .replace(/\//g, "") // remove /
-    .replace(/\./g, "_") // Replace . with _
-    .replace(p, (c) => '_') // Replace special characters
-    .replace(/&/g, "_and_") // Replace & with ‘and’
-    .replace(/[^\w\-]+/g, "") // Remove all non-word characters
-}
-
-// -----------------------------------------------------------------------------
-// main
-// -----------------------------------------------------------------------------
-
-async function compileTemplates(files) {
-  process.stdout.write(`Processing ${files.length} files`);
-  let xmlStrings = await Promise.all(files.map((file) => fs.promises.readFile(file, "utf8")));
-
-  const templates = [];
-  const errors = [];
-
-  for (let i = 0; i < files.length; i++) {
-    const fileName = files[i];
-    const fileContent = xmlStrings[i];
-    process.stdout.write(`.`);
-    const parser = new DOMParser();
-    const doc = parser.parseFromString(fileContent, "text/xml");
-    for (const template of doc.querySelectorAll("[t-name]")) {
-      const name = template.getAttribute("t-name");
-      if (template.hasAttribute("owl")) {
-        template.removeAttribute("owl")
-      }
-      const fnName = slugify(name);
-      try {
-        const fn = compile(template).toString().replace('anonymous', fnName);
-        templates.push(`"${name}": ${fn},\n`);
-      } catch (e) {
-        errors.push({ name, fileName, e });
-      }
-    }
-  }
-  process.stdout.write(`\n`);
-
-  for (let { name, fileName, e } of errors) {
-    console.warn(`Error while compiling '${name}' (in file ${fileName})`);
-    console.error(e);
-  }
-  console.log(`${templates.length} templates compiled`);
-
-  return `export const templates = {\n ${templates.join("\n")} \n}`;
-}
-
-const templatesPath = process.argv[2];
-if (templatesPath && templatesPath.length) {
-  getXmlFiles(templatesPath).then(async (files) => {
-    const result = await compileTemplates(files);
-    writeToFile("templates.js", result);
-  });
-} else {
-  console.log("Please provide a path");
-}