/* * Elasticsearch B.V licenses this file to you under the MIT License. * See `packages/kbn-handlebars/LICENSE` for more information. */ import Handlebars from 'handlebars'; import { createProtoAccessControl, resultIsAllowed, // @ts-expect-error: Could not find a declaration file for module } from 'handlebars/dist/cjs/handlebars/internal/proto-access'; // @ts-expect-error: Could not find a declaration file for module import AST from 'handlebars/dist/cjs/handlebars/compiler/ast'; // @ts-expect-error: Could not find a declaration file for module import { indexOf, createFrame } from 'handlebars/dist/cjs/handlebars/utils'; // @ts-expect-error: Could not find a declaration file for module import { moveHelperToHooks } from 'handlebars/dist/cjs/handlebars/helpers'; import type { AmbiguousHelperOptions, CompileOptions, Container, DecoratorDelegate, DecoratorsHash, HelperOptions, NodeType, NonBlockHelperOptions, ProcessableBlockStatementNode, ProcessableNode, ProcessableNodeWithPathParts, ProcessableNodeWithPathPartsOrLiteral, ProcessableStatementNode, ResolvePartialOptions, RuntimeOptions, Template, TemplateDelegate, VisitorHelper, } from './types'; import { kAmbiguous, kHelper, kSimple } from './symbols'; import { initData, isBlock, isDecorator, noop, toDecoratorOptions, transformLiteralToPath, } from './utils'; export class ElasticHandlebarsVisitor extends Handlebars.Visitor { private env: typeof Handlebars; private contexts: any[] = []; private output: any[] = []; private template?: string; private compileOptions: CompileOptions; private runtimeOptions?: RuntimeOptions; private blockParamNames: any[][] = []; private blockParamValues: any[][] = []; private ast?: hbs.AST.Program; private container: Container; private defaultHelperOptions: Pick<NonBlockHelperOptions, 'lookupProperty'>; private processedRootDecorators = false; // Root decorators should not have access to input arguments. This flag helps us detect them. private processedDecoratorsForProgram = new Set(); // It's important that a given program node only has its decorators run once, we use this Map to keep track of them constructor( env: typeof Handlebars, input: string | hbs.AST.Program, options: CompileOptions = {} ) { super(); this.env = env; if (typeof input !== 'string' && input.type === 'Program') { this.ast = input; } else { this.template = input as string; } this.compileOptions = { data: true, ...options }; this.compileOptions.knownHelpers = Object.assign( Object.create(null), { helperMissing: true, blockHelperMissing: true, each: true, if: true, unless: true, with: true, log: true, lookup: true, }, this.compileOptions.knownHelpers ); const protoAccessControl = createProtoAccessControl({}); const container: Container = (this.container = { helpers: {}, partials: {}, decorators: {}, strict(obj, name, loc) { if (!obj || !(name in obj)) { throw new Handlebars.Exception('"' + name + '" not defined in ' + obj, { loc, } as hbs.AST.Node); } return container.lookupProperty(obj, name); }, // this function is lifted from the handlebars source and slightly modified (lib/handlebars/runtime.js) lookupProperty(parent, propertyName) { const result = parent[propertyName]; if (result == null) { return result; } if (Object.prototype.hasOwnProperty.call(parent, propertyName)) { return result; } if (resultIsAllowed(result, protoAccessControl, propertyName)) { return result; } return undefined; }, // this function is lifted from the handlebars source and slightly modified (lib/handlebars/runtime.js) lambda(current, context) { return typeof current === 'function' ? current.call(context) : current; }, data(value: any, depth: number) { while (value && depth--) { value = value._parent; } return value; }, hooks: {}, }); this.defaultHelperOptions = { lookupProperty: container.lookupProperty, }; } render(context: any, options: RuntimeOptions = {}): string { this.contexts = [context]; this.output = []; this.runtimeOptions = { ...options }; this.container.helpers = { ...this.env.helpers, ...options.helpers }; this.container.partials = { ...this.env.partials, ...options.partials }; this.container.decorators = { ...(this.env.decorators as DecoratorsHash), ...options.decorators, }; this.container.hooks = {}; this.processedRootDecorators = false; this.processedDecoratorsForProgram.clear(); if (this.compileOptions.data) { this.runtimeOptions.data = initData(context, this.runtimeOptions.data); } const keepHelperInHelpers = false; moveHelperToHooks(this.container, 'helperMissing', keepHelperInHelpers); moveHelperToHooks(this.container, 'blockHelperMissing', keepHelperInHelpers); if (!this.ast) { this.ast = Handlebars.parse(this.template!); } // The `defaultMain` function contains the default behavior: // // Generate a "program" function based on the root `Program` in the AST and // call it. This will start the processing of all the child nodes in the // AST. const defaultMain: TemplateDelegate = (_context) => { const prog = this.generateProgramFunction(this.ast!); return prog(_context, this.runtimeOptions); }; // Run any decorators that might exist on the root: // // The `defaultMain` function is passed in, and if there are no root // decorators, or if the decorators chooses to do so, the same function is // returned from `processDecorators` and the default behavior is retained. // // Alternatively any of the root decorators might call the `defaultMain` // function themselves, process its return value, and return a completely // different `main` function. const main = this.processDecorators(this.ast, defaultMain); this.processedRootDecorators = true; // Call the `main` function and add the result to the final output. const result = main(this.context, options); if (main === defaultMain) { this.output.push(result); return this.output.join(''); } else { // We normally expect the return value of `main` to be a string. However, // if a decorator is used to override the `defaultMain` function, the // return value can be any type. To match the upstream handlebars project // behavior, we want the result of rendering the template to be the // literal value returned by the decorator. // // Since the output array in this case always will be empty, we just // return that single value instead of attempting to join all the array // elements as strings. return result; } } // ********************************************** // // *** Visitor AST Traversal Functions *** // // ********************************************** // Program(program: hbs.AST.Program) { this.blockParamNames.unshift(program.blockParams); super.Program(program); this.blockParamNames.shift(); } MustacheStatement(mustache: hbs.AST.MustacheStatement) { this.processStatementOrExpression(mustache); } BlockStatement(block: hbs.AST.BlockStatement) { this.processStatementOrExpression(block); } PartialStatement(partial: hbs.AST.PartialStatement) { this.invokePartial(partial); } PartialBlockStatement(partial: hbs.AST.PartialBlockStatement) { this.invokePartial(partial); } // This space is intentionally left blank: We want to override the Visitor // class implementation of this method, but since we handle decorators // separately before traversing the nodes, we just want to make this a no-op. DecoratorBlock(decorator: hbs.AST.DecoratorBlock) {} // This space is intentionally left blank: We want to override the Visitor // class implementation of this method, but since we handle decorators // separately before traversing the nodes, we just want to make this a no-op. Decorator(decorator: hbs.AST.Decorator) {} SubExpression(sexpr: hbs.AST.SubExpression) { this.processStatementOrExpression(sexpr); } PathExpression(path: hbs.AST.PathExpression) { const blockParamId = !path.depth && !AST.helpers.scopedId(path) && this.blockParamIndex(path.parts[0]); let result; if (blockParamId) { result = this.lookupBlockParam(blockParamId, path); } else if (path.data) { result = this.lookupData(this.runtimeOptions!.data, path); } else { result = this.resolvePath(this.contexts[path.depth], path); } this.output.push(result); } ContentStatement(content: hbs.AST.ContentStatement) { this.output.push(content.value); } StringLiteral(string: hbs.AST.StringLiteral) { this.output.push(string.value); } NumberLiteral(number: hbs.AST.NumberLiteral) { this.output.push(number.value); } BooleanLiteral(bool: hbs.AST.BooleanLiteral) { this.output.push(bool.value); } UndefinedLiteral() { this.output.push(undefined); } NullLiteral() { this.output.push(null); } // ********************************************** // // *** Visitor AST Helper Functions *** // // ********************************************** // /** * Special code for decorators, since they have to be executed ahead of time (before the wrapping program). * So we have to look into the program AST body and see if it contains any decorators that we have to process * before we can finish processing of the wrapping program. */ private processDecorators(program: hbs.AST.Program, prog: TemplateDelegate) { if (!this.processedDecoratorsForProgram.has(program)) { this.processedDecoratorsForProgram.add(program); const props = {}; for (const node of program.body) { if (isDecorator(node)) { prog = this.processDecorator(node, prog, props); } } } return prog; } private processDecorator( decorator: hbs.AST.DecoratorBlock | hbs.AST.Decorator, prog: TemplateDelegate, props: Record<string, any> ) { const options = this.setupDecoratorOptions(decorator); const result = this.container.lookupProperty<DecoratorDelegate>( this.container.decorators, options.name )(prog, props, this.container, options); return Object.assign(result || prog, props); } private processStatementOrExpression(node: ProcessableNodeWithPathPartsOrLiteral) { // Calling `transformLiteralToPath` has side-effects! // It converts a node from type `ProcessableNodeWithPathPartsOrLiteral` to `ProcessableNodeWithPathParts` transformLiteralToPath(node); switch (this.classifyNode(node as ProcessableNodeWithPathParts)) { case kSimple: this.processSimpleNode(node as ProcessableNodeWithPathParts); break; case kHelper: this.processHelperNode(node as ProcessableNodeWithPathParts); break; case kAmbiguous: this.processAmbiguousNode(node as ProcessableNodeWithPathParts); break; } } // Liftet from lib/handlebars/compiler/compiler.js (original name: classifySexpr) private classifyNode(node: { path: hbs.AST.PathExpression }): NodeType { const isSimple = AST.helpers.simpleId(node.path); const isBlockParam = isSimple && !!this.blockParamIndex(node.path.parts[0]); // a mustache is an eligible helper if: // * its id is simple (a single part, not `this` or `..`) let isHelper = !isBlockParam && AST.helpers.helperExpression(node); // if a mustache is an eligible helper but not a definite // helper, it is ambiguous, and will be resolved in a later // pass or at runtime. let isEligible = !isBlockParam && (isHelper || isSimple); // if ambiguous, we can possibly resolve the ambiguity now // An eligible helper is one that does not have a complex path, i.e. `this.foo`, `../foo` etc. if (isEligible && !isHelper) { const name = node.path.parts[0]; const options = this.compileOptions; if (options.knownHelpers && options.knownHelpers[name]) { isHelper = true; } else if (options.knownHelpersOnly) { isEligible = false; } } if (isHelper) { return kHelper; } else if (isEligible) { return kAmbiguous; } else { return kSimple; } } // Liftet from lib/handlebars/compiler/compiler.js private blockParamIndex(name: string): [number, any] | undefined { for (let depth = 0, len = this.blockParamNames.length; depth < len; depth++) { const blockParams = this.blockParamNames[depth]; const param = blockParams && indexOf(blockParams, name); if (blockParams && param >= 0) { return [depth, param]; } } } // Looks up the value of `parts` on the given block param and pushes // it onto the stack. private lookupBlockParam(blockParamId: [number, any], path: hbs.AST.PathExpression) { const value = this.blockParamValues[blockParamId[0]][blockParamId[1]]; return this.resolvePath(value, path, 1); } // Push the data lookup operator private lookupData(data: any, path: hbs.AST.PathExpression) { if (path.depth) { data = this.container.data(data, path.depth); } return this.resolvePath(data, path); } private processSimpleNode(node: ProcessableNodeWithPathParts) { const path = node.path; // @ts-expect-error strict is not a valid property on PathExpression, but we used in the same way it's also used in the original handlebars path.strict = true; const result = this.resolveNodes(path)[0]; const lambdaResult = this.container.lambda(result, this.context); if (isBlock(node)) { this.blockValue(node, lambdaResult); } else { this.output.push(lambdaResult); } } // The purpose of this opcode is to take a block of the form // `{{#this.foo}}...{{/this.foo}}`, resolve the value of `foo`, and // replace it on the stack with the result of properly // invoking blockHelperMissing. private blockValue(node: hbs.AST.BlockStatement, value: any) { const name = node.path.original; const options = this.setupParams(node, name); const result = this.container.hooks.blockHelperMissing!.call(this.context, value, options); this.output.push(result); } private processHelperNode(node: ProcessableNodeWithPathParts) { const path = node.path; const name = path.parts[0]; if (this.compileOptions.knownHelpers && this.compileOptions.knownHelpers[name]) { this.invokeKnownHelper(node); } else if (this.compileOptions.knownHelpersOnly) { throw new Handlebars.Exception( 'You specified knownHelpersOnly, but used the unknown helper ' + name, node ); } else { this.invokeHelper(node); } } // This operation is used when the helper is known to exist, // so a `helperMissing` fallback is not required. private invokeKnownHelper(node: ProcessableNodeWithPathParts) { const name = node.path.parts[0]; const helper = this.setupHelper(node, name); // TypeScript: `helper.fn` might be `undefined` at this point, but to match the upstream behavior we call it without any guards const result = helper.fn!.call(helper.context, ...helper.params, helper.options); this.output.push(result); } // Pops off the helper's parameters, invokes the helper, // and pushes the helper's return value onto the stack. // // If the helper is not found, `helperMissing` is called. private invokeHelper(node: ProcessableNodeWithPathParts) { const path = node.path; const name = path.original; const isSimple = AST.helpers.simpleId(path); const helper = this.setupHelper(node, name); const loc = isSimple && helper.fn ? node.loc : path.loc; helper.fn = (isSimple && helper.fn) || this.resolveNodes(path)[0]; if (!helper.fn) { if (this.compileOptions.strict) { helper.fn = this.container.strict(helper.context, name, loc); } else { helper.fn = this.container.hooks.helperMissing; } } // TypeScript: `helper.fn` might be `undefined` at this point, but to match the upstream behavior we call it without any guards const result = helper.fn!.call(helper.context, ...helper.params, helper.options); this.output.push(result); } private invokePartial(partial: hbs.AST.PartialStatement | hbs.AST.PartialBlockStatement) { const { params } = partial; if (params.length > 1) { throw new Handlebars.Exception( `Unsupported number of partial arguments: ${params.length}`, partial ); } const isDynamic = partial.name.type === 'SubExpression'; const name = isDynamic ? this.resolveNodes(partial.name).join('') : (partial.name as hbs.AST.PathExpression).original; const options: AmbiguousHelperOptions & ResolvePartialOptions = this.setupParams(partial, name); options.helpers = this.container.helpers; options.partials = this.container.partials; options.decorators = this.container.decorators; let partialBlock; if ('fn' in options && options.fn !== noop) { const { fn } = options; const currentPartialBlock = options.data?.['partial-block']; options.data = createFrame(options.data); // Wrapper function to get access to currentPartialBlock from the closure partialBlock = options.data['partial-block'] = function partialBlockWrapper( context: any, wrapperOptions: { data?: HelperOptions['data'] } = {} ) { // Restore the partial-block from the closure for the execution of the block // i.e. the part inside the block of the partial call. wrapperOptions.data = createFrame(wrapperOptions.data); wrapperOptions.data['partial-block'] = currentPartialBlock; return fn(context, wrapperOptions); }; if (fn.partials) { options.partials = { ...options.partials, ...fn.partials }; } } let context = {}; if (params.length === 0 && !this.compileOptions.explicitPartialContext) { context = this.context; } else if (params.length === 1) { context = this.resolveNodes(params[0])[0]; } if (Object.keys(options.hash).length > 0) { // TODO: context can be an array, but maybe never when we have a hash??? context = Object.assign({}, context, options.hash); } const partialTemplate: Template | undefined = this.container.partials[name] ?? partialBlock ?? // TypeScript note: We extend ResolvePartialOptions in our types.ts file // to fix an error in the upstream type. When calling back into the // upstream code, we just cast back to the non-extended type Handlebars.VM.resolvePartial( undefined, undefined, options as Handlebars.ResolvePartialOptions ); if (partialTemplate === undefined) { throw new Handlebars.Exception(`The partial ${name} could not be found`); } let render; if (typeof partialTemplate === 'string') { render = this.env.compileAST(partialTemplate, this.compileOptions); if (name in this.container.partials) { this.container.partials[name] = render; } } else { render = partialTemplate; } let result = render(context, options); if ('indent' in partial) { result = partial.indent + (this.compileOptions.preventIndent ? result : result.replace(/\n(?!$)/g, `\n${partial.indent}`)); // indent each line, ignoring any trailing linebreak } this.output.push(result); } private processAmbiguousNode(node: ProcessableNodeWithPathParts) { const name = node.path.parts[0]; const helper = this.setupHelper(node, name); let { fn: helperFn } = helper; const loc = helperFn ? node.loc : node.path.loc; helperFn = helperFn ?? this.resolveNodes(node.path)[0]; if (helperFn === undefined) { if (this.compileOptions.strict) { helperFn = this.container.strict(helper.context, name, loc); } else { helperFn = helper.context != null ? this.container.lookupProperty(helper.context, name) : helper.context; if (helperFn == null) helperFn = this.container.hooks.helperMissing; } } const helperResult = typeof helperFn === 'function' ? helperFn.call(helper.context, ...helper.params, helper.options) : helperFn; if (isBlock(node)) { const result = helper.fn ? helperResult : this.container.hooks.blockHelperMissing!.call(this.context, helperResult, helper.options); if (result != null) { this.output.push(result); } } else { if ( (node as hbs.AST.MustacheStatement).escaped === false || this.compileOptions.noEscape === true || typeof helperResult !== 'string' ) { this.output.push(helperResult); } else { this.output.push(Handlebars.escapeExpression(helperResult)); } } } private setupHelper(node: ProcessableNode, helperName: string): VisitorHelper { return { fn: this.container.lookupProperty(this.container.helpers, helperName), context: this.context, params: this.resolveNodes(node.params), options: this.setupParams(node, helperName), }; } private setupDecoratorOptions(decorator: hbs.AST.Decorator | hbs.AST.DecoratorBlock) { // TypeScript: The types indicate that `decorator.path` technically can be an `hbs.AST.Literal`. However, the upstream codebase always treats it as an `hbs.AST.PathExpression`, so we do too. const name = (decorator.path as hbs.AST.PathExpression).original; const options = toDecoratorOptions(this.setupParams(decorator, name)); if (decorator.params.length > 0) { if (!this.processedRootDecorators) { // When processing the root decorators, temporarily remove the root context so it's not accessible to the decorator const context = this.contexts.shift(); options.args = this.resolveNodes(decorator.params); this.contexts.unshift(context); } else { options.args = this.resolveNodes(decorator.params); } } else { options.args = []; } return options; } private setupParams(node: ProcessableBlockStatementNode, name: string): HelperOptions; private setupParams(node: ProcessableStatementNode, name: string): NonBlockHelperOptions; private setupParams(node: ProcessableNode, name: string): AmbiguousHelperOptions; private setupParams(node: ProcessableNode, name: string) { const options: AmbiguousHelperOptions = { name, hash: this.getHash(node), data: this.runtimeOptions!.data, loc: { start: node.loc.start, end: node.loc.end }, ...this.defaultHelperOptions, }; if (isBlock(node)) { (options as HelperOptions).fn = node.program ? this.processDecorators(node.program, this.generateProgramFunction(node.program)) : noop; (options as HelperOptions).inverse = node.inverse ? this.processDecorators(node.inverse, this.generateProgramFunction(node.inverse)) : noop; } return options; } private generateProgramFunction(program: hbs.AST.Program) { if (!program) return noop; const prog: TemplateDelegate = (nextContext: any, runtimeOptions: RuntimeOptions = {}) => { runtimeOptions = { ...runtimeOptions }; // inherit data in blockParams from parent program runtimeOptions.data = runtimeOptions.data || this.runtimeOptions!.data; if (runtimeOptions.blockParams) { runtimeOptions.blockParams = runtimeOptions.blockParams.concat( this.runtimeOptions!.blockParams ); } // inherit partials from parent program runtimeOptions.partials = runtimeOptions.partials || this.runtimeOptions!.partials; // stash parent program data const tmpRuntimeOptions = this.runtimeOptions; this.runtimeOptions = runtimeOptions; const shiftContext = nextContext !== this.context; if (shiftContext) this.contexts.unshift(nextContext); this.blockParamValues.unshift(runtimeOptions.blockParams || []); // execute child program const result = this.resolveNodes(program).join(''); // unstash parent program data this.blockParamValues.shift(); if (shiftContext) this.contexts.shift(); this.runtimeOptions = tmpRuntimeOptions; // return result of child program return result; }; prog.blockParams = program.blockParams?.length ?? 0; return prog; } private getHash(statement: { hash?: hbs.AST.Hash }) { const result: { [key: string]: any } = {}; if (!statement.hash) return result; for (const { key, value } of statement.hash.pairs) { result[key] = this.resolveNodes(value)[0]; } return result; } private resolvePath(obj: any, path: hbs.AST.PathExpression, index = 0) { if (this.compileOptions.strict || this.compileOptions.assumeObjects) { return this.strictLookup(obj, path); } for (; index < path.parts.length; index++) { if (obj == null) return; obj = this.container.lookupProperty(obj, path.parts[index]); } return obj; } private strictLookup(obj: any, path: hbs.AST.PathExpression) { // @ts-expect-error strict is not a valid property on PathExpression, but we used in the same way it's also used in the original handlebars const requireTerminal = this.compileOptions.strict && path.strict; const len = path.parts.length - (requireTerminal ? 1 : 0); for (let i = 0; i < len; i++) { obj = this.container.lookupProperty(obj, path.parts[i]); } if (requireTerminal) { return this.container.strict(obj, path.parts[len], path.loc); } else { return obj; } } private resolveNodes(nodes: hbs.AST.Node | hbs.AST.Node[]): any[] { const currentOutput = this.output; this.output = []; if (Array.isArray(nodes)) { this.acceptArray(nodes); } else { this.accept(nodes); } const result = this.output; this.output = currentOutput; return result; } private get context() { return this.contexts[0]; } }