@accordproject/template-engine 2.7.1 → 2.9.0

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
@@ -125,9 +150,9 @@ TemplateMark JSON is a well-defined file format, meaning that powerful template
 
 We encourage community and commercial innovation in this area!
 
-### 3. Logic FULL
+### 3. Full Logic Support
 
-Unlike some templating systems which prohibit, or minmize, logic in templates, Accord Project templates fully embrace templates that may contain sophisticated logic: conditional logic to determine what text to include, or even calculations, for example to calculate the monthly payments for a mortgage based on the term of the mortgage, the amount and the interest rate.
+Unlike some templating systems which prohibit, or minimize, logic in templates, Accord Project templates fully embrace templates that may contain sophisticated logic: conditional logic to determine what text to include, or even calculations, for example to calculate the monthly payments for a mortgage based on the term of the mortgage, the amount and the interest rate.
 
 ### 4. Type-safety
 

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:
@@ -910,7 +924,12 @@ async function generateAgreement(modelManager, clauseLibrary, templateMark, data
         delete context.dependencies;
         delete context.functionName;
       } else if (CLAUSE_DEFINITION_RE.test(nodeClass)) {
-        if (context.condition) {
+        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) {
           checkCode(context.condition);
           const result = !!userCodeResults[this.path.join("/")];
           if (!result) {
@@ -973,10 +992,45 @@ class TemplateMarkInterpreter {
     const serializer = new concertoCore.Serializer(factory, modelManager);
     try {
       serializer.fromJSON(templateMark);
-      return 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.