import { Context, createContext, runInNewContext } from "vm" import { create, TemplateDelegate } from "handlebars" import { registerAll, registerMinimum } from "./helpers/index" import { preprocess, postprocess } from "./processors" import { atob, btoa, isBackendService, FIND_HBS_REGEX, FIND_ANY_HBS_REGEX, findDoubleHbsInstances, } from "./utilities" import { convertHBSBlock } from "./conversion" import { setJSRunner, removeJSRunner } from "./helpers/javascript" import manifest from "./manifest.json" import { ProcessOptions } from "./types" export { helpersToRemoveForJs } from "./helpers/list" export { FIND_ANY_HBS_REGEX } from "./utilities" export { setJSRunner, setOnErrorLog } from "./helpers/javascript" export { iifeWrapper } from "./iife" const hbsInstance = create() registerAll(hbsInstance) const hbsInstanceNoHelpers = create() registerMinimum(hbsInstanceNoHelpers) const defaultOpts: ProcessOptions = { noHelpers: false, cacheTemplates: false, noEscaping: false, escapeNewlines: false, noFinalise: false, } /** * Utility function to check if the object is valid. */ function testObject(object: any) { // JSON stringify will fail if there are any cycles, stops infinite recursion try { JSON.stringify(object) } catch (err) { throw "Unable to process inputs to JSON, cannot recurse" } } /** * Creates a HBS template function for a given string, and optionally caches it. */ const templateCache: Record> = {} function createTemplate(string: string, opts?: ProcessOptions) { opts = { ...defaultOpts, ...opts } // Finalising adds a helper, can't do this with no helpers const key = `${string}-${JSON.stringify(opts)}` // Reuse the cached template is possible if (opts.cacheTemplates && templateCache[key]) { return templateCache[key] } string = preprocess(string, opts) // Optionally disable built in HBS escaping if (opts.noEscaping) { string = disableEscaping(string) } // This does not throw an error when template can't be fulfilled, // have to try correct beforehand const instance = opts.noHelpers ? hbsInstanceNoHelpers : hbsInstance const template = instance.compile(string, { strict: false, }) templateCache[key] = template return template } /** * Given an input object this will recurse through all props to try and update any handlebars statements within. * @param {object|array} object The input structure which is to be recursed, it is important to note that * if the structure contains any cycles then this will fail. * @param {object} context The context that handlebars should fill data from. * @param {object|undefined} [opts] optional - specify some options for processing. * @returns {Promise} The structure input, as fully updated as possible. */ export async function processObject>( object: T, context: object, opts?: { noHelpers?: boolean; escapeNewlines?: boolean; onlyFound?: boolean } ): Promise { testObject(object) for (const key of Object.keys(object || {})) { if (object[key] != null) { const val = object[key] let parsedValue = val if (typeof val === "string") { parsedValue = await processString(object[key], context, opts) } else if (typeof val === "object") { parsedValue = await processObject(object[key], context, opts) } // @ts-ignore object[key] = parsedValue } } return object } /** * This will process a single handlebars containing string. If the string passed in has no valid handlebars statements * then nothing will occur. * @param {string} string The template string which is the filled from the context object. * @param {object} context An object of information which will be used to enrich the string. * @param {object|undefined} [opts] optional - specify some options for processing. * @returns {Promise} The enriched string, all templates should have been replaced if they can be. */ export async function processString( string: string, context: object, opts?: ProcessOptions ): Promise { // TODO: carry out any async calls before carrying out async call return processStringSync(string, context, opts) } /** * Given an input object this will recurse through all props to try and update any handlebars statements within. This is * a pure sync call and therefore does not have the full functionality of the async call. * @param {object|array} object The input structure which is to be recursed, it is important to note that * if the structure contains any cycles then this will fail. * @param {object} context The context that handlebars should fill data from. * @param {object|undefined} [opts] optional - specify some options for processing. * @returns {object|array} The structure input, as fully updated as possible. */ export function processObjectSync( object: { [x: string]: any }, context: any, opts: any ): object | Array { testObject(object) for (let key of Object.keys(object || {})) { let val = object[key] if (typeof val === "string") { object[key] = processStringSync(object[key], context, opts) } else if (typeof val === "object") { object[key] = processObjectSync(object[key], context, opts) } } return object } /** * This will process a single handlebars containing string. If the string passed in has no valid handlebars statements * then nothing will occur. This is a pure sync call and therefore does not have the full functionality of the async call. * @param {string} string The template string which is the filled from the context object. * @param {object} context An object of information which will be used to enrich the string. * @param {object|undefined} [opts] optional - specify some options for processing. * @returns {string} The enriched string, all templates should have been replaced if they can be. */ export function processStringSync( string: string, context?: object, opts?: ProcessOptions ): string { // Take a copy of input in case of error const input = string if (typeof string !== "string") { throw "Cannot process non-string types." } function process(stringPart: string) { const template = createTemplate(stringPart, opts) const now = Math.floor(Date.now() / 1000) * 1000 const processedString = template({ now: new Date(now).toISOString(), __opts: { ...opts, input: stringPart, }, ...context, }) return postprocess(processedString) } try { if (opts && opts.onlyFound) { const blocks = findHBSBlocks(string) for (let block of blocks) { const outcome = process(block) string = string.replace(block, outcome) } return string } else { return process(string) } } catch (err) { return input } } /** * By default with expressions like {{ name }} handlebars will escape various * characters, which can be problematic. To fix this we use the syntax {{{ name }}}, * this function will find any double braces and switch to triple. * @param string the string to have double HBS statements converted to triple. */ export function disableEscaping(string: string) { const matches = findDoubleHbsInstances(string) if (matches == null) { return string } // find the unique set const unique = [...new Set(matches)] for (let match of unique) { // add a negative lookahead to exclude any already const regex = new RegExp(`${match}(?!})`, "g") string = string.replace(regex, `{${match}}`) } return string } /** * Simple utility function which makes sure that a templating property has been wrapped in literal specifiers correctly. * @param {string} property The property which is to be wrapped. * @returns {string} The wrapped property ready to be added to a templating string. */ export function makePropSafe(property: any): string { return `[${property}]`.replace("[[", "[").replace("]]", "]") } /** * Checks whether or not a template string contains totally valid syntax (simply tries running it) * @param string The string to test for valid syntax - this may contain no templates and will be considered valid. * @param [opts] optional - specify some options for processing. * @returns {boolean} Whether or not the input string is valid. */ export function isValid(string: any, opts?: any): boolean { const validCases = [ "string", "number", "object", "array", "cannot read property", "undefined", "json at position 0", ] // this is a portion of a specific string always output by handlebars in the case of a syntax error const invalidCases = [`expecting '`] // don't really need a real context to check if its valid const context = {} try { const template = createTemplate(string, { ...opts, noFinalise: true, }) template(context) return true } catch (err: any) { const msg = err && err.message ? err.message : err if (!msg) { return false } const invalidCase = invalidCases.some(invalidCase => msg.toLowerCase().includes(invalidCase) ) const validCase = validCases.some(validCase => msg.toLowerCase().includes(validCase) ) // special case for maths functions - don't have inputs yet return validCase && !invalidCase } } /** * We have generated a static manifest file from the helpers that this string templating package makes use of. * This manifest provides information about each of the helpers and how it can be used. * @returns The manifest JSON which has been generated from the helpers. */ export function getManifest() { return manifest } /** * Checks if a HBS expression is a valid JS HBS expression * @param handlebars the HBS expression to check * @returns {boolean} whether the expression is JS or not */ export function isJSBinding(handlebars: any): boolean { return decodeJSBinding(handlebars) != null } /** * Encodes a raw JS string as a JS HBS expression * @param javascript the JS code to encode * @returns {string} the JS HBS expression */ export function encodeJSBinding(javascript: string): string { return `{{ js "${btoa(javascript)}" }}` } /** * Decodes a JS HBS expression to the raw JS code * @param handlebars the JS HBS expression * @returns {string|null} the raw JS code */ export function decodeJSBinding(handlebars: string): string | null { if (!handlebars || typeof handlebars !== "string") { return null } // JS is only valid if it is the only HBS expression if (!handlebars.trim().startsWith("{{ js ")) { return null } const captureJSRegex = new RegExp(/{{ js "(.*)" }}/) const match = handlebars.match(captureJSRegex) if (!match || match.length < 2) { return null } return atob(match[1]) } /** * Same as the doesContainString function, but will check for all the strings * before confirming it contains. * @param {string} template The template string to search. * @param {string[]} strings The strings to look for. * @returns {boolean} Will return true if all strings found in HBS statement. */ export function doesContainStrings(template: string, strings: any[]): boolean { let regexp = new RegExp(FIND_HBS_REGEX) let matches = template.match(regexp) if (matches == null) { return false } for (let match of matches) { let hbs = match if (isJSBinding(match)) { hbs = decodeJSBinding(match)! } let allFound = true for (let string of strings) { if (!hbs.includes(string)) { allFound = false } } if (allFound) { return true } } return false } /** * Given a string, this will return any {{ binding }} or {{{ binding }}} type * statements. * @param {string} string The string to search within. * @return {string[]} The found HBS blocks. */ export function findHBSBlocks(string: string): string[] { if (!string || typeof string !== "string") { return [] } let regexp = new RegExp(FIND_ANY_HBS_REGEX) let matches = string.match(regexp) if (matches == null) { return [] } return matches } /** * This function looks in the supplied template for handlebars instances, if they contain * JS the JS will be decoded and then the supplied string will be looked for. For example * if the template "Hello, your name is {{ related }}" this function would return that true * for the string "related" but not for "name" as it is not within the handlebars statement. * @param {string} template A template string to search for handlebars instances. * @param {string} string The word or sentence to search for. * @returns {boolean} The this return true if the string is found, false if not. */ export function doesContainString(template: any, string: any): boolean { return doesContainStrings(template, [string]) } export function convertToJS(hbs: string) { const blocks = findHBSBlocks(hbs) let js = "return `", prevBlock: string | null = null const variables: Record = {} if (blocks.length === 0) { js += hbs } let count = 1 for (let block of blocks) { let stringPart = hbs if (prevBlock) { stringPart = stringPart.split(prevBlock)[1] } stringPart = stringPart.split(block)[0] prevBlock = block const { variable, value } = convertHBSBlock(block, count++) variables[variable] = value js += `${[stringPart]}\${${variable}}` } let varBlock = "" for (let [variable, value] of Object.entries(variables)) { varBlock += `const ${variable} = ${value};\n` } js += "`;" return `${varBlock}${js}` } export { JsErrorTimeout } from "./errors" export function defaultJSSetup() { if (!isBackendService()) { /** * Use polyfilled vm to run JS scripts in a browser Env */ setJSRunner((js: string, context: Context) => { context = { ...context, alert: undefined, setInterval: undefined, setTimeout: undefined, } createContext(context) return runInNewContext(js, context, { timeout: 1000 }) }) } else { removeJSRunner() } } defaultJSSetup()