@accordproject/template-engine 3.1.0 → 4.2.1

package/README.md

@@ -180,6 +180,47 @@ Note that this module is primarily intended for tool authors, or developers embe
 npm install @accordproject/template-engine --save
 ```
 
+Requires Node.js >= 22.
+
+## Browser usage
+
+The package is published with two entry points:
+
+- `lib/index.js` — the Node.js build (`tsc` output, typed via `lib/index.d.ts`).
+- `umd/template-engine.js` — a pre-built UMD browser bundle (referenced by the `browser`
+  field, so bundlers pick it up automatically for web builds).
+
+The full author-and-run loop works **in the browser** — parse a template to TemplateMark,
+type-check it, compile its embedded TypeScript logic to JavaScript, and evaluate it — which
+is what powers the [Template Playground](https://playground.accordproject.org). For
+convenience the bundle also re-exports `ModelManager` (concerto) and `TemplateMarkTransformer`
+(markdown-template), so a single bundle can run the whole `model -> template -> agreement` flow
+with one concerto instance:
+
+```html
+<script src="https://unpkg.com/@accordproject/template-engine/umd/template-engine.js"></script>
+<script>
+  const { ModelManager, TemplateMarkTransformer, TemplateMarkInterpreter } = window['template-engine'];
+  const modelManager = new ModelManager();
+  modelManager.addCTOModel('namespace test@1.0.0\n@template\nconcept TemplateData { o String name }');
+  const templateMark = new TemplateMarkTransformer()
+    .fromMarkdownTemplate({ content: 'Hello {{name}}!' }, modelManager, 'contract');
+  const engine = new TemplateMarkInterpreter(modelManager, {});
+  const agreement = await engine.generate(templateMark, { $class: 'test@1.0.0.TemplateData', name: 'World' });
+</script>
+```
+
+Notes on browser limitations:
+
+- Logic that imports **arbitrary** 3rd-party packages must be shipped as a **compiled archive**
+  (JavaScript logic, dependencies already bundled — produced offline in Node.js). In the browser,
+  source archives (TypeScript logic) compile against a fixed set of supported runtime dependencies.
+- `Template.fromDirectory()`/`fromUrl()` and child-process logic evaluation are Node-only; in the
+  browser load templates via `Template.fromArchive(buffer)` and use the default in-process evaluator.
+
+The browser bundle is exercised by the Playwright tests in the `e2e/` workspace, which load
+`umd/template-engine.js` into a headless Chromium and run a real `generate()`.
+
 ## License <a name="license"></a>
 Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/.
 

package/lib/JavaScriptEvaluator.d.ts

@@ -0,0 +1,71 @@
+import { EventEmitter } from 'node:events';
+export type EvalOptions = {
+    timeout: number;
+};
+export type EvalRequest = {
+    verbose?: boolean;
+    templateLogic?: boolean;
+    code: string;
+    functionName?: string;
+    argumentNames: string[];
+    arguments: any[];
+};
+type WorkItem = {
+    pid?: number;
+    startTime: number;
+    expireTime: number;
+    request: EvalRequest;
+    resolve: (result: any) => void;
+    reject: (result: any) => void;
+};
+export type EvalResponse = {
+    result: any;
+    timeout?: boolean;
+    starvation?: boolean;
+    message?: string;
+    stack?: string;
+    elapsed?: number;
+    maxQueueDepthExceeded?: boolean;
+};
+export type JavaScriptEvaluatorOptions = {
+    waitInterval: number;
+    maxWorkers: number;
+    maxQueueDepth: number;
+};
+type ChildProcess = {
+    pid?: number;
+} & EventEmitter;
+export declare const dynamicImport: <T>(path: string, symbol?: string) => Promise<any>;
+/**
+ * This class implements two JS function evaluation strategies:
+ * 1. evalDangerously which creates a dynamic function and run it in-process
+ * This should only be used with trusted code, or within a sandbox (e.g. the browser)
+ * 2. evalChildProcess which spins up a child Node process to eval the function
+ * The maximum number of child processes is capped via JavaScriptEvaluatorOptions
+ * as well as the maximum queue depth for the queue used to wait for a free worker
+ * child process. Not that to prevent cross-request contamination
+ * child processes are NOT pooled and are never reused.
+ */
+export declare class JavaScriptEvaluator {
+    options: JavaScriptEvaluatorOptions;
+    workers: Array<ChildProcess>;
+    queue: Array<WorkItem>;
+    constructor(options?: JavaScriptEvaluatorOptions);
+    /**
+     * Evaluates a JS function in process.
+     * @param {EvalRequest} request - the eval request
+     * @returns {Promise} a promise to the result
+     */
+    evalDangerously(request: EvalRequest): Promise<EvalResponse>;
+    /**
+     * Evaluates a JS function using a node child process
+     * @param {EvalRequest} request the eval request
+     * @param {EvalOptions} options the options for the request
+     * @returns {Promise<EvalResponse>} the async result
+     */
+    evalChildProcess(request: EvalRequest, options?: EvalOptions): Promise<EvalResponse>;
+    private processQueue;
+    private getWorkerPath;
+    private doWork;
+}
+export {};

package/lib/JavaScriptEvaluator.js

@@ -0,0 +1,245 @@
+"use strict";
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JavaScriptEvaluator = exports.dynamicImport = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const child_process_1 = __importDefault(require("child_process"));
+const jsonpath_1 = __importDefault(require("jsonpath"));
+const dayjs_1 = __importDefault(require("dayjs"));
+const path_1 = __importDefault(require("path"));
+async function sleep(msec) {
+    return new Promise(resolve => setTimeout(resolve, msec));
+}
+// we use this to import modules because it's an ESM module and direct imports won't work...
+// see: https://github.com/TypeStrong/ts-node/discussions/1290
+const _import = async (path) => new Function('specifier', 'return import(specifier)')(path);
+// we create a wrapper for the _import above and returns the `default` exported method/function/symbol
+// inferred by the module name or a custom one base on user preferences...
+const dynamicImport = async (path, symbol) => {
+    const mod = await _import(path);
+    return symbol ? mod.symbol : mod.default;
+};
+exports.dynamicImport = dynamicImport;
+/**
+ * This class implements two JS function evaluation strategies:
+ * 1. evalDangerously which creates a dynamic function and run it in-process
+ * This should only be used with trusted code, or within a sandbox (e.g. the browser)
+ * 2. evalChildProcess which spins up a child Node process to eval the function
+ * The maximum number of child processes is capped via JavaScriptEvaluatorOptions
+ * as well as the maximum queue depth for the queue used to wait for a free worker
+ * child process. Not that to prevent cross-request contamination
+ * child processes are NOT pooled and are never reused.
+ */
+class JavaScriptEvaluator {
+    constructor(options = { waitInterval: 50, maxWorkers: 8, maxQueueDepth: 1000 }) {
+        this.options = options;
+        this.workers = [];
+        this.queue = [];
+    }
+    /**
+     * Evaluates a JS function in process.
+     * @param {EvalRequest} request - the eval request
+     * @returns {Promise} a promise to the result
+     */
+    async evalDangerously(request) {
+        return new Promise((resolve, reject) => {
+            try {
+                if (request.verbose) {
+                    console.log(request.code);
+                }
+                const start = new Date().getTime();
+                let result = null;
+                // is this a simple JS function?
+                if (!request.templateLogic) {
+                    const fun = new Function(...['dayjs', 'jp', ...request.argumentNames], request.code);
+                    result = fun(...[dayjs_1.default, jsonpath_1.default, ...request.arguments]);
+                    const end = new Date().getTime();
+                    resolve({ result, elapsed: end - start });
+                }
+                else {
+                    // this is a template logic esm module, so we need to dynamic import it
+                    const dataUri = 'data:text/javascript;base64,'
+                        + btoa(request.code);
+                    (0, exports.dynamicImport)(dataUri)
+                        .then(templateLogicConstructor => {
+                        const instance = new templateLogicConstructor();
+                        if (!request.functionName) {
+                            throw new Error('No function name specified for template logic');
+                        }
+                        result = instance[request.functionName](...request.arguments);
+                        const end = new Date().getTime();
+                        resolve({ result, elapsed: end - start });
+                    })
+                        .catch(err => {
+                        console.error(err);
+                        if (err instanceof Error) {
+                            reject({
+                                message: err.message,
+                                stack: err.stack,
+                            });
+                        }
+                        else {
+                            reject({
+                                message: String(err),
+                            });
+                        }
+                    });
+                }
+            }
+            catch (err) {
+                console.error(err);
+                if (err instanceof Error) {
+                    reject({
+                        message: err.message,
+                        stack: err.stack,
+                    });
+                }
+                else {
+                    reject({
+                        message: String(err),
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Evaluates a JS function using a node child process
+     * @param {EvalRequest} request the eval request
+     * @param {EvalOptions} options the options for the request
+     * @returns {Promise<EvalResponse>} the async result
+     */
+    async evalChildProcess(request, options = { timeout: 10000 }) {
+        // console.log('Workers count: ' + this.workers.length);
+        return new Promise((resolve, reject) => {
+            const now = new Date().getTime();
+            const workItem = {
+                startTime: now,
+                expireTime: now + options.timeout,
+                request,
+                resolve,
+                reject
+            };
+            if (this.queue.length >= this.options.maxQueueDepth) {
+                reject({ maxQueueDepthExceeded: true, elapsed: 0 });
+                return;
+            }
+            this.queue.push(workItem);
+            this.processQueue(options);
+        });
+    }
+    processQueue(options) {
+        const now = new Date().getTime();
+        const notExpired = this.queue.filter(w => (now < w.expireTime));
+        const expired = this.queue.filter(w => (now >= w.expireTime));
+        this.queue = notExpired;
+        expired.forEach(w => {
+            w.reject({ timeout: true, starvation: true, elapsed: now - w.startTime });
+        });
+        if (this.workers.length < this.options.maxWorkers) {
+            // we have a free worker
+            const next = this.queue.shift();
+            if (next) {
+                this.doWork(next, options)
+                    .then(result => next.resolve(result))
+                    .catch(error => next.reject(error));
+            }
+        }
+        else {
+            // no free worker, so sleep and then try again
+            sleep(this.options.waitInterval)
+                .then(() => {
+                this.processQueue(options);
+            });
+        }
+    }
+    getWorkerPath() {
+        try {
+            const thisPath = require.resolve('@accordproject/template-engine');
+            return path_1.default.join(thisPath, '..', 'worker.js');
+        }
+        catch (err) { // eslint-disable-line @typescript-eslint/no-unused-vars
+            // if we cannot load the module it likely means we are running
+            // a unit test inside the module...
+            return path_1.default.join(__dirname, '..', 'lib', 'worker.js');
+        }
+    }
+    doWork(work, options) {
+        return new Promise((resolve, reject) => {
+            const start = new Date().getTime();
+            // check for browser
+            if (!child_process_1.default.fork) {
+                reject({ message: 'Cannot use evalChildProcess because child_process.fork is not defined.' });
+            }
+            // on timeout will send SIGTERM
+            const workerPath = this.getWorkerPath();
+            // console.debug(`Worker path: ${workerPath}`);
+            const worker = child_process_1.default.fork(workerPath, { timeout: options.timeout, env: {} });
+            if (worker.pid === undefined || worker.pid === null) {
+                throw new Error('Failed to fork child process');
+            }
+            this.workers.push(worker);
+            work.pid = worker.pid;
+            let result;
+            worker.on('error', (err) => {
+                this.workers = this.workers.filter((w) => w.pid !== worker.pid);
+                const end = new Date().getTime();
+                if (err instanceof Error) {
+                    reject({
+                        message: err.message,
+                        stack: err.stack,
+                        elapsed: end - start
+                    });
+                }
+                else {
+                    reject({
+                        message: String(err),
+                        elapsed: end - start
+                    });
+                }
+            });
+            worker.on('message', (msg) => {
+                result = msg;
+            });
+            worker.on('exit', (code) => {
+                if (code === null) {
+                    // timeout
+                    this.workers = this.workers.filter((w) => w.pid !== worker.pid);
+                    const end = new Date().getTime();
+                    reject({ timeout: true, elapsed: end - start });
+                }
+                else if (code === 0 && result) {
+                    // success!
+                    this.workers = this.workers.filter((w) => w.pid !== worker.pid);
+                    const end = new Date().getTime();
+                    resolve({ ...result, elapsed: end - start });
+                }
+                else {
+                    // null result or non-zero code from worker means an error
+                    // result will be undefined if the user code calls process.exit()
+                    this.workers = this.workers.filter((w) => w.pid !== worker.pid);
+                    const end = new Date().getTime();
+                    reject({ code, result, elapsed: end - start });
+                }
+            });
+            // send the request to the child process
+            worker.send(work.request);
+        });
+    }
+}
+exports.JavaScriptEvaluator = JavaScriptEvaluator;
+//# sourceMappingURL=JavaScriptEvaluator.js.map

package/lib/JavaScriptEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JavaScriptEvaluator.js","sourceRoot":"","sources":["../src/JavaScriptEvaluator.ts"],"names":[],"mappings":"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"}

package/lib/TemplateArchiveProcessor.d.ts

@@ -0,0 +1,151 @@
+import { Template } from '@accordproject/cicero-core';
+import { TwoSlashReturn } from '@typescript/twoslash';
+import { LLMExecutorConfig } from './llm/LLMConfig';
+/** The contract state. */
+export type State = object;
+/** A response/result returned by the contract logic. */
+export type Response = object;
+/** An event emitted by the contract logic. */
+export type Event = object;
+/** The result of triggering a template: the response, updated state, and events. */
+export type TriggerResponse = {
+    result: Response;
+    state: State;
+    events: Event[];
+};
+/** The result of initializing a template: the initial state. */
+export type InitResponse = {
+    state: State;
+};
+/**
+ * A template archive processor: can draft content using the
+ * templatemark for the archive and trigger the logic of the archive
+ */
+export declare class TemplateArchiveProcessor {
+    /** The template used by the processor. */
+    template: Template;
+    /** Cache of compiled logic, keyed by script identifier. */
+    private compiledLogicCache?;
+    /** Optional LLM fallback configuration. */
+    llmConfig?: LLMExecutorConfig;
+    /** Lazily-created LLM executor reused across debug/init/trigger calls. */
+    private llmExecutor?;
+    /**
+     * Creates a template archive processor
+     * @param {Template} template - the template to be used by the processor
+     * @param {LLMExecutorConfig} [llmConfig] - optional LLM fallback configuration
+     */
+    constructor(template: Template, llmConfig?: LLMExecutorConfig);
+    /**
+     * Drafts a template by merging it with data
+     * @param {any} data the data to merge with the template
+     * @param {string} format the output format
+     * @param {any} options merge options
+     * @param {[string]} currentTime the current value for 'now'
+     * @returns {Promise} the drafted content
+     */
+    draft(data: any, format: string, options: any, currentTime?: string): Promise<any>;
+    /**
+     * Compile the logic of a template
+     * @param {boolean} [enableCompiledLogicCache] - whether to cache the compiled logic for future use
+     * @returns {Promise<Record<string, TwoSlashReturn>>} the compiled code for each typescript file
+     */
+    compileLogic(enableCompiledLogicCache?: boolean): Promise<Record<string, TwoSlashReturn>>;
+    /**
+     * Asserts that a runtime payload's declared type is, or extends, the given runtime
+     * base type. This enforces the runtime class hierarchy nominally (by `$class`), which
+     * the type system cannot: request is a bivariant `trigger` parameter, and State's
+     * generated interface is structurally satisfied by any identified concept. Using the
+     * model's own assignability, the bare base type and any subclass are accepted while a
+     * plain concept that does not extend the base is rejected.
+     * @param {any} payload - a serialized Concerto object (has a `$class`), or undefined
+     * @param {string} baseFqn - the fully-qualified name of the runtime base type
+     * @param {string} role - the payload's role, used in the error message
+     * @throws {Error} if the payload's type is not the base type or a subclass of it
+     */
+    private assertRuntimeHierarchy;
+    /**
+     * Populates the `contract` back-reference that `org.accordproject.runtime.Obligation`
+     * (and therefore any event that extends it, e.g. a template's `PaymentObligationEvent`)
+     * requires, so that template logic never has to set it explicitly.
+     *
+     * Only events whose `contract` field is not already set are touched, so template logic
+     * that deliberately points an obligation at a different contract is left alone. Filling
+     * the field in is only meaningful when the template's own data model is itself a
+     * `Contract` (or a subtype of it) - that's the only instance in scope at `trigger()` time
+     * that the relationship is allowed to point to. The `Serializer` this class uses is
+     * constructed with `acceptResourcesForRelationships: true`, so handing it the full `data`
+     * resource is enough for it to resolve the relationship from that resource's own
+     * `$class`/identifier.
+     * @param {Event[]} events - the events returned by the template logic, mutated in place
+     * @param {any} data - the contract/clause data instance passed into trigger()
+     * @throws {Error} if an Obligation-derived event is missing `contract` and the template's
+     * data model does not extend Contract, so there is nothing valid to auto-populate with
+     */
+    private populateObligationBackReferences;
+    private assertTemplateLogicSubclass;
+    /**
+     * Determines whether LLM fallback is enabled.
+     * @returns {boolean} true if an LLM config is present and not disabled
+     */
+    private shouldUseLLM;
+    /**
+     * Constructs an LLM executor for this template.
+     * @returns {LLMExecutor} the LLM executor
+     * @throws {Error} if no LLM config is present
+     */
+    private makeLLMExecutor;
+    /**
+     * Executes the template's compiled TypeScript trigger logic.
+     * @param {any} data - the data for the template
+     * @param {any} request - the request to send to the template logic
+     * @param {any} [priorState] - the state produced by init() (or a previous
+     * trigger()); required for stateful templates, ignored for stateless ones
+     * @param {string} [currentTime] - the current time, defaults to now
+     * @param {number} [utcOffset] - the UTC offset, defaults to zero
+     * @returns {Promise<TriggerResponse>} the response and any events
+     */
+    private executeTypeScriptTrigger;
+    /**
+     * Executes the template's compiled TypeScript init logic. Returns an empty
+     * state when the compiled logic defines no `init` method (stateless template).
+     * @param {any} data - the data for the template
+     * @param {string} [currentTime] - the current time, defaults to now
+     * @param {number} [utcOffset] - the UTC offset, defaults to zero
+     * @returns {Promise<InitResponse>} the new state
+     */
+    private executeTypeScriptInit;
+    /**
+     * Trigger the logic of a template.
+     *
+     * Stateful templates (`this.template.isStateful()`) carry state across
+     * executions, so they must always be seeded with `priorState` — the state
+     * returned by a prior call to {@link init} (or by a prior call to
+     * `trigger`) — before a request can be evaluated. There is no implicit
+     * "empty" state for a template that declares custom State fields; calling
+     * `trigger` without `priorState` for such a template throws. Stateless
+     * templates ignore `priorState` entirely.
+     * @param {object} data - the data for the template
+     * @param {object} request - the request to send to the template logic
+     * @param {object} priorState - the state to evaluate the request against.
+     * For stateful templates this is required and must be the state produced
+     * by init() or a previous trigger(); for stateless templates it is ignored.
+     * @param {[string]} currentTime - the current time, defaults to now
+     * @param {[number]} utcOffset - the UTC offset, defaults to zero
+     * @param {boolean} [enableCompiledLogicCache] - whether to use the compiled logic cache
+     * @returns {Promise<TriggerResponse>} the response and any events
+     * @throws {Error} if the template is stateful and no priorState is supplied, or if an
+     * emitted event extends `org.accordproject.runtime.Obligation` and its `contract`
+     * back-reference can't be auto-populated (see {@link populateObligationBackReferences})
+     */
+    trigger(data: any, request: any, priorState?: any, currentTime?: string, utcOffset?: number, enableCompiledLogicCache?: boolean): Promise<TriggerResponse>;
+    /**
+     * Init the logic of a template.
+     * @param {object} data - the data for the template
+     * @param {[string]} currentTime - the current time, defaults to now
+     * @param {[number]} utcOffset - the UTC offset, defaults to zero
+     * @param {boolean} [enableCompiledLogicCache] - whether to use the compiled logic cache
+     * @returns {Promise<InitResponse>} the new state
+     */
+    init(data: any, currentTime?: string, utcOffset?: number, enableCompiledLogicCache?: boolean): Promise<InitResponse>;
+}