@accordproject/template-engine 2.8.0 → 3.0.1

package/README.md

@@ -20,6 +20,31 @@ At a high-level the template engine converts a TemplateMark DOM to an AgreementM
 
 ![Template Interpreter](./assets/template-interpreter.png)
 
+## Execution Pipeline Overview
+
+Internally, the Template Engine evaluates templates through a structured execution pipeline:
+
+1. **Type Validation**  
+   The TemplateMark JSON document and the incoming agreement data are validated against their respective Concerto models to ensure structural and type correctness.
+
+2. **TypeScript Compilation**  
+   Embedded TypeScript expressions (such as conditionals, clauses, and formulae) are compiled into JavaScript using the `TemplateMarkToJavaScriptCompiler`.
+
+3. **User Code Evaluation**  
+   During agreement generation, compiled JavaScript expressions are evaluated using the `JavaScriptEvaluator`.  
+   The evaluator supports two execution strategies:
+   - `evalDangerously()` — Executes JavaScript directly within the current       process. 
+   This should only be used with trusted code or in a sandboxed environment (e.g., browser).
+   - `evalChildProcess()` — Executes JavaScript in an isolated Node.js child process for improved safety and isolation and is recommended for untrusted template content on the server.
+
+4. **AgreementMark Generation**  
+   The TemplateMark document is traversed, evaluated values are inserted into the document structure, and an AgreementMark JSON document is produced.
+
+5. **Output Validation**  
+   The generated AgreementMark document is validated before being returned.
+
+This layered architecture ensures type-safety, deterministic execution of template logic, and isolation during runtime evaluation.
+
 ## Hello World Template
 
 Let's create the simplest template imaginable, the infamous "hello world"!
