feat: generate model declaration & runtime code using handlebars (#16)

Co-authored-by: Thorsten Seyschab <business@todde.tv>

Author: fehnomenal

.gitignore

@@ -26,3 +26,7 @@ node_modules/
 
 # generated build
 dist
+
+# generated files
+*.hbs.ts
+register__generated.ts

README.dev.md

@@ -76,6 +76,37 @@ the GitHub workflow (CI action) that:
 
 You can use `npx changelogen --dry` to generate the new changelog in a dry run to preview in development.
 
+## Template Compilation and Usage
+
+It uses Handlebars to generate the code.
+
+Here's a more detailed explanation of how everything works:
+
+1. During local installation, all Handlebars templates are precompiled into JavaScript code so they can be bundled
+   without the need to manually specify which `*.hbs` files need to be included or reference them at runtime.
+
+   1. The process works by scanning all files in the `src` directory and generating a TypeScript file for each
+      found template.
+   2. These files contain the precompiled Handlebars code and export the instantiated template (which is a regular
+      function) as the default export. This allows the templates to be used simply by importing them.
+   3. The script treats partials (identified by being in `_partials` directories) differently: They are also
+      precompiled as described above, but for each `_partials` directory, an index file is generated that registers
+      all the contained partials on import.
+   4. To generate these two types of files, the script itself uses Handlebars templates. These do not need to be
+      precompiled or bundled as they are only used during the plugin's development.
+
+2. The templates themselves are fairly simple but split across multiple files and helpers to reduce duplication.
+
+   1. The `fn_prefix` partial generates code for the node getter function and is adaptable for both `.d.ts`
+      and `.js` code. For example, in declaration files, the use of `async function` is not allowed.
+   2. The `children` partial is recursive and constructs the tree of child indices, using a helper function to
+      build the index array.
+   3. The `imports` partial builds a list of imports and takes into account type-only imports. Currently, this is
+      not required and is a remnant of a previous iteration. I decided to keep it in, as it might be useful in the future.
+   4. The main templates, `declaration` and `runtime`, are now simply wrappers around these partials.
+
+See [PR #16](https://github.com/toddeTV/gltf-type-toolkit/pull/16), which introduces this logic for the first time.
+
 ## Docs and helper websites
 
 \[currently none\]

package.json

@@ -108,6 +108,8 @@
     "pnpm": "9"
   },
   "scripts": {
+    "prepare": "run-s \"precompile-templates\"",
+    "precompile-templates": "esno scripts/precompile-templates.ts",
     "build": "tsup",
     "dev": "tsup --watch src",
     "build:post": "esno scripts/postbuild.ts",
@@ -158,6 +160,7 @@
     }
   },
   "dependencies": {
+    "handlebars": "~4.7.8"
   },
   "devDependencies": {
     "@antfu/eslint-config": "~3.16.0",

pnpm-lock.yaml

@@ -0,0 +1,80 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Handlebars from 'handlebars'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// This template is used to generate the files.
+const template = Handlebars.compile(
+  await readFile(resolve(__dirname, './templates/template.hbs'), { encoding: 'utf8' }),
+  { strict: true },
+)
+
+// Begin traversal at this directory.
+const dirsToScan = [resolve(__dirname, '../src/')]
+
+// Marker for partial templates.
+const PARTIALS_DIR = '_partials'
+
+// Memory to build index files for partials.
+const partialsIndices: Record<string, string[]> = {}
+
+// This template is used to generate the partial index files.
+const partialIndex = Handlebars.compile(
+  await readFile(resolve(__dirname, './templates/register.hbs'), { encoding: 'utf8' }),
+  { strict: true },
+)
+
+while (dirsToScan.length > 0) {
+  const dir = dirsToScan.shift()
+  if (dir) {
+    // Get directory contents.
+    const entries = await readdir(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = join(entry.parentPath, entry.name)
+
+      if (entry.isDirectory()) {
+        // Enqueue directories into the list to check. This does a breadth-first search.
+        dirsToScan.push(fullPath)
+      }
+      else if (entry.name.endsWith('.hbs')) {
+        // Precompile the template...
+        const templateSpec = Handlebars.precompile(await readFile(fullPath, { encoding: 'utf8' }), {
+          strict: true,
+        })
+
+        // ... and save it into a file.
+        await writeFile(
+          `${fullPath}.ts`,
+          template({
+            templateSpec,
+          }),
+          { encoding: 'utf8' },
+        )
+
+        // Check if this is a partial template.
+        const partialsIdx = fullPath.indexOf(PARTIALS_DIR)
+        if (partialsIdx > -1) {
+          const partialDir = fullPath.slice(0, partialsIdx + PARTIALS_DIR.length)
+          const partialName = fullPath.slice(partialsIdx + PARTIALS_DIR.length + 1)
+
+          const index = partialsIndices[partialDir] ?? (partialsIndices[partialDir] = [])
+          index.push(partialName)
+        }
+      }
+    }
+  }
+}
+
+// Generate index files for partials that register them on import.
+for (const [dir, partials] of Object.entries(partialsIndices)) {
+  await writeFile(
+    join(dir, 'register__generated.ts'),
+    partialIndex({
+      partials,
+    }),
+    { encoding: 'utf8' },
+  )
+}

scripts/precompile-templates.ts

@@ -0,0 +1,8 @@
+import Handlebars from 'handlebars';
+{{#each partials}}
+import partial_{{@index}} from './{{.}}.js';
+{{/each}}
+
+{{#each partials}}
+Handlebars.registerPartial('{{.}}', partial_{{@index}});
+{{/each}}

scripts/templates/register.hbs

@@ -0,0 +1,5 @@
+import Handlebars from 'handlebars';
+
+const spec = {{{templateSpec}}};
+
+export default Handlebars.template(spec);

scripts/templates/template.hbs

@@ -0,0 +1,65 @@
+import type { Object3D } from 'three'
+import type { GLTF } from 'three-stdlib'
+import { Imports } from './utils/imports.js'
+
+export interface GltfNode {
+  name: string
+  type: string
+  index: number
+  children: GltfNode[]
+}
+
+export type GltfAnalysis = ReturnType<typeof analyzeGltfModel>
+
+export function analyzeGltfModel({ scenes }: Pick<GLTF, 'scenes'>): { imports: Imports, scenes: GltfNode[] } {
+  const imports = new Imports()
+
+  const sceneNodes: GltfNode[] = []
+
+  for (let index = 0; index < scenes.length; index++) {
+    const scene = scenes[index]
+
+    const node: GltfNode = {
+      children: [],
+      index,
+      name: toValidIdentifier(`${scene.name}Scene`),
+      type: imports.addImport('three', scene.type, true),
+    }
+
+    collectNamedChildren(imports, scene, node)
+
+    sceneNodes.push(node)
+  }
+
+  return {
+    imports,
+    scenes: sceneNodes,
+  }
+}
+
+function collectNamedChildren(imports: Imports, obj: Object3D, parentNode: GltfNode): void {
+  for (let index = 0; index < obj.children.length; index++) {
+    const child = obj.children[index]
+
+    if (child.name) {
+      const node: GltfNode = {
+        children: [],
+        index,
+        name: toValidIdentifier(child.name),
+        type: imports.addImport('three', child.type, true),
+      }
+
+      parentNode.children.push(node)
+
+      collectNamedChildren(imports, child, node)
+    }
+  }
+}
+
+function toValidIdentifier(name: string): string {
+  if (/^[a-z_]/i.test(name)) {
+    return name
+  }
+
+  return `_${name}`
+}

src/core/analyze.ts

@@ -0,0 +1,12 @@
+import Handlebars from 'handlebars'
+import './templates/_partials/register__generated.js'
+
+// Join strings with a separator.
+Handlebars.registerHelper('join', (list, options) =>
+  list.map((item: any) => options.fn(item, { data: options.data })).join(options.hash.sep))
+
+// Create an array with a single element.
+Handlebars.registerHelper('singleton', val => [val])
+
+// Append an element to an array.
+Handlebars.registerHelper('append', (arr, val) => [...arr, val])

src/core/generate/handlebars.ts

@@ -0,0 +1,26 @@
+import type { GltfAnalysis, GltfNode } from '../analyze.js'
+import declaration from './templates/declaration.hbs.js'
+import './handlebars.js'
+
+export function generateModelDeclaration(
+  { imports, scenes }: GltfAnalysis,
+  identifiers: {
+    nodeGetter: string
+  },
+): string {
+  return declaration({
+    flattenedTree: scenes.flatMap(scene => flattenNodes(scene, [])),
+    identifiers,
+    imports: imports.toTemplateData(true),
+    scenes,
+  }).trim()
+}
+
+function flattenNodes(node: GltfNode, prefixPath: string[]): { names: string[], type: string }[] {
+  prefixPath = [...prefixPath, node.name]
+
+  return [
+    { names: prefixPath, type: node.type },
+    ...node.children.flatMap(child => flattenNodes(child, prefixPath)),
+  ]
+}