Add option to pass in custom handlebars templates #1268

README.md

@@ -50,11 +50,13 @@ $ openapi --help
     --postfixServices         Service name postfix (default: "Service")
     --postfixModels           Model name postfix
     --request <value>         Path to custom request file
+    --templateOverrides <list> List of template overrides in the format name:template
     -h, --help                display help for command
 
   Examples
     $ openapi --input ./spec.json --output ./generated
     $ openapi --input ./spec.json --output ./generated --client xhr
+    $ openapi --input ./spec.json --output ./generated --templateOverrides index:\"Hello World\" exportService:./templates/service.hbs"
 ```
 
 Documentation

bin/index.js

@@ -5,6 +5,12 @@
 const path = require('path');
 const { program } = require('commander');
 const pkg = require('../package.json');
+const getTemplateOverrides = list =>
+    list?.reduce((result, override) => {
+        const [name, value] = override.split(':');
+        if (name && value) result[name] = value;
+        return result;
+    }, {});
 
 const params = program
     .name('openapi')
@@ -24,6 +30,7 @@ const params = program
     .option('--postfixServices <value>', 'Service name postfix', 'Service')
     .option('--postfixModels <value>', 'Model name postfix')
     .option('--request <value>', 'Path to custom request file')
+    .option('--templateOverrides <name:template...>', 'List of template overrides in the format name:template')
     .parse(process.argv)
     .opts();
 
@@ -45,6 +52,7 @@ if (OpenAPI) {
         postfixServices: params.postfixServices,
         postfixModels: params.postfixModels,
         request: params.request,
+        templateOverrides: getTemplateOverrides(params.templateOverrides),
     })
         .then(() => {
             process.exit(0);

src/index.ts

@@ -1,3 +1,4 @@
+import { TemplateOverrideNames } from '../types';
 import { HttpClient } from './HttpClient';
 import { Indent } from './Indent';
 import { parse as parseV2 } from './openApi/v2';
@@ -28,6 +29,7 @@ export type Options = {
     postfixModels?: string;
     request?: string;
     write?: boolean;
+    templateOverrides?: Partial<Record<TemplateOverrideNames, string>>;
 };
 
 /**
@@ -49,6 +51,7 @@ export type Options = {
  * @param postfixModels Model name postfix
  * @param request Path to custom request file
  * @param write Write the files to disk (true or false)
+ * @param templateOverrides Override any template with a custom implementation
  */
 export const generate = async ({
     input,
@@ -66,13 +69,15 @@ export const generate = async ({
     postfixModels = '',
     request,
     write = true,
+    templateOverrides,
 }: Options): Promise<void> => {
     const openApi = isString(input) ? await getOpenApiSpec(input) : input;
     const openApiVersion = getOpenApiVersion(openApi);
     const templates = registerHandlebarTemplates({
         httpClient,
         useUnionTypes,
         useOptions,
+        templateOverrides,
     });
 
     switch (openApiVersion) {

src/utils/preCompileTemplate.spec.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from 'fs';
+import handlebars from 'handlebars';
+
+import { preCompileTemplate } from './preCompileTemplate';
+
+jest.mock('fs');
+jest.mock('handlebars');
+
+describe('preCompileTemplate', () => {
+    it('returns undefined if no file is provided', () => {
+        expect(preCompileTemplate()).toBeUndefined();
+    });
+
+    it('reads the file, trims it, and precompiles it', () => {
+        (readFileSync as jest.Mock).mockReturnValue({ toString: () => ' mock template ' });
+        (handlebars.precompile as jest.Mock).mockReturnValue('"mock template spec"');
+
+        const result = preCompileTemplate('mock-file.hbs');
+
+        expect(readFileSync).toHaveBeenCalledWith('mock-file.hbs', 'utf8');
+        expect(handlebars.precompile).toHaveBeenCalledWith('mock template', {
+            strict: true,
+            noEscape: true,
+            preventIndent: true,
+            knownHelpersOnly: true,
+            knownHelpers: {
+                ifdef: true,
+                equals: true,
+                notEquals: true,
+                containsSpaces: true,
+                union: true,
+                intersection: true,
+                enumerator: true,
+                escapeComment: true,
+                escapeDescription: true,
+                camelCase: true,
+            },
+        });
+        expect(result).toBe('mock template spec');
+    });
+});

src/utils/preCompileTemplate.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'fs';
+import handlebars from 'handlebars';
+import { extname } from 'path';
+
+/**
+ * Precompiles a Handlebars template from a given file.
+ *
+ * @param {string | undefined} file - The path to the file containing the Handlebars template.
+ * @returns {TemplateSpecification | undefined} - The precompiled template as a string, ready to be exported.
+ */
+export function preCompileTemplate(file?: string): TemplateSpecification | undefined {
+    if (!file) return;
+
+    const template = extname(file) === '.hbs' ? readFileSync(file, 'utf8').toString().trim() : file;
+    const templateSpec = handlebars.precompile(template, {
+        strict: true,
+        noEscape: true,
+        preventIndent: true,
+        knownHelpersOnly: true,
+        knownHelpers: {
+            ifdef: true,
+            equals: true,
+            notEquals: true,
+            containsSpaces: true,
+            union: true,
+            intersection: true,
+            enumerator: true,
+            escapeComment: true,
+            escapeDescription: true,
+            camelCase: true,
+        },
+    });
+
+    return eval(`(function(){return ${templateSpec} }());`);
+}

src/utils/registerHandlebarTemplates.spec.ts

@@ -1,21 +1,74 @@
+import Handlebars from 'handlebars/runtime';
+
 import { HttpClient } from '../HttpClient';
+import * as preCompiler from './preCompileTemplate';
 import { registerHandlebarTemplates } from './registerHandlebarTemplates';
 
+jest.mock('handlebars/runtime', () => ({
+    template: jest.fn((file: string) => file),
+    registerPartial: jest.fn((file: string) => file),
+    registerHelper: jest.fn((file: string) => file),
+}));
+
+jest.mock('./preCompileTemplate', () => ({
+    preCompileTemplate: jest.fn((file: string) => file),
+}));
+
 describe('registerHandlebarTemplates', () => {
-    it('should return correct templates', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should register handlebar templates', () => {
+        registerHandlebarTemplates({
+            httpClient: HttpClient.FETCH,
+            useOptions: false,
+            useUnionTypes: false,
+        });
+
+        expect(Handlebars.template).toHaveBeenCalled();
+        expect(Handlebars.registerPartial).toHaveBeenCalled();
+        expect(preCompiler.preCompileTemplate).toHaveBeenCalled();
+    });
+
+    it('should return default templates', () => {
+        const templates = registerHandlebarTemplates({
+            httpClient: HttpClient.FETCH,
+            useOptions: false,
+            useUnionTypes: false,
+        });
+
+        expect(templates.index).toHaveProperty('compiler');
+        expect(templates.exports.model).toHaveProperty('compiler');
+        expect(templates.exports.schema).toHaveProperty('compiler');
+        expect(templates.exports.service).toHaveProperty('compiler');
+        expect(templates.core.settings).toHaveProperty('compiler');
+        expect(templates.core.apiError).toHaveProperty('compiler');
+        expect(templates.core.apiRequestOptions).toHaveProperty('compiler');
+        expect(templates.core.apiResult).toHaveProperty('compiler');
+        expect(templates.core.request).toHaveProperty('compiler');
+    });
+
+    it('should allow template overrides', () => {
         const templates = registerHandlebarTemplates({
             httpClient: HttpClient.FETCH,
             useOptions: false,
             useUnionTypes: false,
+            templateOverrides: {
+                index: 'override',
+                exportService: 'override',
+                settings: 'override',
+            },
         });
-        expect(templates.index).toBeDefined();
-        expect(templates.exports.model).toBeDefined();
-        expect(templates.exports.schema).toBeDefined();
-        expect(templates.exports.service).toBeDefined();
-        expect(templates.core.settings).toBeDefined();
-        expect(templates.core.apiError).toBeDefined();
-        expect(templates.core.apiRequestOptions).toBeDefined();
-        expect(templates.core.apiResult).toBeDefined();
-        expect(templates.core.request).toBeDefined();
+
+        expect(templates.index).toBe('override');
+        expect(templates.exports.model).toHaveProperty('compiler');
+        expect(templates.exports.schema).toHaveProperty('compiler');
+        expect(templates.exports.service).toBe('override');
+        expect(templates.core.settings).toBe('override');
+        expect(templates.core.apiError).toHaveProperty('compiler');
+        expect(templates.core.apiRequestOptions).toHaveProperty('compiler');
+        expect(templates.core.apiResult).toHaveProperty('compiler');
+        expect(templates.core.request).toHaveProperty('compiler');
     });
 });