@@ -102,7 +127,7 @@ This AgreementMark JSON document can then be passed to the `@accordproject/markd
 
 The Hello World example just scratches the surface of what can be accomplished! TemplateMark can define optional sections, conditional sections, TypeScript formulae/calculations and even reference external data.
 
-Refer to the [full](https://github.com/accordproject/template-engine/tree/main/test/templates/full) example for details. 
+Refer to the [full](https://github.com/accordproject/template-engine/tree/main/test/templates/good/full) example for details. 
 
 > More detailed syntax documentation is to come!
 Read the existing documentation at: https://docs.accordproject.org/docs/markup-templatemark.html

package/dist/index.d.ts

@@ -152,15 +152,15 @@ declare class TemplateArchiveProcessor {
      * @param {object} request - the request to send to the template logic
      * @param {object} state - the current state of the template
      * @param {[string]} currentTime - the current time, defaults to now
-     * @param {[number]} utcOffset - the UTC offer, defaults to zero
+     * @param {[number]} utcOffset - the UTC offset, defaults to zero
      * @returns {Promise} the response and any events
      */
     trigger(data: any, request: any, state?: any, currentTime?: string, utcOffset?: number): Promise<TriggerResponse>;
     /**
      * Init the logic of a template
      * @param {[string]} currentTime - the current time, defaults to now
-     * @param {[number]} utcOffset - the UTC offer, defaults to zero
-     * @returns {Promise} the response and any events
+     * @param {[number]} utcOffset - the UTC offset, defaults to zero
+     * @returns {Promise<InitResponse>} the new state
      */
     init(data: any, currentTime?: string, utcOffset?: number): Promise<InitResponse>;
 }

package/dist/index.js

@@ -122,6 +122,16 @@ function integerDrafter(value, format) {
   }
 }
 
+function isDuration(value) {
+  return value != null && typeof value === "object" && "amount" in value && "unit" in value && typeof value.amount === "number" && typeof value.unit === "string";
+}
+function durationDrafter(value) {
+  if (!isDuration(value)) {
+    return "0 unknown";
+  }
+  return `${value.amount} ${value.unit}`;
+}
+
 function longDrafter(value, format) {
   if (format) {
     return draftIntegerFormat(value, format);
@@ -210,6 +220,10 @@ function getDrafter(typeName) {
       return longDrafter;
     case "org.accordproject.money@0.3.0.MonetaryAmount":
       return monetaryAmountDrafter;
+    case "org.accordproject.time@0.3.0.Duration":
+      return durationDrafter;
+    case "org.accordproject.time@0.3.0.Period":
+      return durationDrafter;
     case "String":
       return stringDrafter;
     default:
@@ -700,7 +714,7 @@ function getJsonPath(rootData, currentNode, paths) {
       }
     }
   }
-  if (currentNode.name !== "this") {
+  if (currentNode.name !== "this" && currentNode.name !== "top") {
     withPath.push(`['${currentNode.name}']`);
   }
   return withPath.length > 0 ? `$${withPath.join("")}` : "$";
@@ -890,8 +904,17 @@ async function generateAgreement(modelManager, clauseLibrary, templateMark, data
         }
       } else if (CONDITIONAL_DEFINITION_RE.test(nodeClass)) {
         if (context.condition) {
-          const result = userCodeResults[this.path.join("/")];
-          context.isTrue = !!result;
+          const key = this.path.join("/");
+          const resultStr = userCodeResults[key];
+          if (resultStr === void 0 || resultStr === null) {
+            context.isTrue = false;
+          } else {
+            try {
+              context.isTrue = !!JSON.parse(resultStr);
+            } catch (err) {
+              throw new Error(`Invalid JSON boolean result for condition '${key}': ${String(err)}`);
+            }
+          }
         } else {
           const path = getJsonPath(templateMark, context, this.path);
           const variableValues = jp.query(data, path, 1);
@@ -912,16 +935,27 @@ async function generateAgreement(modelManager, clauseLibrary, templateMark, data
       } else if (CLAUSE_DEFINITION_RE.test(nodeClass)) {
         const path = getJsonPath(templateMark, context, this.path);
         const variableValues = jp.query(data, path, 1);
-        if (context.name !== "top" && (variableValues.length === 0 || variableValues[0] === void 0 || variableValues[0] === null)) {
-          delete context.nodes;
-          stopHere = true;
-        } else if (context.condition) {
+        if (context.condition) {
           checkCode(context.condition);
-          const result = !!userCodeResults[this.path.join("/")];
+          const key = this.path.join("/");
+          const resultStr = userCodeResults[key];
+          let result = false;
+          if (resultStr === void 0 || resultStr === null) {
+            result = false;
+          } else {
+            try {
+              result = !!JSON.parse(resultStr);
+            } catch (err) {
+              throw new Error(`Invalid JSON boolean result for condition '${key}': ${String(err)}`);
+            }
+          }
           if (!result) {
             delete context.nodes;
             stopHere = true;
           }
+        } else if (context.name !== "top" && (variableValues.length === 0 || variableValues[0] === void 0 || variableValues[0] === null)) {
+          delete context.nodes;
+          stopHere = true;
         }
         delete context.condition;
         delete context.functionName;
@@ -970,18 +1004,53 @@ class TemplateMarkInterpreter {
    * @throws {Error} if the templateMark document is invalid
    */
   checkTypes(templateMark) {
-    const modelManager = new concertoCore.ModelManager({ strict: true });
+    const modelManager = new concertoCore.ModelManager();
     modelManager.addCTOModel(markdownCommon.ConcertoMetaModel.MODEL, "concertometamodel.cto");
     modelManager.addCTOModel(markdownCommon.CommonMarkModel.MODEL, "commonmark.cto");
     modelManager.addCTOModel(markdownCommon.TemplateMarkModel.MODEL, "templatemark.cto");
     const factory = new concertoCore.Factory(modelManager);
-    const serializer = new concertoCore.Serializer(factory, modelManager);
+    const serializer = new concertoCore.Serializer(factory, modelManager, {});
     try {
-      serializer.fromJSON(templateMark);
-      return templateMark;
+      serializer.fromJSON(templateMark, {});
     } catch (err) {
       throw new Error(`Generated invalid agreement: ${err}: ${JSON.stringify(templateMark, null, 2)}`);
     }
+    const errors = [];
+    const templateClass = this.templateClass;
+    const guardBlockPaths = /* @__PURE__ */ new Map();
+    traverse(templateMark).forEach(function(node) {
+      if (!node || typeof node !== "object" || !node.$class) return;
+      const currentPath = this.path.join("/");
+      if (OPTIONAL_DEFINITION_RE.test(node.$class) || CONDITIONAL_DEFINITION_RE.test(node.$class) || WITH_DEFINITION_RE.test(node.$class)) {
+        guardBlockPaths.set(node.name, currentPath);
+      }
+      if (VARIABLE_DEFINITION_RE.test(node.$class) || ENUM_VARIABLE_DEFINITION_RE.test(node.$class) || FORMATTED_VARIABLE_DEFINITION_RE.test(node.$class)) {
+        const propName = node.name;
+        if (propName && propName !== "this") {
+          try {
+            const property = templateClass.getProperty(propName);
+            if (property && property.isOptional()) {
+              const guardPath = guardBlockPaths.get(propName);
+              const isGuarded = guardPath !== void 0 && (currentPath === guardPath || currentPath.startsWith(guardPath + "/"));
+              if (!isGuarded) {
+                errors.push({
+                  propertyName: propName,
+                  message: `Optional property '${propName}' is used without a guard. Wrap it in {{#optional ${propName}}}...{{/optional}} or {{#if ${propName}}}...{{/if}}.`
+                });
+              }
+            }
+          } catch {
+          }
+        }
+      }
+    });
+    if (errors.length > 0) {
+      const errorMessage = `Optional properties used without guards: ${errors.map((e) => e.propertyName).join(", ")}`;
+      const error = new Error(errorMessage);
+      error.errors = errors;
+      throw error;
+    }
+    return templateMark;
   }
   /**
    * Compiles the code nodes containing TS to code nodes containing JS.
@@ -1014,22 +1083,22 @@ class TemplateMarkInterpreter {
     return compiler.compile(templateMark);
   }
   validateCiceroMark(ciceroMark) {
-    const modelManager = new concertoCore.ModelManager({ strict: true });
+    const modelManager = new concertoCore.ModelManager();
     modelManager.addCTOModel(markdownCommon.ConcertoMetaModel.MODEL, "concertometamodel.cto");
     modelManager.addCTOModel(markdownCommon.CommonMarkModel.MODEL, "commonmark.cto");
     modelManager.addCTOModel(markdownCommon.CiceroMarkModel.MODEL, "ciceromark.cto");
     const factory = new concertoCore.Factory(modelManager);
-    const serializer = new concertoCore.Serializer(factory, modelManager);
+    const serializer = new concertoCore.Serializer(factory, modelManager, {});
     try {
-      return serializer.fromJSON(ciceroMark);
+      return serializer.fromJSON(ciceroMark, {});
     } catch (err) {
       throw new Error(`Generated invalid agreement: ${err}: ${JSON.stringify(ciceroMark, null, 2)}`);
     }
   }
   async generate(templateMark, data, options) {
     const factory = new concertoCore.Factory(this.modelManager);
-    const serializer = new concertoCore.Serializer(factory, this.modelManager);
-    const templateData = serializer.fromJSON(data);
+    const serializer = new concertoCore.Serializer(factory, this.modelManager, {});
+    const templateData = serializer.fromJSON(data, {});
     if (templateData.getFullyQualifiedType() !== this.templateClass.getFullyQualifiedName()) {
       throw new Error(`Template data must be of type '${this.templateClass.getFullyQualifiedName()}'.`);
     }
@@ -1078,7 +1147,7 @@ class TemplateArchiveProcessor {
    * @param {object} request - the request to send to the template logic
    * @param {object} state - the current state of the template
    * @param {[string]} currentTime - the current time, defaults to now
-   * @param {[number]} utcOffset - the UTC offer, defaults to zero
+   * @param {[number]} utcOffset - the UTC offset, defaults to zero
    * @returns {Promise} the response and any events
    */
   async trigger(data, request, state, currentTime, utcOffset) {
@@ -1098,6 +1167,8 @@ class TemplateArchiveProcessor {
         const result = compiler.compile(code);
         compiledCode[tsFile.getIdentifier()] = result;
       }
+      const resolvedTime = currentTime ?? (/* @__PURE__ */ new Date()).toISOString();
+      const resolvedOffset = utcOffset ?? 0;
       const evaluator = new JavaScriptEvaluator();
       const evalResponse = await evaluator.evalDangerously({
         templateLogic: true,
@@ -1106,7 +1177,7 @@ class TemplateArchiveProcessor {
         code: compiledCode["logic/logic.ts"].code,
         // TODO DCS - how to find the code to run?
         argumentNames: ["data", "request", "state"],
-        arguments: [data, request, state, currentTime, utcOffset]
+        arguments: [data, request, state, resolvedTime, resolvedOffset]
       });
       if (evalResponse.result) {
         return evalResponse.result;
@@ -1120,8 +1191,8 @@ class TemplateArchiveProcessor {
   /**
    * Init the logic of a template
    * @param {[string]} currentTime - the current time, defaults to now
-   * @param {[number]} utcOffset - the UTC offer, defaults to zero
-   * @returns {Promise} the response and any events
+   * @param {[number]} utcOffset - the UTC offset, defaults to zero
+   * @returns {Promise<InitResponse>} the new state
    */
   async init(data, currentTime, utcOffset) {
     const logicManager = this.template.getLogicManager();
@@ -1140,6 +1211,8 @@ class TemplateArchiveProcessor {
         const result = compiler.compile(code);
         compiledCode[tsFile.getIdentifier()] = result;
       }
+      const resolvedTime = currentTime ?? (/* @__PURE__ */ new Date()).toISOString();
+      const resolvedOffset = utcOffset ?? 0;
       const evaluator = new JavaScriptEvaluator();
       const evalResponse = await evaluator.evalDangerously({
         templateLogic: true,
@@ -1148,7 +1221,7 @@ class TemplateArchiveProcessor {
         code: compiledCode["logic/logic.ts"].code,
         // TODO DCS - how to find the code to run?
         argumentNames: ["data"],
-        arguments: [data, currentTime, utcOffset]
+        arguments: [data, resolvedTime, resolvedOffset]
       });
       if (evalResponse.result) {
         return evalResponse.result;